Skip to content

Aimsun Next API Control Meterings

Read Number of meterings

In C++ and Python

Explanation

Read the number of meterings present on the road network.

Format
int ECIGetNumberMeterings ()
Parameters

No parameters required.

Output
Output
  • ≥ 0: The number of meterings in the road network
  • < 0: Error

Read Information of a metering

In C++ and Python

Explanation

Read the information of the elem-th metering.

Format
structA2KMetering ECIGetMeteringProperties (int elem)
structA2KMetering ECIGetMeteringPropertiesById (int IdMetering)
Parameters
  • elem: Has to be between 0 and the total number of meterings -1
  • IdMetering: The metering identifier.
Output
struct structA2KMetering {
    int report;
    int Id; 
    int IdSection;
    int IdFirstLane;
    int IdLastLane;
    int Type;
    double Distance;
    const unsigned short* Name;
    int Platoon;
};

where:

  • report: 0, OK, else error code.
  • Id: Metering identifier.
  • IdSection: Section identifier where the metering is located.
  • IdFirstLane: First lane that the metering covers.
  • IdLastLane: Last lane that the metering covers.
  • Type: Metering type: 1: GREEN, 2: FLOW, 3:DELAY, 4:FLOW ALINEA, 5:GREEN BY LANE.
  • Distance: Position of the beginning of the metering, with respect to the beginning of the section.
  • Name: Metering name.
  • Platoon: On flow meterings, the number of vehicles by lane that will allow to cross.

Read the Section Identifier of a metering

In C++ and Python

Explanation

Read the section identifier that contains the elem-th metering present on the road network.

Format
int ECIGetMeteringIdSection(int elem)
Parameters
  • elem: The index of the metering within the range 0 ≤ elem < number of meterings –1.
Output
  • > 0: section identifier that contains the elem-th metering.
  • < 0: Error

Read the Metering Identifier

In C++ and Python

Explanation

Read the metering identifier that contains the elem-th metering present on the road network.

Format
int ECIGetMeteringIdByPosition (int elem)
Parameters
  • elem: The index of the metering within the range 0 ≤ elem < number of meterings –1
Output
  • > 0: metering identifier.
  • < 0: Error

Read the Metering Identifier (Deprecated function)

In C++ and Python

Explanation

Read the metering identifier from a section. This function has been deprecated in version 6. Use the ECIGetMeteringIdByPosition function instead.

Format
int ECIGetMeteringId (int idsection)
Parameters
  • idsection: The section identifier for the section where the metering is located
Output
  • > 0: metering identifier.
  • < 0: Error

Read the Metering Identifier

In C++ and Python

Explanation

Read the metering identifier from a section and a position inside the section (from the beginning of the section).

Format
int ECIGetMeteringIdByPos (int idsection, double position)
Parameters
  • idsection: The section identifier for the section where the metering is located
  • position: The position from the beginning of the section where the metering is located, in the network units (meters or feet).
Output
  • > 0: metering identifier.
  • < 0: Error

Read the Name of a metering

In C++ and Python

Explanation

Read the name of a metering present in a section.

Format
const unsigned short *ECIGetMeteringNameById(int idmetering);
const unsigned short *ECIGetMeteringName(int idsection) (Deprecated function)
Parameters
  • idmetering: The metering identifier
  • idsection: The section identifier for the section where the metering is located.
Output
  • < > NULL: name of the metering
  • = NULL: Error

Sample code in Python:

nonChar = boolp()
name = AKIConvertToAsciiString(ECIGetMeteringNameById(idmetering), True, nonChar)

Read the Type of metering

In C++ and Python

Explanation

Read the type of metering present in a section. The type of a metering can be 0: None; 1: GREEN METERING; 2: FLOW METERING; 3: DELAY METERING; 4: FLOW-ALINEA METERING; 5: GREEN BY LANE METERING.

Format
int ECIGetTypeMeteringById(int idmetering); 
int ECIGetTypeMetering (int idsection) (Deprecated function)
Parameters
  • idmetering: The metering identifier
  • idsection: A valid identifier of a section.
Output
  • ≥ 0: No error occurred.
  • < 0: Error

Read the Control Parameters of a Green Metering

In C++ and Python

Explanation

Read the parameters of a green metering that are defined in the current control.

