Aimsun Next Scripting

Introduction

Aimsun Next is, from a programmer's point of view, an extensible environment in which new functionality can be added.

Conceptually it is divided into two main parts, kernel and UI:

• Kernel – This is the non-visible part. It includes an extensible database to hold any kind of information, a representation of this database in memory and a collection of classes and functions (called methods in C++) to access and modify such information.
• User interface (UI) – The graphical representation of the kernel. It includes 2D and 3D views, editors, printing support, etc.

Aimsun Next has four different means of extending both the kernel and the UI, each with a different purpose:

• Scripting: Python scripts have access to part of the kernel and the UI. Scripting is aimed at automating some operations that could also be done manually with the UI.

• Microsimulator API: Using the API it is possible to program operations that run during the microsimulation by changing control timings or vehicle parameters. The API is typically used in simulating advanced traffic management systems (ATMS).

• Microsimulator Software Development Kit: Using the microSDK it is possible to develop new microscopic simulation models (car-following, lane-changing, etc.) replacing those included in the Aimsun Next microsimulator. The microSDK uses C++.

• Platform Software Development Kit: The Aimsun Next software development kit or platformSDK, is a collection of UI widgets, libraries, and documents that enables new applications to be included in Aimsun Next. The platformSDK uses C++.

Scripting

This section of the manual focuses on scripting, using the Python language to perform operations with the subset of UI and kernel classes exposed by the software.

Its main aim is to describe which Aimsun classes are available and how to use their methods. It includes examples that will introduce the effective use of scripting. It also explains best practices: what is allowed, what is not allowed and what is the best way to perform common tasks.

Typical tasks that might be performed with scripting are:

• modifying the model
• importing or exporting data
• performing calculations with model data
• modifying the metadata model.

Teaching Python programming is beyond the scope of this manual; however, there is a brief introduction in Python programming, along with an introduction to the Object Oriented programming paradigm.

Requirements

Python

Aimsun Next scripting uses a Python engine embedded in Aimsun Next version 6 onwards. This means that you don't need to manually install Python 3 in order to write and execute scripts within Aimsun Next.

However, if you need to use additional libraries you will need to install Python version 3 so that Aimsun Next can use the external Python interpreter, which has access to all the installed libraries.

You can downloaded Python 3 from the Python website. Always choose the most recent version of Python 3 available.

Importing additional modules

To import additional modules, such as xlrd or win32client for 64bit applications, first install Python 3 and then install the appropriate module (see the example below).

Note: In Windows OS, define the paths with "/" instead of backslashes, otherwise attempts to load the library will fail.

Installing a 3rd-party Python library/module

This procedure explains how to install Python and get access to a 3rd-party Python library.

1. Install Aimsun Next Python 3.
2. Install Python 3 from the Python website.
3. Install the Python Additional Module from a command line, using, for example: python -m pip install $PYTHON_LIBRARY_NAME (let's use "matplotlib" in our example).
4. Define the Environmental Variable PYTHONPATH with the value where pip saved the installation. This path was displayed after performing step 3. In Windows OS you can define this in System Properties > Environmental Variables > System Variables > New > Variable Name. Input PYTHONPATH and Variable Value: PATH using the path where the $PYTHON_LIBRARY_NAME was installed.

5. Open Aimsun Next and create and run the following (example) Python script (# = comments in the script):

   #Import the necessary packages and modules
   import matplotlib.pyplot as plt
   import numpy as np
   #Prepare the data
   x = np.linspace(0, 10, 100)
   #Plot the data
   plt.plot(x, x, label='linear')
   #Add a legend
   plt.legend()
   #Show the plot
   plt.show()
   

Qt data types

Most methods in Aimsun Next scripting use or return data in Qt containers, such as QDate, QTime, etc. Descriptions of the subset of Qt data types used by Aimsun Next are available at the Qt Project website.

Related topics

Extensible Metadata Model Editing and Running a Script User Interaction and Error Handling Scripting Examples Script Library Programming for Scripts