Skip to content

API Changes

The changes to the API in recent releases of Aimsun Next are:

Changes in version 26.0.0

Python Version

In order to use Python to create an Aimsun Next API, Python 3.12 must be installed for Ubuntu 24, Mac ARM and Windows. It is possible to freely download from http://www.python.org/ website.

Refer to the ‘Before starting’ section in the Aimsun Next Scripting manual for information about the differences between C++ and Python syntax for functions.

Functions relevant to Traffic management

Parameters aOrigin and aDest have changed type in the following function:

void * AKIActionAddCloseTurningODAction(int sectionId, int anewSection2Close, const std::vector<int> & aOrigin, const std::vector<int> & aDest, int VehType, double acomplianceLevel, double visibilityDistance = 200.0, bool localEffect = true, int sectionAffectingPathCostId = -1);
void * AKIActionAddCloseTurningODActionByID(int idAction, int sectionId, int anewSection2Close, const std::vector\<int> & aOrigin, const std::vector\<int> & aDest, int vehType, double acomplianceLevel, double visibilityDistance = 200.0, bool localEffect = true, int sectionAffectingPathCostId = -1 );
void * AKIActionAddEnRouteAssignmentAction(int actionId, int ang_sectionId, int sectionInPath, const std::vector<int>& aOrigin, const std::vector<int>& aDest, int vehType, double complianceLevel, bool reevaluateAction, int routeChoiceType, double routeChoiceParam1, double routeChoiceParam2, double routeChoiceParam3);
void * AKIActionAddForceTurningODActionByID( int idAction, int sectionId, const std::vector<A2KDestinationProportion*>& aNextSections, const std::vector<int>& aOrigin, const std::vector<int>& aDest, int vehType, int aSectionInPath, double aComplianceLevel, double visibilityDistance ); 
void * AKIActionAddForceTurningODActionQTByID( int idAction, int sectionId, QList<DestinationProportion> aNextSections, const std::vector<int>& aOrigin, const std::vector<int>& aDest, int vehType, int aSectionInPath, double aComplianceLevel, double visibilityDistance ); 
void * AKIActionAddForceTurningODSubPathActionByID( int idAction, int sectionId, const std::vector<A2KDestinationProportion*>& aNextSections, const std::vector<int>& aOrigin, const std::vector<int>& aDest, int vehType, int aSectionInPath, double aComplianceLevel, double visibilityDistance ); 
void * AKIActionAddForceTurningODSubPathActionQTByID( int idAction, int sectionId, QList<DestinationProportion> aNextSections, const std::vector<int>& aOrigin, const std::vector<int>& aDest, int vehType, int aSectionInPath, double aComplianceLevel, double visibilityDistance );
void * AKIActionAddChangeDestActionByID(int idAction, int sectionId, const std::vector<A2KDestinationProportion*>& aNewDests, const std::vector<int>& aOrigin, const std::vector<int>& aDest, int vehType, double aComplianceLevel);
void * AKIActionAddChangeDestActionQTByID(int idAction, int sectionId, const QList<DestinationProportion> anewDests, const std::vector<int>& aOrigin, const std::vector<int>& aDest, int vehType, double aComplianceLevel);
void * AKIActionAddChangeDestParkRideActionByID(int idAction, int sectionId, const std::vector<A2KDestinationProportion*>& aNewDests, const std::vector<int>& aOrigin, const std::vector<int>& aDest, int vehType, double complianceLevel, double scaleFactor);
void * AKIActionAddChangeDestParkRideActionQTByID(int idAction, int sectionId, const QList<DestinationProportion> anewDests, const std::vector<int>& aOrigin, const std::vector<int>& aDest, int vehType, double complianceLevel, double scaleFactor);

The old version of the functions expected an int with the ID of the origin/destination centroid to be used as filter, if the ID was invalid (-1) no filter was applied. Now, it receives a vector with the IDs of the origin/destination centroids to be used as filter, if the vector is empty no filter will be applied.

Changes in version 24.0.2

Functions relevant to Traffic management

Two new high-level functions in micro to inform that a traffic management action has been activated or deactivated, have been added:

  • AAPIActionActivated(int idAction);
  • AAPIActionDeactivated(int idAction);

Note that all existing Python APIs need to be updated adding the above 2 functions in order to be loaded in the simulation as expected.

Functions relevant to simulated vehicles

1) One new parameter has been returned by a new function, the AKIVehTrackedGetCOPERTEmissionVehicleTypeId:

  • COPERTEmissionVehicleTypeId, emission vehicle type including in the vehicle type for the COPERT model (depends on vehicle category): Car, LargeGoodsVehicle, HeavyGoodsVehicle, Coach, Bus, MicroCar, Motorbike, Quad.