Format
int ECIGetParametersGreenMeteringById(int idmetering, double timeSta,   double *amax, double *greenTime, double *amin, double *cycleTime, double *offset, double *yellowTime);
int ECIGetParametersGreenMetering (int idsection, double timeSta, double *amax, double *greenTime, double *amin, double *cycleTime, double *offset, double *yellowtime) (deprecated function)
Parameters
  • idmetering: The metering identifier
  • idsection: A valid section identifier.
  • timeSta: The time of simulation in stationary period, in seconds from midnight.
  • amax: Value returns the current maximum green time in seconds.
  • greenTime: Value returns the current green time, in seconds.
  • amin: Value returns the current minimum green time, in seconds.
  • cycleTime: Value returns the current cycle time, in seconds.
  • offset: Value returns the offset, in seconds.
  • yellowtime: Value returns the yellow time, in seconds.
Output
  • = 0: No error occurred.
  • < 0: Error

Change the Control Parameters of a Green Metering

In C++ and Python

Explanation:

Changes the parameters of a green metering that are defined in the current control.

Format
int ECIChangeParametersGreenMeteringById(int idmetering, double timeSta, double amax, double ngreenTime, double amin, double ncycleTime, double offset, double yellowTime, double currentTime, double currentTimeTrans, double cycle);
int ECIChangeParametersGreenMetering(int idsection, double timeSta, double amax, double ngreenTime, double amin, double ncycleTime, double offset, double yellowtime, double currentTime, double currentTimeTrans, double cycle)
Parameters
  • idmetering: The metering identifier.
  • idsection: A valid section identifier.
  • timeSta: The time of simulation in stationary period, in seconds from midnight.
  • amax: The new maximum green time, in seconds.
  • ngreenTime: The new green time, in seconds.
  • amin: The new minimum green time, in seconds.
  • ncycleTime: The new cycle time, in seconds.
  • offset: The new offset, in seconds.
  • yellowtime:The new yellow time, in seconds.
  • currentTime:The current simulation time.
  • currentTimeTrans:The current simulation time without the warm up.
  • cycle:The current simulation step.
Output
  • = 0: No error occurred.
  • < 0: Error

Read the Control Parameters of a Green by Lane Metering

In C++ and Python

Explanation

Read the parameters of a green by lane metering that are defined in the current control.

Format
int ECIGetParametersGreenMeteringByLaneById(int idmetering, double timeSta, double *amax, double *greenTime, double *amin,double *cycleTime, double *offset, double *yellowTime, double *laneOffset);
Parameters
  • idmetering: The metering identifier.
  • timeSta: The time of simulation in stationary period, in seconds from midnight.
  • amax: Value returns the current maximum green time in seconds.
  • greenTime: Value returns the current green time, in seconds.
  • amin: Value returns the current minimum green time, in seconds.
  • cycleTime: Value returns the current cycle time, in seconds.
  • offset: Value returns the offset, in seconds.
  • yellowtime: Value returns the yellow time, in seconds.
  • laneOffset: Value returns the delay activating green between lanes, in seconds.
Output
  • = 0: No error occurred.
  • < 0: Error

Change the Control Parameters of a Green by Lane Metering

In C++ and Python

Explanation

Changes the parameters of a green by lane metering that are defined in the current control.

Format
int ECIChangeParametersGreenMeteringByLaneById(int idmetering, double timeSta,double amax, double ngreenTime, double amin, double ncycleTime, double offset, double yellowTime, double laneOffset , double currentTime, double currentTimeTrans, double cycle);
Parameters
  • idmetering: The metering identifier
  • timeSta: The time of simulation in stationary period, in seconds from midnight.
  • amax: The new maximum green time, in seconds.
  • ngreenTime: The new green time, in seconds.
  • amin: The new minimum green time, in seconds.
  • ncycleTime: The new cycle time, in seconds.
  • offset: The new offset, in seconds.
  • yellowtime: The new yellow time, in seconds.
  • laneOffset: The delay activating green between lanes, in seconds.
  • currentTime: The current simulation time.
  • currentTimeTrans: The current simulation time without considering the warm up
  • cycle: The simulation step.
Output
  • = 0: No error occurred.
  • < 0: Error

Read the Control Parameters of a Flow Metering

In C++ and Python

Explanation

Read the parameters of a flow metering that are defined in the current control.

