Department of Adaptive Systems

UTIA,
AV CR
P.O.Box 18, 182 08 Prague 8,Czech Republic

RESEARCH REPORT

Petr Gebousk
y

AIMSUN MATLAB
Interface Toolbox
Users Guide

Version 1.0

November, 2005

1F43A/003/120, MSMT

MD CR
1M0572

Tel: +420-266052061

Fax: +420-266052068

E-mail: school@utia.cas.cz

Abstract
This text is the basic users guide for the manipulation with the toolbox implementing interface between AIMSUN and MATLAB. Besides the basic instructions, some technical details of
implementation are outlined.

Aim of Toolbox

The aim of AIMSUN MATLAB interface toolbox is to implement the interface between MATLAB
environment and AIMSUN simulator for the purpose of testing of designed traffic control of special
type.
The AIMSUN simulator [2] is powerful tool for simulation of traffic flow while the MATLAB environment [1] provides the rich set of functions that simplify the process of design, optimization and
testing of developed traffic control. Toolbox combines together advantages of both of them.
This text presume the knowledge of AIMSUN and TEDI manipulation.
Acknowledgment: Creation of this toolbox was partially supported by the grants RIZDOP03 (MD
1F43A/003/120) and DAR (MSMT

CR
1M0572).

Specificity of Toolbox

Toolbox allows to realize special type of macroscopic control with the fixed control/sampling period.
It comes out from the goals of the project. Its aim is to develop coordinated traffic control on the wide
area with tens of controlled junctions. Basic prerequisite is relatively long control/sampling period
(about minutes) for gathering the data on the level of network of junctions and subsequent application
of control actions.
The simple loop detectors are considered to exist in the traffic network only. Therefore counts and
occupancy from the detectors can be gathered only.
The chosen sampling period of coordinated traffic control is equivalent to the period of switching
(synchronization) of software control between MATLAB and AIMSUN. Therefore switching of control
between them are not realized in each simulation step, but only periodically determined by the sampling
period. It helps to minimize an increase of time necessary for simulation run spent on synchronization.
Counts of passing vehicles and occupancies on detectors in each sampling/control period are accessible from MATLAB environment. Functions of the toolbox then allow to change timing of phases of the
predefined control plan on all controlled junctions in the network. Allowed control actions are only the
changes of time of phases. It means that both the rates of phases and the length of cycle of control plan
can be changed. But it is not possible to switch the order of phases. It correspondes to reality, where
the optimal ordering of phases is determined, timing of phases is varying according the conditions only.
A special complement of the toolbox is possibility to acquire average and maximal queues per lane
in the sections of traffic network. It is implemented for the purpose of testing of queue length estimator
from basic detectors data. Estimates of queue length serve as input to the controller under development
in this main project.
The latest version of toolbox also offers the possibility to insert number of vehicles on entrances of
network directly from MATLAB, when the so called AIMSUN results containers are used. Generally,
both results containers (vehicle entrance numbers + turning rates on junctions) and OD matrices can
be employed in AIMSUN together with this toolbox. Though, the specification of number vehicles on
entrances directly from MATLAB works only for result containers now. The reason is preffered result
containers for definition of traffic flow.

Contents of Toolbox

Toolbox contains two main parts necessary to implement the connection between MATLAB environment
and AIMSUN: general shared dynamic library and set of MATLAB functions.

3.1

General Dynamic Library

The dynamic library forms the core of the implemented interface. It has to be linked both to the
AIMSUN and MATLAB before running simulation.
Interface and synchronization between MATLAB and AIMSUN are implemented by means of shared
files in the Windows pagefile. The shared data are represented by the C structures, where all the used
arrays are static. The bounds are fixed and sufficiently high (see Table 1). If it would not suffice, it is
possible to recompile the library with the new bounds.
Detectors
100

Junctions
100

Sections
100

Phases of Junctions
16

Vehicle types
10

Table 1: Fixed limits for number of elements in traffic network

3.2

MATLAB functions

Toolbox includes set of MATLAB functions that realize link and unlink of general dynamic library,
synchronization with and access function for obtaining and changing the information in AIMSUN. All
functions are listed bellow:
after error
function info
get data
get junctions
get sections
get total statistics
load ini information
return activity
sort hash