2) Info struct DynInfVeh is now returned by a new function, the AKIVehGetVehicleTrackedDynInf:

struct A2KERNELEXPORT DynInfVeh{
    int report;
    double xCurrentPos;
    double yCurrentPos;
    double xCurrentPosBack;
    double yCurrentPosBack;
    double currentSpeed;
    int downstreamObjectId;
};

where:

  • report: Error code returned (0 means success).
  • xCurrentPos, yCurrentPos: World coordinates of the middle point of the vehicle front bumper for the current position
  • xCurrentPosBack, yCurrentPosBack: World coordinates of the middle point of the vehicle rear bumper for the current position
  • currentSpeed: Current speed (km/h or mph, depending the units defined in the network).
  • downstreamObjectId: Downstream object Id.

Changes in version 23.0.2

Functions relevant to Detection Pattern Events

Parameter isSection has been removed from the following functions:

  • int AKIInfNetGetIdObjectofOriginCentroidConnector(int aid, int elem);
  • int AKIInfNetGetIdObjectofDestinationCentroidConnector(int aid, int elem);
  • int AKIInfNetGetIdObjectANGofOriginCentroidConnector(int aid, int elem);
  • int AKIInfNetGetIdObjectANGofDestinationCentroidConnector(int aid, int elem);

AKIInfNetGetIdObjectofOriginCentroidConnector

Changes in version 23.0.1

Functions relevant to Detection Pattern Events

In previous versions the function to add Detector Pattern Events required the start and end time of the event to be expressed as time of the simulation, in seconds from midnight. This made it impossible to execute events during a warmup. A new function to add events with relative times has been added:

Old functions are kept for compatibility reasons but are considered deprecated and will be removed in future versions.

Changes in version 23

Attributes added or modified to InfVeh and InfPTVeh

  • Added isLost attribute, used for return whether the vehicle cannot longer reach its destination, to both InfVeh and InfPTVeh.
  • From InfPTVeh, the misspelled theoricalGenerationTime renamed to theoreticalGenerationTime.

Attribute added to StaticInfPed

  • Added typeID attribute to be able to get the pedestrian type of the pedestrian.

Changes in version 22.0.2

Added all missing variables for global, partial and current period in the following entities:

StructAkiEstadSystem:

  • int vehOut: Vehicles which are left from the network.

  • int totalNumStops: Total number of stops.

  • double waitingTimeVirtualQueue, waitingTimeVirtualQueueDev: Average time in seconds that vehicles remained waiting in a virtual queue. Only in entry sections.

StructAkiEstadSection:

  • int numVehiclesInVQ: Total number of vehicles in virtual queues.

  • double waitingTimeVirtualQueue, waitingTimeVirtualQueueDev: Average time in seconds that vehicles remained waiting in a virtual queue. Only in entry sections.

It has not added the missing stats of dTimeTTime because is allow to calculate from the delay Time and the travel time.

StructAkiEstadSectionLane:

  • int count: Count.

  • int inputCount: Input count.

  • int inputFlow: Input Flow.

  • double STa,STd: Average and deviation of the stop time.

  • double waitingTimeVirtualQueue, waitingTimeVirtualQueueDev: Average time in seconds that vehicles remained waiting in a virtual queue. Only in entry sections.

It has not added the missing stats of dTimeTTime because is allow to calculate from the delay Time and the travel time.

StructAkiEstadTurning:

  • int count: Count.

  • int inputCount: Input Count.

  • int inputFlow: Input Flow.

  • double virtualQueueAvg: Average of virtual queue.

  • int virtualQueueMax: Maximum of virtual queue.

  • int vehLost: Total number of lost vehicles.

  • int vehMissed: Total number of missed vehicles.

StructAkiEstadODPair:

  • int count: Count.

  • int inputCount: Input Count.

  • int inputFlow: Input Flow.

  • int vehLost: Total number of lost vehicles.

  • double dwellTime, dwellTimeDev: Time spends by a vehicle at a scheduled stop without moving. Only in Transit line vehicles.

  • double waitingTimeVirtualQueue, waitingTimeVirtualQueueDev: Average time in seconds that vehicles remained waiting in a virtual queue. Only in entry sections.

StructAkiEstadStream:

  • int count: Count.

  • int inputCount: Input Count.

  • int inputFlow: Input Flow.

  • int vehLost: Total number of lost vehicles.

  • double dwellTime, dwellTimeDev: Time spends by a veh at a scheduled stop without moving. Only in Transit line vehicles.

  • double waitingTimeVirtualQueue, waitingTimeVirtualQueueDev: Average time in seconds that vehicles remained waiting in a virtual queue. Only in entry sections.

Changes in version 22

Functions relevant to Transit Management