Format
int ECIGetParametersFlowMeteringById(int idmetering, double timeSta, double *amax, double *flow, double *amin);
int ECIGetParametersFlowMetering (int idsection, double timeSta, double * amax,double *flow, double *amin) (Deprecated function)
Parameters
  • idmetering: The metering identifier.
  • idsection: A valid section identifier.
  • timeSta: The time of simulation in stationary period, in seconds from midnight.
  • amax: Value returned for the maximum flow allowed.
  • flow: Value returned for the flow allowed.
  • amin: Value returned for the minimum flow allowed.
Output
  • = 0: No error occurred.
  • < 0: Error

Change the Control Parameters of a Flow Metering

In C++ and Python

Explanation

Changes the parameters of a flow metering that are defined in the current control.

Format
int ECIChangeParametersFlowMeteringById(int idmetering, double timeSta, double amax, double flow, double amin , double currentTime, double cycle);
int ECIChangeParametersFlowMetering (int idsection, double timeSta, double amax, double flow, double amin, double currentTime, double cycle) (Deprecated function)
int ECIChangeParametersFlowMeteringResetById(int idmetering, double timeSta, double amax, double flow, double amin, double currentTime, double cycle, bool resetToGreen);
Parameters
  • idmetering: The metering identifier.
  • idsection: A valid section identifier.
  • timeSta: The time of simulation in stationary period, in seconds from midnight.
  • amax: The new maximum flow allowed, in vehicles per hour.
  • newflow: The new flow allowed, in vehicles per hour.
  • amin: The new minimum flow allowed, in vehicles per hour.
  • currentTime: The current simulation time.
  • cycle: The current simulation step.
  • resetToGreen: If true it will reset the metering state. If false, it will consider the new rates after the next scheduled green
Output
  • = 0: No error occurred.
  • < 0: Error

Read the Control Parameters of a Flow-Alinea Metering

In C++ and Python

Explanation

Read the parameters of a flow-Alinea metering that are defined in the current control.

Format
int ECIGetParametersFlowAlineaMeteringById(int idmetering, double timeSta,  double *amax, double *flow, double *amin, double *kr, double *ostar, double *intervalUpdate);
Parameters
  • idmetering: The metering identifier.
  • timeSta: The time of simulation in stationary period, in seconds from midnight.
  • amax: Value returned for the maximum flow allowed.
  • flow: Value returned for the flow allowed.
  • amin: Value returned for the minimum flow allowed.
  • kr: Value for the regulator parameter for this metering.
  • ostar: Target occupancy on the main road.
  • intervalUpdate: Interval at which the flow is recalculated, in seconds.
Output
  • = 0: No error occurred.
  • < 0: Error

Change the Control Parameters of a Flow-Alinea Metering

In C++ and Python

Explanation

Changes the parameters of a flow-Alinea metering that are defined in the current control.

Format
int ECIChangeParametersFlowAlineaMeteringById(int idmetering, double timeSta, double amax, double flow, double amin, double kr, double ostar, double intervalUpdate, double currentTime, double cycle);
int ECIChangeParametersFlowAlineaMeteringResetById(int idmetering, double timeSta, double amax, double flow, double amin, double kr, double ostar, double intervalUpdate, double currentTime, double cycle, bool resetToGreen);
Parameters
  • idmetering: The metering identifier.
  • timeSta: The time of simulation in stationary period, in seconds from midnight.
  • amax: The new maximum flow allowed, in vehicles per hour.
  • newflow: The new flow allowed, in vehicles per hour.
  • amin: The new minimum flow allowed, in vehicles per hour.
  • kr: The regulator parameter.
  • ostar: The target occupancy on the main road.
  • intervalUpdate: The interval at which the flow will be recalculated, in seconds.
  • currentTime: The current simulation time.
  • cycle: The simulation step.
  • resetToGreen: If true it will reset the metering state. If false, it will consider the new rates after the next scheduled green.
Output
  • = 0: No error occurred.
  • <0: Error

Read the Control Parameters of a Delay Metering

In C++ and Python

Explanation

Read the parameters of a delay metering that are defined in the current control.

