Home

TraSMAPI-Aimsun

This is a TraSMAPI specialisation for Aimsun simulator.

TraSMAPI is a generic API used as bridge for microscopic traffic simulators (what is a microscopic simulator?) that allows real-time communication between agents in the urban traffic context (such as vehicles, traffic lights and pedestrians) and the environment created by various simulators. This tool was developed at LIACC (Artificial Intelligence and Computer Science Laboratory), University of Porto.

Aimsun is a traffic modelling software that allows you to model anything from a single bus lane to an entire region. With thousands of licensed users in government agencies, consultancies and universities all over the world, Aimsun stands out for the exceptionally high speed of its simulations and for fusing travel demand modelling, static and dynamic traffic assignment with mesoscopic, microscopic and hybrid simulation.

Table of Contents

• Usage
• Contributing
• Published papers
• License

Usage

TraSMAPI is written in Java. To use this extension you first need to include TraSMAPI into your project. That can simply be done by creating a trasmapi package and by cloning the genApi folder into there. Then, you have to include in that same trasmapi package the aimsun folder that is in this repository.

To perform the communication between TraSMAPI and Aimsun, it is necessary to implement a dedicated communication module in TraSMAPI which interconnects with the Aimsun’s API module (Figure 1). The Aimsun API module is placed, in the functional point of view, between the Aimsun simulator and the TraSMAPI.

Figure 1: Communication protocol

There are two types of communication processes that will be focused:

• between the Aimsun simulator and the Aimsun API module, provided by the Aimsun environment;
• between the Aimsun API module and the TraSMAPI, implemented by the user.

Every simulation step, Aimsun traffic simulator communicates with our algorithm trough the communication protocol.

The communication protocol was tested by us for version 6 and 7 of Aimsun simulator. Beyond Aimsun simulator license is necessary to have the supplement of Aimsun API Module.

Aimsun Environment

The Aimsun’s API Module allows the interface of almost any external application that may need access to some internal data of Aimsun during simulation run time since it has direct access to the simulation functions. The interaction between Aimsun simulator and its API module is performed by a set of functions provided by an interface of Aimsun. This set of functions allows the Aimsun’s API module to obtain information from the simulation model and modify the simulation state. Moreover, the external application must connect and establish a communication process with the API to take advantage of these functionalities. It is not possible to create new functions. However you can try to contact simulator support (suport@aimsun.com) and describe your problem, if they get interested they can include the new function in the next simulator version. The functions available depend of the Aimsun simulator version.

The Aimsun API module gives, to the user, the possibility of choose between two programming languages: C/C++ or Python. We used the C/C++ programming language to create an Aimsun API Extension. The C++ Aimsun API Extension (in apiAIMSUN_ folder) is a dynamic library that contains the desired code that will interact with the Aimsun. This folder includes by default some files as following:

• 5 header files (AKIProxie.h, CIProxie.h, ANGConProxie.h, AAPI_Util.h);
• 1 library (angext.lib);
• 2 samples files (AAPI.h, AAPI.cxx).

We can only modify the sample file AAPI.cxx. Below you can see parts of that file with some comments:

(...)
// Here, it can be defined Aimsun functions that are
// not simulation time dependent
int getNumberOfControlPlansLoaded()
{
   return ECIGetNumberofControls();
}

int AAPILoad() { (...) }
int AAPIInit() { (...) }

(...)

int AAPIManage(double time, double timeSta, double timTrans, double acicle)
{
   (...)
   while(strcmp(in,"DONE!") != 0) {
      (...)
      if(getToken(in,0).compare("ECIGetDurationsPhase") == 0)
      {
         // Here, it can be defined Aimsun functions time dependent
         // Function 1 (see API manual)
      }
      else
      {
         if(getToken(in,0).compare("ECIGetNumberPhases") == 0)
         {
            // Function 2 (see API manual)
         }
         else
         {
            // Function n (see API manual)
         }
      }
   }
}

int AAPIPostManage(double time, double timeSta, double timTrans, double acicle) { (...) }
int AAPIFinish() { (...) }
int AAPIUnLoad() { (...) }

