By Dimitris Triantafyllos
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.
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:
In a microscopic simulation (or in the microscopic area of a hybrid meso-micro simulation), you can:
In a mesoscopic simulation, you can:
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
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
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”).