export phases
generate input flows
get detectors
get lock
get simulation time
get veh types
load library
select random generator
start AIMSUN

export vehicle flows

get actual time
get entrance sections
get sampling time
get statistics time
load final information
load step information
set vehicle rates
unload library

Detailed information about functions is given in the Appendix A.

In addition to the functions directly used in interface, the toolbox contains also few functions that
simplify and automate building of ASCII file, that defines the result container. Such created file can be
imported to the TEDI editor of AIMSUN package thereafter. These functions are:
create area inflow
generate traffic result

create junction

create vehicle

Usage of Toolbox

Manipulation with the prepared interface toolbox and AIMSUN simulator has to follow some basic
rules described hereafter. Set of necessary instructions is divided into three groups according the place
of their application.

4.1

Before the First Usage of Toolbox

After instalation of the toolbox (directory), the path has to be set to this directory in MATLAB. Besides
the path to the AIMSUN directory (which contains file aimsun*.exe) has to be modified in function
start_AIMSUN to the actual one.

4.2

Preparation of Simulation Experiment in AIMSUN

Before the running simulation in AIMSUN with the realized MATLAB interface, it is necessary to
prepare simulation experiment in AIMSUN. Such experiment has to be open and ready in AIMSUN or
even better, saved as AIMSUN scenario. The saved scenario can be then simply called directly from
MATLAB using function start_AIMSUN. Such simulation experiment (scenario) comprehends:
Loaded traffic network.
Set simulation time of experiment.
Loaded traffic result or O/D matrices. Suitable generator of vehicle entrances for both of them
has to be selected. In case of employment of ASCII files representing the result container, it has
to be imported in TEDI editor first of all. It is visible from AIMSUN then. It is recommended to
delete result container of the same name before importing new one from ASCII file.
If it is planned to use the possibility to generate vehicles directly from MATLAB , all states of
result container should define only turning rates on junctions. Vehicle entrances should stay zero.
In this case, the random generator is selected from MATLAB.
Loaded predefined control plan with described phases on each junction. The control plan has to
applied during the whole time of simulation. The control on individual junctions in this control
plan has to be set to external (if external control is supposed) and the lower and upper bounds
of times of phases selected reasonably, as only then it is possible to change these times from
MATLAB within these bounds.
Loaded dynamic library (*.dll), that is a part of toolbox, by means of extensions.
Set the aggregated detection time to the desired sampling/control period. It corresponds the
period of synchronization with MATLAB.
If measurement of queue lengths are in demand, time interval of the periodic statistics gathering
has to be set to the same value as sampling/control period and items determining that statistics
data from all sections selected.

4.3

Structure of MATLAB Script

Basic structure of a m-script that employs developed interface should follow the blueprint saved in
_default.m listed bellow. Starting of such script realizes the simulation experiment with conected
interface.
The blueprint contains instructions in the form of comments. Positions, where the modifications
according the actual conditions and simulation experiment have to be applied are labelled (OPTIONAL)
or (SWITCH). Further information about individual functions can be found in function references, see
Section A.
% basic blueprint of m-script realizing the AIMSUN simulation with employed interface toolbox

%####################################

% Preliminary block
%####################################
disp(AIMSUN simulation can start...);
%***************************************************
%**
**
% (OPTIONAL)
% calling of saved AIMSUN scenario from MATLAB
% (1- console, 2- GUI with visualization 3- GUI without visualization)
% (the alternative is to run scenario directly from AIMSUN. If so, after
% running the m-script, the simulation has to be started in AIMSUN)
start_AIMSUN(C:\AIMSUNpr\smichovNEW.sce,1);
%**
**
%***************************************************
load_library;
disp(Waiting for AIMSUN simulation initialization...);
while (get_lock == 0)
end
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
% AIMSUN initialization information load and first prior setting
% of junction phase timing
if (get_lock ==1),
load_ini_information;
sim_time=get_simulation_time;
sam_time=get_sampling_time;
[n_detectors, ID_detectors]
[n_sections, ID_sections]
[n_junctions, JunctionNphases]
[n_vehicle_types]

