Advanced Aimsun API Programming (1)
This post has already been read 2195 times!
Aimsun MicroAPIs are the programming interface of Aimsun microscopic traffic simulator. These APIs provided 10 predefined call back hooks, together with various other utility functions.
MicroAPIs allow advanced users to implement sophisticated external logic, for example, non-standard ramp metering, advanced traffic management strategies, adaptive signal control etc.. These are not readily available with standard off-the-shelf Aimsun features, but made possible with Aimsun MicroAPIs.
The Aimsun MicroAPIs are very flexible, as its final product is in the format of a Dynamic Link Library (DLL). The DLL is loaded by Aimsun host during run time before running a simulation replication, and unloaded after the simulation replication finishes. The supported programming language is C++ and Python. But a developer with sufficient knowledge of DLL programing can easily port the development in other languages such as Delphi, C#, Java, Fortran, if he or she desires so.
One nuance about Aimsun MicroAPIs programming is the granular control level down to a single simulation step. This is no surprise since Aimsun Micro is a time-discretized space continuous simulator that all the simulation events have to be driven by incrementing simulation steps. However, this might pose some programming challenges or certain pitfalls when multi-threading is involved, or when a TCP/IP based client-server structure is employed. The tricky point is that at the simulation step level, the control of flow is transferred from Aimsun host to MicroAPI DLL, while NOT until the call back finishes, Aimsun host is essentially “blocked”. This could possibly counter-balance any benefits obtained from the multi-threaded code implemented inside the API logic.
Overall, Aimsun MicroAPIs include two types of functions:
- Predefined DLL Exported Functions (hooks to the Aimsun Host);
- Utility Functions provided by the Aimsun Host to retrieve various run time information.
The utility functions can be further classified into three categories:
- External Control Interface Functions for traffic signal control (ramp metering, intersection signal control etc). These functions are usually prefixed with ECI, for example, ECIChangeParametersFlowAlineaMeteringById;
- Aimsun NG Objects Connection Interface Functions for accessing properties of Aimsun internal objects. These functions are usually prefixed with ANGConn, for example, ANGConnActivatePolicy;
- Aimsun Kernel Interface Functions to retrieve other simulation run time information. These functions are usually prefixed with AKI, for example, AKIDetGetDensityAggregatedbyId.
As mentioned above, Aimsun MicroAPIs provided 10 predefined call-back functions (hooks). These functions are exported by the MicroAPI DLL, so that the Aimsun host can load the DLL and call these functions at appropriate time during simulation. It is the task of the MicroAPI developers to design the external logic and implement the logic under the framework of these functions properly.
In a nutshell, Aimsun host will call back these functions on the following events:
- The MicroAPI DLL is loaded or unloaded by the Aimsun host;
- The external logic is registered with the Aimsun host;
- Before running, or after finishing the simulation;
- Before or after a simulation step is executed;
- A vehicle enters or exits the transportation network;
- Before a route choice calculation is performed.
In addition to the 10 predefined call-backs (See Table 1 below) exported by the MicroAPI DLL, there are also many utility functions exported by the Aimsun host. This renders two way communication between the MicroAPI DLL and the Aimsun host for exchanging of information and control.
As to be explained in future post, Aimsun’s two way communication is quite different from VISSIM, another popular traffic simulator developed and marketed by the Germany company PTV AG. VISSIM also provides various APIs, e.g., VISSIM external driver APIs, VISSIM signal control APIs etc. Particularly, VISSIM provides an automation mechanism by virtue of Microsoft’s COM technology. Regardless, in terms of APIs, VISSIM is merely one way communication. The pros and cons of these two types of interfaces will be discussed later.
To use the utility functions exported by the Aimsun host, “angext.lib” must be specified for the linker. However, for some reason, the corresponding DLLis not named angext.dll, but a2kernel.dll.
The following table summaries the 10 predefined call-backs.
This post has already been read 2195 times!