Empower the Aimsun Next simulation with Aimsun Advanced Programming Interface (API)

Enriching Aimsun Next simulations with the Advanced Programming Interface (API)

Technical Note #65

By Dimitris Triantafyllos

December 2021

What is the Aimsun Next API?

The Aimsun Next API is a collection of functions, in Python or C++, that let you read information and perform actions during a mesoscopic, microscopic or hybrid mesoscopic-microscopic simulation. With the API, you can make changes while the simulation is running whereas with scripting, you have to make any changes before the simulation starts.

You can also use the API to connect an external application to the simulation. Internally, within Aimsun Next, the API can communicate with the simulation engine, and externally, with the external application.

Where to use the Aimsun Next API?

The most common application of the Aimsun Next API is to emulate Intelligent Transportation Systems (ITS), Advanced Driver Assistance Systems (ADAS) and Connected Vehicle (CV) applications: for example, implementing custom transit signal priority and adaptive traffic control algorithms; applying traffic management on the fly; controlling vehicle driving behavioral parameters etc. The functionality that the API provides depends on the simulation engine:

In both mesoscopic and microscopic simulations, you can:

Read the output statistics,
Read the state of the traffic signals,
Change the state of the traffic signals.

In a microscopic simulation (or in the microscopic area of a hybrid meso-micro simulation), you can:

Read the detector data,
Read the state of individual vehicles (origin, destination, behavioral parameters, current path, position, speed, acceleration etc.),
Introduce new vehicles,
Take control of vehicles (set position and speed, change their destination or their path),
Trigger traffic management actions.

In a mesoscopic simulation, you can:

Read the state of individual vehicles (origin, destination, current section or turn, entrance time, exit time)
Introduce new vehicles.

Example: implement a Connected Vehicle application by controlling the vehicles via API

In the following example we will use API to control the speed and the lane of the vehicles approaching a merge. This represents a very simple (probably simplistic) implementation of a cooperative merge application for Connected Vehicles.

Step 1: We set all vehicles entering the section upstream of the merge as tracked so that we can modify their speed and target lane when needed. This is accomplished by calling the function

				
					int AKIVehSetAsTracked(int aidVeh)

in the AAPIEnterVehicleSection callback

Step 2: At every simulation step we get the number of vehicles on the selected sections using the following function:

				
					int AKIVehStateGetNbVehiclesSection(int aidSec, bool considerAllSegments)

Step 3: Then we read the state of those vehicles using

				
					int AKIVehStateGetVehicleInfSection(int aidSec, int indexveh)

Step 4: Next we modify the speed of the vehicles upstream of the merge with

				
					int AKIVehTrackedModifySpeed(int aidVeh, double newSpeed)

Note that this function only allows you to set a speed that is lower than the speed calculated by the car-following model. If you don’t want to be constrained by the car-following speed, you can use instead the following function:

				
					int AKIVehTrackedForceSpeed (int aidVeh, double newSpeed)

Step 5: In the section of the merge, we set the leftmost lane as target lane by calling

				
					AKIVehTrackedModifyLane (int aidVeh, int nextLane)

Step 6: When the vehicles leave the section of the merge, we set the vehicles back to non-tracked by calling

				
					int AKIVehSetAsNoTracked(int aidVeh)

in the AAPIExitVehicleSection callback

Running the sample API

Download the sample files below and ensure that all files are located in the same directory:

Aimsun file controlling-vehicles.ang
API file controlling-vehicles.py

Copy-paste the py file from Aimsun_Next_installation_folder/programming/Aimsun Next API/python/private/Micro OR Meso/AAPI.py in the same directory where the controlling-vehicles.py file is stored.

Note: Remember that the Aimsun AAPI file must be consistent with the Aimsun version currently in use. You can retrieve it here:

Aimsun_Next_installation_folder/programming/Aimsun Next API/python/private/Micro/AAPI.py

Procedure:
1. Launch Aimsun and then open the controlling-vehicles.ang file provided
2. Execute the Replication. See Log window for detailed feedback about the operation of the CACC

Step-by-step instructions to set-up the Aimsun Next API in Python

The Aimsun Next Application Programming Interface (API) extension can be implemented using a Python script. This Python script is an ASCII file (with extension: “.py”), which can be edited in any text editor. This Python script is provided with the Aimsun Next software in the Aimsun_Next_installation_folder (right-click on the Aimsun Next shortcut > Select “Open File location”).

Copy-paste the py file from Aimsun_Next_installation_folder/programming/Aimsun Next API/python/samples/Micro OR Meso/sample.py in the working directory ( it is recommended to place it in the same directory as the ANG file so that Aimsun Next can automatically recognize the relative paths if moved to a different directory.
Copy-paste the py file from Aimsun_Next_installation_folder/programming/Aimsun Next API/python/private/Micro OR Meso/AAPI.py in the same directory where the sample.py file is stored.
You may save the Python script file (py) with a name of your preference. Keep the sample.py file as back-up file in case you need to code another API.
Open the renamed Python script file. In the upper part, the AAPI module is imported to allow the interpretation of the function from C++ to Python. This module works as an interface between the Python script and Aimsun Next (interpreter with Python code and libraries). The Aimsun Next Microscopic API module has seven high level functions which communicate between the API Module and the Simulation model: AAPILoad(), AAPIInit(), AAPISimulationReady(), AAPIManage(…), AAPIPostManage(…), AAPIFinish(), AAPIUnLoad(). It also has eight additional functions that are called when certain events occur: AAPIEnterVehicle(…), AAPIExitVehicle(…), AAPIEnterVehicleSection(…), AAPIExitVehicleSection(…), AAPIPreRouteChoiceCalculation(…), AAPIVehicleStartParking(…), AAPIEnterPedestrian(…), AAPIExitPedestrian(…). For more information re the Aimsun Next Mesoscopic API, visit the Aimsun Next Manual > Aimsun Next API > Architecture > Simulation Management.
Find a complete list of functions documented in the Aimsun Next Manual to manage control plans, to apply changes in the microscopic or mesoscopic simulations. Access the Aimsun Next Manual > Aimsun Next API > Manage Control Plans/Microscopic Simulation/Mesoscopic Simulation. Also find a step-by-step instruction how to build an API as well as explore the API examples.
Start coding –
To test the coding status, load the API in the Aimsun Next, open a Dynamic Scenario
Access the tab Aimsun Next APIs
Add the py in the Aimsun Next APIs and select it.
Press OK and then right click on the Replication > Run Animated Simulation (for microscopic simulation). Now observe the printed messages of your code in the Log window (to activate the Log window, go to Main Menu > Window > Windows > Log (o).

License: Note that you need an API license to run this example. For more information, please contact info@aimsun.com

More technical notes

Exporting probe data using Aimsun micro API

July 2015: Dimitris Triantafyllos discusses how this Aimsun API allows research centres to work on the understanding of the innovative uses of probe vehicle data, available applications, visualisations, performance measures, and management techniques.