Aimsun Next 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.

This section presents all topics related to the Aimsun Next Scripting:

• Updating Scripts For Newer Versions

• Aimsun Next Architecture

• Extensible Metadata Model

• Editing and Running a Script

• User Interaction and Error Handling

• Scripting Examples

• Script Library

• Programming for Scripts

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 download 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.