The file has to have six high level functions defined in order to guarantee the communication between the Aimsun API Module and the Aimsun Simulation model: AAPILoad(), AAPIInit(), AAPIManage(), AAPIPostManage(), AAPIFinish() and AAPIUnLoad(). As explained before, the functions which are responsible for exchange information or modify its state dynamically should be defined in the AAPIManage() function as stated in the above comments. After defining the selected functions in the file, the project is ready to compile and build the DLL file - AAPI_D.dll. Every time the user includes a new function from repository is necessary to compile and build the library. The AAPI.cxx file should be edit using Microsoft Visual Studio C++. In this work, we used version of 2010.
The dynamic library file (AAPI_D.dll) must be loaded in Aimsun simulator in order to complete the communication in Aimsun environment. In order to follow the dialogs in Figure 2:

• open Aimsun file;
• click on the “Scenario” -> Properties and a new dialog will appear;
• select the Aimsun API tab folder;
• using the Add button or Remove button the user can load or unload a set of Aimsun Extensions (Dynamic libraries or Python scripts);
• check the desired Aimsun extension -> ok click.

Figure 2: Adding AAPI_D.dll

Note: If the Aismun Api folder named by us as “AAPIVisual” change the path location, it is necessary to upload again the folder in Aimsun simulator as explained above.

Aimsun Environment - TraSMAPI Environment

To link between TraSMAPI module and Aimsun API Module, it was develop a communication protocol supported in sockets (Figure 3).

Figure 3: Link between TraSMAPI module and Aimsun API Module

In the AAPI.cxx file (described in section above) is also defined the socket number in the Aimsun environment, in order to promote the communication between Aimsun API module and TraSMAPI environment.

In short the overall information flux between the several components is presented in Figure 4. This information flux occurs, for each function request of algorithm, in each simulation interval. The input data is passed through the API that asks the simulator for the function result and returns it back to the algorithm.

Figure 4: Information flux in communication protocol

Our case

The communication between our algorithm and traffic simulator allows us to get information from the simulation model and modify the simulation state during the simulation. The road network is modelled in traffic simulator. The TraSMAPI framework allows building an abstraction of this traffic light, and controlling the simulation lifecycle. For more information see our published papers.

We have created a batch file in order to run several Aimsun simulations in console mode without user interaction:

C:
REM Temos de por os ficheiros todos na mesma diretoria
@ECHO off

SET /a j=0 

:loopname2
	set /a j=%j%+1
	echo Loop number file -^>%j%
	SET /a i=0

	:loopname21
		ECHO Replication -^>%i%
		cd C:\Program Files (x86)\TSS-Transport Simulation Systems\Aimsun 7.0\
		start aconsole.exe -script "C:\Users\pdst11008\Dropbox (Pessoal)\PDST\Analise ITC\No warm_up\cemiterio_S1.py" %j% %i% -v
		timeout /t 15
		cd C:\Users\pdst11008\Dropbox (Pessoal)\PDST\Analise ITC\No warm_up
		winAimsun29.jar
		ECHO end
		set /a i=%i%+1 
	if %i% NEQ 25 goto loopname21
if %j% NEQ 1 goto loopname2

pause
exit

Contributing

We appreciate any help you could give by improving our code, documention, or by simpling creating an issue. If you wish you can contact us at stems.group@gmail.com

Submitting a Pull Request

1. Fork it.
2. Create a branch (git checkout -b my_trasmapi)
3. Commit your changes (git commit -am "Added message type")
4. Push to the branch (git push origin my_trasmapi)
5. Open a Pull Request
6. Enjoy a refreshing Diet Coke and wait

Published papers

• Vilarinho, C., Soares, G., Macedo, J., Tavares, J. P. & Rossetti, R. J. F. 2013. Capability-Enhanced AIMSUN with Real-Time Signal Timing Control. Procedia - Social and Behavioral Sciences, EWGT2013 – 16th Meeting of the EURO Working Group on Transportation, 262-221.
• Vilarinho, C. & Tavares, J. P. 2014. Real-time traffic signal settings at an isolated signal control intersection Transportation Research Procedia (TRPRO264)
• Vilarinho, C., Tavares, J. P. & Rossetti, R. J. 2015. A Conceptual MAS Model for Real-Time Traffic Control. Progress in Artificial Intelligence. Springer.

License

Copyright 2016 STEMS-group

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.