=
=
=
=

get_detectors;
get_sections;
get_junctions;
get_veh_types;

% use ONLY if vehicles will be entered from MATLAB

[n_entr_sections, ID_entr_sections]=
get_entrance_sections;
%***************************************************
%**
**
%(OPTIONAL)
% selection of detectors from which the counts and occupancy will be
% gained in this order. Each row of matrix define, data of which
% detector will be on this position. If the rows of matrix contain more numbers of
% detectors the data will be aggregated. Superfluous positions should contain NaN
detectors=ID_detectors;
%**
**
%***************************************************
%***************************************************
%**
**
%(OPTIONAL)
% selection of sections from which the queues will be
% gained in this order. Each row of matrix define, data of which
% section will be on this position. If the rows of matrix contain more numbers of
% sections the data will be aggregated. Superfluous positions should cantain NaN
%
%
%
%
%
%
%
%
%
%
%
%
%

sekce=[ 4
40
1
2
8
5
37
13
33
38
36
9
16

42;
NaN;
NaN;
3;
NaN;
12;
NaN;
NaN;
NaN;
NaN;
NaN;
NaN;
NaN;

%
%
%
%
%
%
%
%
%
%
%
%
%

Zborovska vstup
Korenskeho
Zborovska (Vbotanice)
V Botanice
Zborovska (Matousova)
Matousova
Zborovska (Lesnicka)
Zborovska (Matousova) -protismer
Lesnicka
Zborovska (Pechackova)
Pechackova
Zborovska (Lidicka)
Lidicka

%
%
%
%
%
%
%
%
%

21
NaN;
% Lidicka (od Motola)
32
NaN;
% Svornosti (Na belidle)
14
NaN;
% Svornosti (Lidicka) -protismer
31
NaN;
% Na belidle
29
NaN;
% Svornosti (Vrazova)
28
NaN;
% Vrazova
25
NaN;
% Svornosti(Jindricha Plachty)
10
NaN;
% Svornosti (Vltavska)
6
22];
% Vltavska
sections=ID_sections;
%**
**
%***************************************************
%***************************************************
%**
**
% (OPTIONAL)
% the choice of the order of junctions, for which phase timing will be set
% vector
junctions = JunctionNphases(:,1);
%**
**
%***************************************************

%***************************************************
%**
**
% (OPTIONAL)
% IF vehicles will be entered from MATLAB
% the choice of the order of entrance section, for which the number of vehicles
% will be inserted in this order
% vector
entrance_sections = ID_entr_sections;
%**
**
%***************************************************