Obsolete parameters VehType, acomplianceLevel and visibilityDistance have been removed from:

Attributes added to StaticInfVeh and StaticInfPTVeh

  • Added engineTypeId identifier, used for classify vehicles by engine in MFC acceleration model, emission models, consumption models, where: None = 0, Petrol = 1, Diesel = 2, Electric = 3, LPG = 4.
  • Added (for the moment only to StaticInfVeh) chassisId identifier, used for classify vehicles by segment (profiles) in MFC Acceleration (MFC acceleration model and battery consumption model).
  • Added EUEmissionId identifier, used for classify vehicles by emission type LEM model (London Emission Model).
  • Added energyCapacity parameter, fuel tank capacity (l) or battery capacity (kW) for energy consumption model (Energy consumption model).

Attributes added to InfVeh and InfPTVeh

  • Added energyState variable, current fuel level or current battery capacity (%) (Energy consumption model).

New struct added LeaderInfVeh

It contains the following info about leader:

  • report: 0, OK, else error code
  • idVeh: vehicle identifier
  • idLeaderVeh: leader vehicle identifier, 0 if no leader
  • headway: time between the front bumper of a vehicle and the front bumper of the following vehicle (s)
  • gap: time between the rear bumper of a vehicle and the front bumper of the following vehicle (s)
  • spacing: space between the front bumper of a vehicle and the front bumper of the following vehicle (m)
  • clearance: space between the rear bumper of a vehicle and the front bumper of the following (m)

Functions relevant to simulated vehicles

Three new functions have been added to provide access to the new struct named LeaderInfVeh and to get info about the leader vehicle:

Four new parameters have been added to the StaticInfVeh structure returned by the AKIVehTrackedGetStaticInf call, the AKIVehGetVehicleStaticInfSection call and the AKIVehGetVehicleStaticInfJunction call:

  • engineTypeId, identifier used for classify vehicles by engine in MFC acceleration, emission models, consumption models, where: None = 0, Petrol = 1, Diesel = 2, Electric = 3, LPG = 4.
  • chassisId, identifier, used for classify vehicles by segment (profiles) in MFC acceleration.
  • EUEmissionId, identifier used for classify vehicles by emission type LEM model.
  • energyCapacity, fuel tank capacity (l) or battery capacity (kW) for energy consumption model.

Two new parameters have been returned by the two new functions AKIVehTrackedGetVehicleCategoryId call, the AKIVehTrackedGetLEMEmissionVehicleTypeId call:

  • vehicleCategoryId, vehicle category identifier including in the vehicle type for engine composition: Car, Commercial vehicle, Bus, Motorbike and Non-motorized.
  • LEMEmissionVehicleTypeId, emission vehicle type including in the vehicle type for the LEM model (depends on vehicle category): Car, Taxi, LGV, HGV, Single-Decker Bus, Double-Decker Bus, Coach.

Functions relevant to entities

StructAkiEstadSystem

  • StructAkiEstadSystem AKIEstGetGlobalStatisticsSystemBatteryCons(int VehType, double& batteryConsumption);
  • StructAkiEstadSystem AKIEstGetParcialStatisticsSystemBatteryCons(double time, int VehType, double &batteryConsumption);
  • double AKIEstGetGlobalStatisticsSystemBatteryConsumption(int VehType);
  • double AKIEstGetParcialStatisticsSystemBatteryConsumption(double time, int VehType);

StructAkiEstadSection

  • StructAkiEstadSection AKIEstGetGlobalStatisticsSectionBatteryCons(int aidarc, int VehType, double& batteryConsumption);
  • StructAkiEstadSection AKIEstGetParcialStatisticsSectionBatteryCons(int aidarc, double time, int VehType, double& batteryConsumption);
  • StructAkiEstadSection AKIEstGetCurrentStatisticsSectionBatteryCons(int aidarc, int VehType, double & batteryConsumption);
  • double AKIEstGetGlobalStatisticsSectionBatteryConsumption(int aidarc, int VehType);
  • double AKIEstGetParcialStatisticsSectionBatteryConsumption(int aidarc, double time, int VehType);
  • double AKIEstGetCurrentStatisticsSectionBatteryConsumption(int aidarc, int VehType);

