API Architecture¶

The Aimsun Next solution¶

The approach taken in Aimsun Next is to consider an Advanced Telematic Application to be tested using the model as an external application that can communicate with the simulation.

Using the Aimsun Next API functions, data from the simulated network is transferred to the external application; the application applies its own algorithms to evaluate the situation in the simulation and responds with appropriate dynamic actions to be implemented in the simulation. The process of information exchange between the simulation and the external application is shown below

Process of information exchange

The model of the road network emulates the detection process. Then, through a set of functions it provides the external application with the required "Simulation Detection Data" (e.g. flow, occupancy, etc.). The external application uses this data to evaluate its control policies and decides which control and/or management actions have to be applied on the road network. Finally, the external application sends, the corresponding actuations (e.g. change the traffic signal state, the phase duration, display a message in a VMS, etc.) to the simulation model, which then emulates their operation through the corresponding model components such as traffic signals, VMSs and ramp metering signs.

Another use of the Aimsun Next API is to access to detailed vehicle simulated data and relay it to a user developed model (e.g. fuel consumption and pollution emissions), to keep track of a guided vehicle throughout the network by an external vehicle guidance system, or to simulate the activities of vehicles such as floating cars.

Implementation¶

Introduction to Aimsun Next API¶

The Aimsun Next API module is logically positioned between the simulation model and the external application. Internally, within Aimsun Next, the API is able to communicate to the simulation module, externally, to the external application. The communication mechanism between the API functions and the application is decided by the analyst implementing the link and can range from direct programming (i.e. the code that uses the API is the external application) to a network communication protocol emulating on-street communications hardware and where the external application is a largely unmodified production system.

Schema of Aimsun Next API module

Aimsun Next Microsimulation API¶

The Aimsun Next API module has six high level functions which communicate between the Aimsun Next API Module and the Simulation model. These are: AAPILoad, AAPIInit, AAPISimulationReady, AAPIManage, AAPIPostManage, AAPIFinish, AAPIUnLoad.

It also has six additional functions that are called when certain events occur. They are: AAPIEnterVehicle and AAPIExitVehicle, AAPIEnterVehicleSection, AAPIExitVehicleSection, AAPIPreRouteChoiceCalculation and AAPIVehicleStartParking.

Simulation Management¶

Initialization Functions¶

AAPILoad ()

Called when the module is loaded by Aimsun Next.
AAPIInit ()

Called when Aimsun Next starts the simulation and can be used to initialize the module.
AAPISimulationReady ()

Called when Aimsun Next has initialized all and vehicles are ready to start moving.

Timestep Functions¶

There are two simulation functions called at every timestep AAPIManage is called before the simulator performs any actions, the simulator then does its calculations and updates vehicles and traffic lights. Finally at the end of the timestep, AAPIPostManage is called.

Hence, when the simulation timestep is evaluated, actions undertaken in AAPIManage are included and when AAPIPostManage is called, actions undertaken in both AAPIManage and the timestep are included. Actions made in AAPIPostManage of one simulation step will then be taken into account in the following simulation step. In general, it is preferable to make changes for ITS or signals in AAPIManage so that they are taken into account by vehicles in that timestep and to make changes for vehicles in AAPIPostManage so that the vehicles surrounding them are up to date with their own actions.

AAPIManage (double time, double timeSta, double timeTrans, double cycle)

Called in every simulation step at the beginning of the cycle, and can be used to request detector measures, vehicle information and interact with junctions, meterings and VMS in order to implement the control and management policy. This function takes four time related parameters:

- *time*: Absolute time of simulation in seconds. At the beginning of the simulation (beginning of the warm-up, if any), it takes the value 0.
- *timeSta*: Time of simulation in stationary period (start from Simulated Initial Time), in seconds from midnight. The value of timeSta is invalid during the warm-up period (where it will always return beginning of the stationary period).
- *timeTrans*: Duration of warm-up period, in seconds.
- *cycle*: Duration of each simulation step in seconds.

Example:

We have started a simulation at 07:00, with 5 minutes of warm-up period and we have simulated one minute with 1 second as the simulation step. Taking these values the parameters will be:

- time = 5*60 + 60 = 360.0
- timeSta = 7*3600+60 = 25260.0
- timeTrans = 5*60 = 300.0
- cycle = 1.0

AAPIPostManage (double time, double timeSta, double timeTrans, double cycle)

Called in every simulation step at the end of the cycle, and can be used to request detector measures, vehicle information and interact with junctions, meterings and VMS to implement the control and management policy. This function takes four time related parameters:
- time: Absolute time of simulation in seconds. At the beginning of the simulation (beginning of the warm-up, if any), it takes the value 0.
- timeSta: Time of simulation in stationary period (start from Simulated Initial Time), in seconds from midnight. The value of timeSta is invalid during the warm-up period (where it will always return beginning of the stationary period).
- timeTrans: Duration of warm-up period, in seconds.
- cycle: Duration of each simulation step in seconds.

Termination Functions¶

AAPIFinish ()