Format
int ECIGetParametersDelayMeteringById(int idmetering, double timeSta, double *avg, double *dev);
int ECIGetParametersDelayMetering (int idsection, double timeSta, double * avg, double *dev) (Deprecated function)
Parameters
  • idmetering: The metering identifier.
  • idsection: A valid section identifier.
  • timeSta: The time of simulation in stationary period, in seconds from midnight.
  • avg: Value returned for the average delay time.
  • dev: Value returned for the deviation delay time.
Output
  • = 0: No error occurred.
  • < 0: Error

Change the Control Parameters of a Delay Metering

In C++ and Python

Explanation

Changes the parameters of a delay metering that are defined in the current control.

Format
int ECIChangeParametersDelayMeteringById(int idmetering, double timeSta, double newavg, double newdev);
int ECIChangeParametersDelayMetering (int idsection, double timeSta, double newavg, double newdev) (Deprecated function)
Parameters
  • idmetering: The metering identifier.
  • idsection: A valid section identifier.
  • timeSta: The time of simulation in stationary period, in seconds from midnight.
  • newavg: The new average delay time.
  • newdev: The new deviation delay time.
Output
  • = 0: No error occurred.
  • < 0: Error

Change the Control Parameters of a Delay Metering for a vehicle type

In C++ and Python

Explanation

Changes the parameters of a delay metering that are defined in the current control for a specific vehicle type.

Format
int ECIChangeParametersDelayMeteringVehTypeById(int idmetering, double timeSta, double newavg, double newdev, int idVehPos)
int ECIChangeParametersDelayMeteringVehType(int idsection, double timeSta, double newavg, double newdev, int idVehPos) (Deprecated function)
Parameters
  • idmetering: The metering identifier.
  • idsection: A valid section identifier.
  • timeSta: The time of simulation in stationary period, in seconds from midnight.
  • newavg: The new average delay time.
  • newdev: The new deviation delay time.
  • idVehPos: The vehicle type position.
Output
  • = 0: No error occurred.
  • < 0: Error

Disable the fixed control plan of a metering

In C++ and Python

Explanation

Disables the current fixed control plan of a metering, so the state changes are completely controlled by the Aimsun Next API Module.

Format
int ECIDisableEventsMeteringById(int idmetering);
int ECIDisableEventsMetering(int idsection) (Deprecated function)
Parameters
  • idmetering: The metering identifier.
  • idsection: A valid section identifier.
Output
  • = 0: No error occurred.
  • < 0: Error

Enable the fixed control plan of a metering

In C++ and Python

Explanation

Enables the current fixed control plan of a metering, so the state changes are completely controlled by Aimsun Next , taking into account the parameters defined in the current control.

Format
int ECIEnableEventsMeteringById(int idmetering)
int ECIEnableEventsMetering (int idsection) (Deprecated function)
Parameters
  • idmetering: The metering identifier.
  • idsection: A valid section identifier.
Output
  • = 0: No error occurred.
  • < 0: Error

Change the State of a metering

In C++ and Python

Explanation

Changes the state of a metering. If the control structure is enabled, Aimsun Next programs the next change, taking into account the parameters that define the control. In Green and Flow meterings it is possible to change to green and to red, but in delay meterings it is only possible to change to green and it is necessary to define in which lane.

Format
int ECIChangeStateMeteringById(int idmetering, int aState, double time, double cycle, int identity, double timeProportion=0.0)
int ECIChangeStateMetering(int idsection, int aState, double time, double cycle, int identity) (Deprecated function)
Parameters
  • idmetering: The metering identifier.
  • idsection: A valid section identifier.
  • aState: A valid state( 0: RED 1:GREEN 2:YELLOW).
  • time: A relative time of simulation in seconds.
  • cycle: The duration of each simulation step in seconds.
  • identity: Is the number of Lane 1...N. Only in Delay Meterings or Green-Time by lane meterings needs to be specified.
Output
  • = 0: No error occurred.
  • < 0: Error

Get Current State of a metering

In C++ and Python

Explanation

Gets the current state of a metering.

Forma
int ECIGetCurrentStateofMeteringById(int idmetering, int idlane)
int ECIGetCurrentStateofMetering(int idsection, int identity) (Deprecated function)
Parameters
  • idmetering: The metering identifier.
  • idsection: A valid section identifier.
  • identity: Is the number of Lane 1...N. Only in Delay Meterings.
Output
  • ≥ 0: The Current State ( 0: RED 1:GREEN 2:YELLOW)
  • < 0: Error