StructAkiEstadTurning

  • StructAkiEstadTurning AKIEstGetGlobalStatisticsTurningBatteryCons(int aidsectionFrom, int aidsectionTo, int VehType, double& batteryConsumption);
  • StructAkiEstadTurning AKIEstGetParcialStatisticsTurningBatteryCons(int aidsectionFrom, int aidsectionTo, double time, int VehType, double& batteryConsumption);
  • StructAkiEstadTurning AKIEstGetCurrentStatisticsTurningBatteryCons(int aidsectionFrom, int aidsectionTo, int VehType, double& batteryConsumption);
  • double AKIEstGetGlobalStatisticsTurningBatteryConsumption(int aidsectionFrom, int aidsectionTo, int VehType);
  • double AKIEstGetParcialStatisticsTurningBatteryConsumption(int aidsectionFrom, int aidsectionTo, double time, int VehType);
  • double AKIEstGetCurrentStatisticsTurningBatteryConsumption(int aidsectionFrom, int aidsectionTo, int VehType);
  • StructAkiEstadTurning AKIEstGetGlobalStatisticsLinkBatteryCons(int aidsectionFrom, int aidsectionTo, int VehType, double& batteryConsumption);
  • StructAkiEstadTurning AKIEstGetParcialStatisticsLinkBatteryCons(int aidsectionFrom, int aidsectionTo, double time, int VehType, double& batteryConsumption);
  • StructAkiEstadTurning AKIEstGetCurrentStatisticsLinkBatteryCons(int aidsectionFrom, int aidsectionTo, int VehType, double& batteryConsumption);
  • double AKIEstGetGlobalStatisticsLinkBatteryConsumption(int aidsectionFrom, int aidsectionTo, int VehType);
  • double AKIEstGetParcialStatisticsLinkBatteryConsumption(int aidsectionFrom, int aidsectionTo, double time, int VehType);
  • double AKIEstGetCurrentStatisticsLinkBatteryConsumption(int aidsectionFrom, int aidsectionTo, int VehType);

StructAkiEstadODPair

  • StructAkiEstadODPair AKIEstGetGlobalStatisticsODPairBatteryCons(int idOrigin, int idDestination, int VehType, double& batteryConsumption);
  • StructAkiEstadODPair AKIEstGetParcialStatisticsODPairBatteryCons(int idOrigin, int idDestination, double time, int VehType, double &batteryConsumption);
  • double AKIEstGetGlobalStatisticsODPairBatteryConsumption(int idOrigin, int idDestination, int VehType);
  • double AKIEstGetParcialStatisticsODPairBatteryConsumption(int idOrigin, int idDestination, double time, int VehType);

StructAkiEstadStream

  • StructAkiEstadStream AKIEstGetParcialStatisticsStreamBatteryCons(int aidstream, double time, int VehType, double& batteryConsumption);
  • StructAkiEstadStream AKIEstGetGlobalStatisticsStreamBatteryCons(int aidstream, int VehType, double& batteryConsumption);
  • double AKIEstGetParcialStatisticsStreamBatteryConsumption(int aidstream, double time, int VehType);
  • double AKIEstGetGlobalStatisticsStreamBatteryConsumption(int aidstream, int VehType);

New Python version for APIs in Python

Aimsun Next 22 is released with Python 3 only. Support for Python 2 has been discontinued. The Ubuntu release uses Python 3.7 and the Mac and Windows releases require Python 3.10.

Changes in version 20

Functions relevant to traffic management

A new parameter to specify the section that will affect path calculation costs has been added to these two functions:

  • void * AKIActionAddCloseTurningODAction(int sectionId, int anewSection2Close, int aOrigin, int aDest, int vehType, double acomplianceLevel, double visibilityDistance, bool localEffect, int sectionAffectingPathCostId )

  • void * AKIActionAddCloseTurningODActionByID(int sectionId, int anewSection2Close, int aOrigin, int aDest, int vehType, double acomplianceLevel, double visibilityDistance, bool localEffect, int sectionAffectingPathCostId )

New functions added:

  • void * AKIActionAddTurnSpeedActionByID( int idAction, int nbTurns, int * turnIDs, double speed, int vehicleType, double complianceLevel, bool considerSpeedAcceptance )

Functions and attributes relevant to yellow box speed

  • The yellow box speed in sections is no longer available. A2KSectionInf and A2KSectionBehaviourParam structs obsolete "double yellowBoxSpeed" parameter has been removed.
  • A2KTurnInf have a new parameter to know whether a turn will take into account the yellow box .

Attributes removed from StaticInfVeh and StaticPTVeh

  • Obsolete minSafetyDistance parameter has been removed from StaticInfVeh and StaticPTVeh.

Three new parameters have been added to allow 2 dimensional positioning of a vehicle:

  • int AKIPutVehTrafficOD(int asection, int idLane, int vehTypePos, int idCentroidOr, int idCentroidDest, double initPosition, double initSpeed, int tracking, bool use2Dim, double initYPosition, double initYSpeed );

New Python version for APIs in Python

Aimsun Next 20 is released with 2 different versions of Python. The Python 2 installer version uses Python 2.7 meanwhile the Python 3 installer uses Python 3.7.