Called when Aimsun Next finishes the simulation and can be used to terminate the module operations, write summary information, close files, etc.
AAPIUnLoad ()

Called when the module is unloaded by Aimsun Next.

The following figure shows graphically how Aimsun Next and the API Module interact.

Scheme how Aimsun Next and the API Module interact

Simulation Events¶

AAPIEnterVehicle (int idveh, int idsection)

Called when a new vehicle enters the system, that is, when the vehicle enters its first section, not when it enters a Virtual queue if one is present. This function takes two parameters:
- idveh: Identifier of the new vehicle entering the network.
- idsection: Identifier of the section where the vehicle enters the network.
AAPIExitVehicle (int idveh, int idsection)

Called when a vehicle exits the network. This function takes two parameters:
- idveh: Identifier of the vehicle exiting the network.
- idsection: Identifier of the section where the vehicle exits the network.

AAPIEnterVehicleSection (int idveh, int idsection, double atime)

Called when a vehicle enters a new section. This function takes three parameters:

- *idveh*: Identifier of the vehicle.
- *idsection*: Identifier of the section the vehicle is entering.
- *atime*: Absolute time of the simulation when the vehicle enters the section. At the beginning of the simulation (beginning of the warm-up, if any), it takes the value 0.

AAPIExitVehicleSection (int idveh, int idsection, double atime)

Called when a vehicle exits a section. This function receives two parameters:

- *idveh*: Identifier of the vehicle.
- *idsection*: Identifier of the section the vehicle is exiting.
- *atime*: Absolute time of the simulation when the vehicle exits the section. At the beginning of the simulation (beginning of the warm-up, if any), it takes the value 0.

AAPIEnterPedestrian (int idPedestrian, int originCentroid)

Called when a new pedestrian enters the system, that is, when the pedestrian enters through its entrance. This function takes two parameters:
```
- *idPedestrian*: Identifier of the new pedestrian entering the network.
- *originCentroid*: Identifier of the pedestrian entrance where the pedestrian enters the network.
```

AAPIExitPedestrian (int idPedestrian, int destinationCentroid)

Called when a pedestrian exits the network. This function takes two parameters:

- *idPedestrian*: Identifier of the pedestrian exiting the network.
- *destinationCentroid*: Identifier of the pedestrian exit where the pedestrian exits the network.

AAPIPreRouteChoiceCalculation (double time, double timeSta)

Called just before a new cycle of route choice calculation is about to begin. It can be used to modify the sections and turnings costs to affect the route choice calculation. This function takes two parameters in relation to time:

- *time*: Absolute time of simulation in seconds. At the beginning of the simulation (beginning of the warm-up, if any), it takes the value 0.
- *timeSta*: Time of simulation in stationary period (start from Simulated Initial Time), in seconds from midnight. The value of timeSta is invalid during the warm-up period (where it will always return beginning of the stationary period).

AAPIVehicleStartParking (int idveh, int idsection, double time)

Called when a vehicle starts a parking maneuver.

    - *idveh*: Vehicle identifier.
    - *idsection*: Section identifier where vehicle is doing the parking.
    - *time*: Current simulation time.

char* AAPIInternalName ()

Returns the unique internal name of the API. It is called when registering APIs before simulation.

Aimsun Next Mesoscopic API¶

The Aimsun Next Mesoscopic API module has four high level functions which communicate between the API Module and the simulation model. These are: MesoAPILoad, MesoAPIUnLoad, MesoAPIInit, MesoAPIFinish.

It also has five additional functions that are called when certain events occur. They are: MesoAPINewVehicleSystem, MesoAPINewVehicleNetwork, MesoAPIFinishVehicleNetwork, MesoAPIEnterVehicleSection, MesoAPIExitVehicleSection and MesoAPIPostManageControl.

In almost all functions of the mesoscopic api there are simhandler and vehhandler parameters, they are used for internal reasons and to achieve better performance results. Simhandler represents the internal simulator while the vehhandler represents the vehicle.

Simulation Management¶

MesoAPILoad ():

Called when the module is loaded by Aimsun Next. Simulator is not available at this point.

MesoAPIInit (void * simhandler, int iterationNumber, bool statisticsAllowed)

Called when Aimsun Next starts the simulation and can be used to initialize the module. It is called at the beginning of every iteration in a DUE simulation.

- *iterationNumber*: The iteration number. In a one-shot simulation this  parameter is not used but in DUE simulation iterationNumber goes from 1 to number of iterations.
- *statisticsAllowed*: true if statistics are allowed in this iteration or simulation when executing a one-shot simulation.

MesoAPISimulationReady (void * simhandler)

Called when Aimsun Next starts the simulation and every thing is ready to start moving vehicles. It is called at the beginning of every iteration in a DUE simulation.
MesoAPIUnLoad (void * simhandler)

Called when the module is unloaded by Aimsun Next .
MesoAPIFinish(void * simhandler)

Called when Aimsun Next finishes the simulation. When running a DUE this function is called at the end of each iteration.

