Building a Microscopic Aimsun Next API¶

The Aimsun Next API module can be implemented as a dynamic library written in C++ or as a script file written in Python (version 3.7 for Ubuntu, version 3.10 for Mac and Windows) (for more information about this scripting language, visit http://www.python.org)

Building an Aimsun Next Micro API using C++¶

A C++ Aimsun Next API Extension is a dynamic library that contains the desired code that will interact with the microscopic simulator. Aimsun Next will load this dynamic library, if selected in the Scenario Editor, when a simulation starts.

To help develop this library, the following files are supplied:

Header Files:
- AKIProxie.h
- CIProxie.h
- ANGConProxie.h
- AAPI_Util.h
Libraries:
- Windows 64 bits version: a2kernel23.lib and acontrol23.lib
- Linux 64 bits versions: liba2kernel22.so and libacontrol22.so (located in the Aimsun Next Home folder)
- Mac version: liba2kernel22.1.0.dylib and libacontrol22.1.0.dylib (located in the Aimsun Next.app/Contents/PlugIns folder)
Sample Files:
- AAPI.h
- AAPI.cxx

Only the sample file AAPI.cxx, can be modified, fill in the routines AAPILoad(), AAPIInit(), AAPISimulationReady(), AAPIManage(…), AAPIPostManage(…), AAPIFinish() and AAPIUnLoad() and add other files if required.

With the Windows 64-bit version there is a sample Visual C++ 2013 project ready to compile and build the DLL. The Visual C++ 2013 project has two configurations available: the Debugger configuration that builds the AAPI_D.dll by default and the Release configurations that builds the AAPI_R.dll by default.

A very simple example of the Aimsun Next API Module in shown in the following AAPI.cxx file:

#include "AKIProxie.h"
#include "CIProxie.h"
#include "ANGConProxie.h"
#include "AAPI.h"
#include <stdio.h>

// Procedures that could be modified by the user

int AAPILoad()
{
    AKIPrintString("LOAD");
    return 0;
}

int AAPIInit()
{
    AKIPrintString("\tInit");
    return 0;
}

int AAPISimulationReady()
{
    AKIPrintString("\tAAPISimulationReady");
    return 0;
}

int AAPIManage(double time, double timeSta, double timeTrans, double acycle)
{
    return 0;
}

int AAPIPostManage(double time, double timeSta, double timeTrans, double acycle)
{
    return 0;
}

int AAPIFinish()
{
    AKIPrintString("\tFinish");
    return 0;
}

int AAPIUnLoad()
{
    AKIPrintString("UNLOAD");
    return 0;
}

Building an Aimsun Next Micro API using a Python Script¶

The Aimsun Next API Extension can be implemented using a Python script. This Python script is an ASCII file with the extension PY and can be created in any text editor.

A Python script should define the fourteen high level functions: AAPILoad(), AAPIInit(), AAPIManage(…), AAPIPostManage(…), AAPIFinish(), AAPIUnLoad(), AAPIPreRouteChoiceCalculation(...), AAPIVehicleStartParking(...), AAPIEnterVehicle(...), AAPIEnterVehicle(...), AAPIExitVehicle(...), AAPIEnterPedestrian(...), AAPIExitPedestrian(...), AAPIEnterVehicleSection(...) and AAPIExitVehicleSection(...). All high level functions must be defined in the file for it to be run successfully.

A very simple example of Aimsun Next API Module with the following contents is provided in the sample.py file:

from AAPI import *

def AAPILoad():
    AKIPrintString( "AAPILoad" )
    return 0

def AAPIInit():
    AKIPrintString( "AAPIInit" )
    return 0

def AAPISimulationReady():
    AKIPrintString( "AAPISimulationReady" )
    return 0

def AAPIManage(time, timeSta, timeTrans, acycle):
    AKIPrintString( "AAPIManage" )
    return 0

def AAPIPostManage(time, timeSta, timeTrans, acycle):
    AKIPrintString( "AAPIPostManage" )
    return 0

def AAPIFinish():
    AKIPrintString( "AAPIFinish" )
    return 0

def AAPIUnLoad():
    AKIPrintString( "AAPIUnLoad" )
    return 0

def AAPIPreRouteChoiceCalculation(time, timeSta):
    AKIPrintString( "AAPIPreRouteChoiceCalculation" )
    return 0

def AAPIVehicleStartParking (idveh, idsection, time):
    return 0

def AAPIEnterVehicle(idveh, idsection):
    return 0

def AAPIExitVehicle(idveh, idsection):
    return 0

def AAPIEnterPedestrian(idPedestrian, originCentroid):
    return 0

def AAPIExitPedestrian(idPedestrian, destinationCentroid):
    return 0

def AAPIEnterVehicleSection(idveh, idsection, atime):
    return 0

def AAPIExitVehicleSection(idveh, idsection, atime):
    return 0

There are some functions that need to pass parameters by reference. In Python it is not possible to pass parameters by reference, but there are some extra functions to enable this.

In the following code there is an example of how functions with reference parameters can be used in a Python script. The function calculates the cycle duration of a junction.

def getCycleTime(junctionId , numPhases, t):
    cycle = 0
    pdur = doublep()
    pcmax = doublep()
    pcmin = doublep()
    for i in range(1, numPhases):
    ECIGetDurationsPhase(junctionId, i, t, pdur, pcmax, pcmin)
    cycle = cycle + pdur.value()
    del pdur
    del pcmax
    del pcmin
    return cycle

Building a Mesoscopic Aimsun Next API Application¶

The Aimsun Next API module can be implemented as a dynamic library written in C++ or as a script file written in Python (version 3.7 for Ubuntu, version 3.10 for Mac and Windows) (for more information about this scripting language, visit http://www.python.org)

Building an Aimsun Next Meso API using C++¶

A C++ Aimsun Next API Next Extension is a dynamic library that contains the desired code that will interact with the mesoscopic simulator. Aimsun Next will load this dynamic library, if selected in the Scenario Editor, when a simulation starts.

To develop this library, the following files are supplied:

Header Files:
- AMesoAPIHelper.h
- CIProxie.h
- AAPI_Util.h
Libraries:
- Windows 64 bits version: aimsunmesoplugin23.lib, acontrol23.lib
Sample Files:
- AAPI.h
- AAPI.cxx

Only the sample file AAPI.cxx should be modified to fill in the routines MesoAPILoad(…), MesoAPIInit(…), MesoAPISimulationReady(…), MesoAPIFinish(…), MesoAPIUnLoad(…), MesoAPINewVehicleSystem(…), MesoAPINewVehicleNetwork(…),MesoAPIEnterVehicleSection(…) and MesoAPIExitVehicleSection(…), MesoAPIPostManageControl(…), MesoAPIPreManageRouteChoice(…) and other files included if required.

With the Windows 64-bit version there is a sample Visual C++ 2013 project ready to compile and build the DLL. The Visual C++ 2013 project has two configurations available: the Debugger configuration that builds the AAPI_D.dll by default and the Release configurations that builds the AAPI_R.dll by default.

A very simple example of the Aimsun Next API Module could be defined by the following contents of AAPI.cxx:

#include "AMesoAPIHelper.h"


#include "AAPI.h"
#include <stdio.h>

// Procedures could be modified by the user

int MesoAPILoad()
{
    return 0;
}

int MesoAPIUnLoad(void * handler)
{
    AMesoPrintString(handler, "UnLOAD");
    return 0;
}

int MesoAPIInit(void * handler, int iterationNumber, bool statisticsAllowed)
{
    AMesoPrintString(handler, "\tInit");
    return 0;
}

int MesoAPISimulationReady(void * handler) { AMesoPrintString(handler, "\tSimulation Ready"); return 0; }

int MesoAPIFinish(void * handler)
{
    AMesoPrintString(handler, "\tFinish");
    return 0;
}

int MesoAPINewVehicleSystem(void * simhandler, void * vehhandler)
{
    return 0;

}

int MesoAPINewVehicleNetwork(void * simhandler, void * vehhandler)
{
    return 0;
}

int MesoAPIFinishVehicleNetwork(void * simhandler, void * vehhandler, bool normalOut)
{
    //AMesoPrintString(simhandler, "\tFinish system");
    return 0;
}

int MesoAPIEnterVehicleSection(void * simhandler, void * vehhandler, int fromSection, int toSection)
{
    AMesoVehicleInfo vehInf = AMesoGetVehicleInfo(simhandler, vehhandler);
    return 0;
}

int MesoAPIExitVehicleSection(void * simhandler, void * vehhandler, int section)
{
    AMesoVehicleInfo vehInf = AMesoGetVehicleInfo(simhandler, vehhandler);
    return 0;
}

int MesoAPIVehicleReadyForSection(void * simhandler, void * vehhandler, int section)
{
    AMesoVehicleInfo vehInf = AMesoGetVehicleInfo(simhandler, vehhandler);
    return 0;
}

int MesoAPIPostManageControl(void * simhandler)
{
    std::cout << "Post Manage Control" << '\n';
    return 0;
}

int MesoAPIPreManageRouteChoice(void * simhandler)
{
    std::cout << "Pre Manage Route Choice" << '\n';
    return 0;
}

Building an Aimsun Next Meso API using a Python Script¶

The Aimsun Next API Extension can be implemented using a Python script. This Python script is an ASCII file with the extension PY and can be created in any text editor.

A Python script should be written to define the six high level functions: MesoAPILoad(…), MesoAPIInit(…), MesoAPISimulationReady(…), MesoAPIUnLoad(…),MesoAPIFinish(…),MesoAPINewVehicleSystem(…), MesoAPINewVehicleNetwork(…),MesoAPIFinishVehicleNetwork(…), MesoAPIEnterVehicleSection(…), MesoAPIExitVehicleSection(…) and MesoAPIPostManageControl(…), MesoAPIPreManageRouteChoice(…).

A very simple example of Aimsun Next API Module with the following contents is provided in the sample.py file:

from AMesoAPI import *

def MesoAPILoad():
    print("AMesoAPILoad" )
    return 0

def MesoAPIInit(simhandler, iterationNumber, statisticsActivated):
    AMesoPrintString( simhandler, "AMesoAPIInit" )
    return 0

def MesoAPISimulationReady(simhandler):
    AMesoPrintString( simhandler, "AMesoSimulationReady" )
    return 0

def MesoAPIUnLoad(simhandler):
    AMesoPrintString(simhandler, "AMesoUnAPILoad" )
    return 0

def MesoAPIFinish(simhandler):
    AMesoPrintString(simhandler, "AMesoFinish" )
    return 0

def MesoAPINewVehicleSystem(simhandler, vehhandler):
    vehInf = AMesoGetVehicleInfo(simhandler, vehhandler)
    AMesoPrintString(simhandler, "Veh system id %d"%vehInf.id)
    return 0

def MesoAPINewVehicleNetwork(simhandler, vehhandler):
    vehInf = AMesoGetVehicleInfo(simhandler, vehhandler)
    AMesoPrintString(simhandler, "Veh network id %d"%vehInf.id)
    return 0

def MesoAPIFinishVehicleNetwork(simhandler, vehhandler, normalOut):
    vehInf = AMesoGetVehicleInfo(simhandler, vehhandler)
    AMesoPrintString(simhandler, "Veh finish id %d"%vehInf.id)
    return 0


def MesoAPIEnterVehicleSection(simhandler, vehhandler, fromSection, toSection):
    vehInf = AMesoGetVehicleInfo(simhandler, vehhandler)
    AMesoPrintString(simhandler, "Veh enter id %d %f %d %d"%(vehInf.id, AMesoGetCurrentTime(simhandler), fromSection, toSection))
    return 0

def MesoAPIExitVehicleSection(simhandler, vehhandler, section):
    vehInf = AMesoGetVehicleInfo(simhandler, vehhandler)
    AMesoPrintString(simhandler, "Veh exit id %d %f %d"%(vehInf.id, AMesoGetCurrentTime(simhandler), section))
    return 0

def MesoAPIVehicleReadyForSection(simhandler, vehhandler, section):
    vehInf = AMesoGetVehicleInfo(simhandler, vehhandler)
    AMesoPrintString(simhandler, "Veh ready for section id %d %f %d"%(vehInf.id, AMesoGetCurrentTime(simhandler), section))
    return 0

def MesoAPIPostManageControl(simhandler):
    return 0

def MesoAPIPreManageRouteChoice(simhandler):
    return 0

def MesoAPIVehicleAtDestination(simhandler, vehhandler, nodeid):
    return 0

def MesoAPIVehicleAtPTStop(simhandler, vehhandler, section, transitstop):
    return 0

There are some functions that need to pass parameters by reference. In Python it is not possible to pass parameters by reference, but there are some extra functions that enable this.

In the following code there is an example of how functions with reference parameters can be used in a Python script. The function calculates the cycle duration of a junction.

def getCycleTime(junctionId , numPhases, t):
    cycle = 0
    pdur = doublep()
    pcmax = doublep()
    pcmin = doublep()
    for i in range(1, numPhases):
        ECIGetDurationsPhase(junctionId, i, t, pdur, pcmax, pcmin)
        cycle = cycle + pdur.value()
    del pdur
    del pcmax
    del pcmin
    return cycle

How to enable and load an Aimsun Next API Extension from Aimsun Next¶

To enable a user-defined Aimsun Next API Extension, add it in the Scenario definition. Clicking on the Scenario by selecting the API tab folder when the following dialog appears:

Extensions Dialog

In this dialog, use the Add button or Remove button to load or unload a set of Aimsun Next Extensions (Dynamic libraries or Python scripts).