% (SWITCH)
% 1. if vehicles are not entered in MATLAB
[seq_det, seq_sec, seq_jun]=sort_hash(detectors, sections, junctions);
% 2. if vehicles are entered in MATLAB
[seq_det, seq_sec, seq_jun, seq_esec]=sort_hash(detectors, sections, junctions, entrance_sections);
% (OPTIONAL)
%??? Generate vehicles from MATLAB? 0/1
generate_input_flows(0);
% (SWITCH)
%??? Which random generator to use to enter vehicles (0-normal, 1-constant, 2-uniform, 3%exponential (only when vehicles are entered from MATLAB)
select_random_generator(0);

%####################################
% initialization block
%####################################
% (OPTIONAL)
% IF the vehicles are generated from MATLAB
%??the rate of vehicle types in all flows in network
%the vehicle types are listed in AIMSUN (X)console
% (the vehicle types has to be specified in result container)
vehicle_rate=ones(1,n_vehicle_types)/n_vehicle_types;
set_vehicle_rates(vehicle_rate);
% ??number of vehicles entering the entrance sections in selected order
% during the (detector) sampling period
vehicles =zeros(1,n_entr_sections);
export_vehicle_flows(vehicles, seq_esec);

% (SWITCH)
% if to set the junction phase timing
% 1. setting the length (seconds) of phases on individual controlled
% junctions
%***************************************************
%**
**
% timing for individual junctions (rows) in selected order of junctions
% the order of phases (and interphases) have to be read from AIMSUN.
% The matrix should have at least number of columns = maximal number of
% phases for all junctions
phase=[ 20 4
20 32 4
27 5
26
31 5
40

52 4
20 4
4
13
4
0

0
0;
5;
0];

0;

%**
**
%***************************************************
export_phases(phase, seq_jun);
% 2. return control to AIMSUN without phase timing setting
return_activity;
while (get_lock == 0)
end
end
% initialization end
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

%+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
% simulation step
disp(AIMSUN simulation is running...);
while (get_lock ~= 2)
load_step_information;
%
%ziskani pozadovanych dat v maticich prislusnem poradi
%pro detektory jsou v prvnim sloupci pocty projetych aut, v druhem
%obsazenosti v procentech, ve tretim rychlosti
%pro delky front pak prvni sloupec vraci prumernou druhy pak maximalni delku kolony na pruh
[data_detectors,data_sections] = get_data(seq_det,seq_sec);
%####################################
% simulation step block

%####################################
% (OPTIONAL)
% IF the vehicles are generated from MATLAB
%??the rate of vehicle types in all flows in network
%the vehicle types are listed in AIMSUN (X)console
vehicle_rate=ones(1,n_vehicle_types)/n_vehicle_types;
set_vehicle_rates(vehicle_rate);
% ??number of vehicles entering the entrance sections in selected order
% during the (detector) sampling period
vehicles =zeros(1,n_entr_sections);
export_vehicle_flows(vehicles, seq_esec);

% (SWITCH)
% if to set the junction phase timing
% 1. setting the length (seconds) of phases on individual controlled
% junctions

%***************************************************
%**
**
% timing for individual junctions (rows) in selected order of junctions
% the order of phases (and interphases) have to be read from AIMSUN.
% The matrix should have at least number of columns = maximal number of
% phases for all junctions
phase=[ 20 4
20 32 4
27 5
26
31 5
40

52 4
20 4
4
13
4
0

0
0;
5;
0];

0;

%**
**
%***************************************************
export_phases(phase, seq_jun);
% 2. return control to AIMSUN without phase timing setting
return_activity;
while (get_lock == 0)
end
end
% simulation step end
disp(AIMSUN simulation is finished.);
load_final_information;
[flow,travel_timeA,travel_timeD,delay_timeA, delay_timeD,speedA, speedD, ...
density, stop_timeA, stop_timeD,n_stops,total_travel]=get_total_statistics;
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

%####################################
% finalization block
%####################################
% unload library
unload_library;

4.4

Repeated Simulations

The simulation without the changes to the AIMSUN scenario can be run repeatedly. Then it is necessary
to rewind the simulation in AIMSUN environmnent to its beginning before each simulation. If the
AIMSUN console is used no actions are necessary.

4.5
4.5.1

Exceptional Events
Stopping the Simulation from AIMSUN

It is possible to stop the simulation in an arbitrary moment from AIMSUN. Then for the repeated
simulation it is necessary to rewind the simulation to its beginning and run the MATLAB m-script
again.
If the function start_AIMSUN with option to run AIMSUN enviroment is used in m-script, new
instance of AIMSUN is opened every time the function is called.
If the AIMSUN console is used for the simulation, it can be stopped by pressing Ctrl+C. After that,
the m-script in MATLAB has to be stopped using again Ctrl+C and calling function after_error.
4.5.2

Stopping the Simulation from MATLAB

If the simulation is interrupted from MATLAB (e.g. due to the error in the code) the simulation halts.
Then it is necessary to call the function after_error. It causes that the action is returned back to

AIMSUN. Then the simulation in AIMSUN follows but without the synchronization and control from
MATLAB. Finally stopping the simulation from AIMSUN has to be applied.
If AIMSUN console is used, it has to be stopped by pressing Ctrl+C too.

4.6

Preparation of Result Containers

The toolbox allows automated creation of two versions of ASCII files representing result container at
present.
The first one supposes that the vehicle entrances are controlled from AIMSUN and turning rates
on all junctions are fixed during the whole simulation. Also rates of vehicle types can be defined
only constant for the whole network and simulation time.
The second one allows to define varying turning rates during simulation, while the vehicle entrances
are supposed to be controlled from MATLAB. Rates of vehicle types are considered same for the
whole network, but variation during simulation time can be generated again from MATLAB.
Simple illustrative example scripts of the generation of traffic results for both versions are listed bellow.
These examples form the contents of two scripts named _exampleTR1 and _exampleTR2, saved in the
toolbox directory.
Example of simple script generating result container ASCII for fixed turning rates and
vehicle entrance control done totally in AIMSUN
% Example of constructor of result container (ASCII file) with fixed turning rates and non-zero entrances (generated in AIMSUN)
%suppose matrix DATA exists and contains number of vehicles entering the
%network. Rows correspond to sampling periods, while the columns various
%entrances
% starting time of simulation (vector of dimension 3 [hours minutes seconds])
t_init = [0 0 0];
% fixed sampling period (in seconds) of gathered data and generated states
t_sample = 90;
% name of the generated file (it coincides with result container name)
file_name = realBezUt;
% relate IDs of entrance sections with columns of DATA matrix
IDinpSec = [9 7 1];
% IDs of entrance sections
inflow = create_area_inflow(IDinpSec, DATA);
% define the vehicle types in network and their rates
% such vehicle types have to be predefined in TEDI
vehicles(1) = create_vehicle(car,0.9);
vehicles(2) = create_vehicle(truck,.1);
% definition of junctions and fixed turning rates on them
turnings = [.4 .6; .1 .9];
junctions(1) = create_junction(1,2,2, [1 6], [2 12], turnings);
turnings = [.80 .2; .23 .77];
junctions(2) = create_junction(2,2,2, [7 11], [6 8], turnings);

% NOT MODIFY HEREAFTER

% construction
% ASCII file
tr.file_name =
tr.t_sample =
tr.t_init
=
tr.inflow
=

of MATLAB structure, necessary to generate traffic result

file_name;
t_sample;
t_init;
inflow;

tr.junctions = junctions;
tr.vehicles = vehicles;
generate_traffic_result(tr,1);

Example of simple script generating result container ASCII for varying turning rates and
vehicle entrance control done only in MATLAB
% Example of constructor of result container (ASCII file) with varible turning rates and zero entrances (entrances generated from MATLAB)

% starting time of simulation (vector of dimension 3 [hours minutes seconds])

t_init = [0 0 0];
% name of the generated file (it coincides with result container name)
file_name=realBezUt;
% defines the IDs of input sections
IDinpSec=[9 7 1];
% IDs of entrance sections
inflow=create_area_inflow(IDinpSec);
% define the vehicle types in network
% such vehicle types have to be predefined in TEDI
vehicles(1)=create_vehicle(car);
vehicles(2)=create_vehicle(truck);
% definition of junctions and varying turning rates on them
turnings{1}=[.4 .6; .1 .9];
turnings{2}=[.5 .5; .2 .8];
junctions(1)=create_junction(1,2,2, [1 6], [2 12], turnings);
turnings{1}=[.8 .2; .23 .77];
turnings{2}=[.7 .3; .23 .77];
junctions(2)=create_junction(2,2,2, [7 11], [6 8], turnings);
% definition of times, where turning rates change
% matrix having 3 columns for determination of time [hours minutes seconds]
% number of rows corresponds with dimension of cell vectors turning for all junctions
t_turning = [0 0 0; 10 0 0];

% NOT MODIFY HEREAFTER

% construction
% ASCII file
tr.file_name =
tr.t_init
=
tr.junctions =
tr.vehicles =
tr.t_turning =
tr.inflow
=

of MATLAB structure, necessary to generate traffic result

file_name;
t_init;
junctions;
vehicles;
t_turning;
inflow;

generate_traffic_result(tr,1);

MATLAB Function References

In order to simplify maintenance of the toolbox documentation, the function reference list is not included
directly in the document. Only the reference to the html version at http://marabu.utia.cas.cz:
1800/svn/doprava/AIMSUN-MATLAB/toolbox/htmldoc/index.html is mentioned here.

References
[1] The MathWorks, Inc. MATLAB Users Guide, 1992.

10

[2] TSS - Transport Simulation Systems. AIMSUN User Manual, version 4.2, 2004.

11