The following figure shows how Aimsun Next and the API Module interact.

Scheme how Aimsun Next Meso and the API Module interact

Simulation Events ¶

MesoAPINewVehicleSystem(void * simhandler, void * vehhandler)

Called when a new vehicle is generated, it can either enter the network or enter into a virtual queue. This function takes two parameters:
```
- *simhandler*: Simulator.
- *vehhandler*: The vehicle generated.
```
MesoAPINewVehicleNetwork (void * simhandler, void * vehhandler)

Called when a new vehicle enters the network. This is when it leaves the virtual queue if it was waiting to enter into the network:
```
- *simhandler*: Simulator.
- *vehhandler*: The vehicle generated.
```
MesoAPIEnterVehicleSection (void * simhandler, void * vehhandler, int fromSection, int toSection)

Called when a new vehicle enters a new section. This function takes four parameters:
```
- *simhandler*: Simulator.
- *vehhandler*: The vehicle.
- *fromSection*: Identifier of the section origin
- *toSection*: Identifier of the section it is entering.
```
MesoAPIExitVehicleSection (void * simhandler, void * vehhandler, int section)

Called when a new vehicle exits the section. This function takes three parameters:
```
- *simhandler*: Simulator.
- *vehhandler*: The vehicle.
- *section*: Identifier of the section it is exiting
```
MesoAPIVehicleReadyForSection (void * simhandler, void * vehhandler, int section)

Called when a new vehicle is ready to exit the section. The vehicle is the first in the queue. This function takes three parameters:
```
- *simhandler*: Simulator.
- *vehhandler*: The vehicle.
- *section*: Identifier of the next section
```
MesoAPIPostManageControl (void * simhandler)

Called every time there is a change in the control. This function is only called when the master control plan has adaptive controllers. This function takes one parameter:
```
- *simhandler*: The simulator.
```
MesoAPIPreManageRouteChoice (void * simhandler)

Called every time the route choice algorithms are executed. This function receives one parameter:
```
- *simhandler*: The simulator.
```
MesoAPINewStatisticalInterval (void * simhandler)

Called every time the statistics cycle starts. This function receives one parameter:
```
- *simhandler*: The simulator.
```
MesoAPINewDetectorStatisticalInterval (void * simhandler)

Called every time the detection statistics interval starts. This function receives one parameter:

    - *simhandler*: The simulator.

MesoAPIVehicleAtDestination (void * simhandler, void *vehhandler, int nodeid)

Called every time the vehicle reaches its destination:
```
- *simhandler*: The simulator.
- *vehiclehandler*: The vehicle
- *nodeid*: Node Identifier of the node
```

MesoAPIVehicleAtPTStop (void * simhandler, void * vehhandler, int sectionId, int stopid)

Called every time the vehicle reaches a transit stop:

- *simhandler*: The simulator.
- *vehiclehandler*: The vehicle
- *sectionId*: Current vehicle's section ID
- *stopid*: Current vehicle's transit stop ID

MesoAPIManageCycleEvent (void * simhandler, int cycleEventId)

Called every time for each cycleEventId and for each cycle time. The event id and cycle time have been defined using functions AMesoAddCycleEvent for adding a new event and AMesoChangeCycleEventTime to change presetted event. The idea behind this functions, MesoAPIManageCycleEvent, AMesoAddCycleEvent and AMesoChangeCycleEventTime is that the api user has a mechanism to syncronize the simulation with the api at every cycle time.
```
- *simhandler*: The simulator.
- *cycleEventId*: An event identifier. How these events id are created and controller is under the responsibility of the api.
```

Mesoscopic external give-way model ¶

These functions can be used to modify the interal behaviour of the give-way model when there are yield signs.

MesoAPIInterstedInGivewayModel(void *simhandler)

Called everytime it's necessary to apply a giveway model and decide which of two vehicles have preference. - simhandler: The simulator.
MesoAPIInterstedInGivewayModelNode(void * simhandler, int nodeid)

Called evertime it's necessary to apply a giveway model and decide which of two vehicles have preference in a given node. - simhandler: The simulator. - nodeid: The node id.
MesoAPIApplyExtGivewayModel(void simhandler, int modelResult, void vehhandler, void *otherVehHandler, bool spatialConflict) Called evertime it's necessary to apply a giveway model and decide which of two vehicles have preference. Return values are: - 0: vehicle in the giveway represented by vehhandler can move - 1: vehicle in the giveway represented by vehhandler can't move because the other vehicle represented by otherVehHandler has preference. - 2: vehicle in the giveway represented by vehhandler can't move because the other vehicle represented by otherVehHandler has preference and the other vehicle has an yield sign too affecting his movement.

The input parameters are the following: - simhandler: the simulator. - modelResult: this is the result of appling the interal mesoscopic model. - vehhandler: the vehicle in the giveway - otherVehHandler: the vehicle in the mainstream or vehicles to apply the giveway - spatialConflict: boolean that it's true when there is a spatial conflict between both vehicles trajectories. False when both vehicles doesn't have a spatial conflict.