![DOI:[not_published_yet]](https://doi.org/10.1109/ITSC55140.2022.9922508.svg)
- Collection of open-source and well documented tools for the synthesis, analysis, and simulation of store-and-forward models of urban road networks in MATLAB
- Full model of the urban traffic network of the city center of Chania, Greece
- Implementation of state-of-the-art traffic responsive signal control strategies
The SAFFRON toolbox is introduced to synthesize, analyze, and simulate store-and-forward based strategies for the signal control problem in congested urban road networks in MATLAB. SAFFRON is tecnhically described in
If you use SAFFRON, reference the publication above.
@inproceedings{PedrosoBatistaEtAl2022Saffron,
author = {Leonardo Pedroso and Pedro Batista and Markos Papageorgiou and Elias Kosmatopoulos},
title = {{SAFFRON}: {Store-And-Forward} model toolbox {For} urban {ROad} {Network} signal control in {MATLAB}},
booktitle = {2022 IEEE 25th International Conference on Intelligent Transportation Systems (ITSC)},
year = {2022},
pages = {3698-3703},
doi = {10.1109/ITSC55140.2022.9922508}
}SAFFRON allows to:
- Seamlessly simulate store-and-forward based signal control strategies
- Apply novel solutions to a meaningful model that is publicly available and, hence, can be reproduced
- Compare novel solutions with other control strategies with little effort
Low-level thorough documentation is provided in the repository page, as well as in the source files.
The community is encouraged to contribute to SAFFRON with suggestions, additions, and the implementation of signal control strategies.
Leonardo Pedroso1 
Pedro Batista1
Markos Papageorgiou2,3
Elias Kosmatopoulos4
1Institute for Systems and Robotics, Instituto Superior Técnico, Universidade de Lisboa, Portugal
2Dynamic Systems and Simulation Laboratory, Technical University of Crete, Chania, Greece
3Faculty of Maritime and Transportation, Ningbo University, Ningbo, China
4Department of Electrical and Computer Engineering, Democritus University of Thrace, Xanthi, Greece
SAFFRON toolbox is currently maintained by Leonardo Pedroso (leonardo.pedroso@tecnico.ulisboa.pt).
The documentation is divided into the following categories:
A store-and-forward urban road network can be synthesized seamlessly with SAFFRON by filling a custom spreadsheet. A template is provided in a subfolder of the repository. The following data is input in the spreadsheet:
- the number of junctions
$J$ , links$Z$ , and stages$S$ , control cycle$C$ , simulation cycle$T$ , and the upstream gating parameter$c_ug$ - the lost time and number of stages in each junction
- the capacity, saturation flow, number of lanes, initial number of vehicles, and demand flow for each link
- the minimum green time and historic green time of each stage
- the stage matrix
$\mathbf{S}$ , i.e., a table that indicates which links have right of way (r.o.w.) for each stage - the turning rates matrix
$\mathbf{T}$ , i.e., a table that indicates the probability of turning into the links of the network on the exit of a certain link, and the exit rate of all links$\mathbf{t_0}$
Each table of the spreadsheet has to copied and pasted to txt whose names are indicated next to each table in the spreadsheet. These txt files have to be enclosed in a folder with the name of the urban road model. Template txt files and an example of this procedure are provided in a subfolder of the repository.
The model is loaded into MATLAB making use of the following command
>> model = SFMSynthesis("directory")
where directory is the enclosing folder of the txt files and model is a MATLAB struct object that characterizes the urban road network. The command above also saves the model object, as well as the raw input tables, in the file data.txt in the model folder. Thus afterwards the models can also be loaded using
>> model = load("directory/data.mat")
The fields of store-and-forward model object struct are
| Field | Description | Notation |
|---|---|---|
| J | Number of junctions | |
| Z | Number of junctions | |
| nStages | Number of stages | |
| C | Control cycle (s) | |
| c | Upstream gating parameter | |
| Tsim | Simulation cycle (s) | |
| lostTime | Column vector of lost times (s) in each junction | |
| nStagesJunction | Column vector of number of stages of each junction | |
| capacity | Column vector of capacity of each link (veh) | |
| saturation | Column vector of saturation flow of each link (veh/s) | |
| lanes | Column vector of number of lanes in each link | - |
| x0 | Initial number of vehicles of each link (veh) | |
| d | Column vector of demand on each link (veh/s) | |
| gmin | Column vector of minimum green time of each stage (s) | |
| gN | Column vector of historic green time of each stage (s) | |
| T | Turning rates matrix | |
| t0 | Exit rates vector | |
| S | Stage matrix | |
| junctions | Cell array indexed by junction number that contains the number of the stages associated with that junction (see example below) | - |
| links |
|
- |
| inLinks | Column vector of link indices that originate from outside the network | - |
| notInLinks | Column vector of link indices that do not originate from outside the network | - |
| A | State-space matrix |
|
| Bu | State-space matrix |
|
| BG | State-space matrix |
|
| Bg | State-space matrix |
|
| Bu_sim | State-space matrix |
- |
| BG_sim | State-space matrix |
- |
| Bg_sim | State-space matrix |
- |
| C_z | State-space matrix |
|
| E_DTUC_psi | Sparsity matrix of the controller gain for the decentralized control strategy DTUC with decentralized configuration |
|
| E_DTUC_phi | Sparsity matrix of the controller gain for the decentralized control strategy DTUC with decentralized configuration |
|
| E_D2TUC_psi | Sparsity matrix of the controller gain for the decentralized control strategy D2TUC with decentralized configuration |
|
| E_D2TUC_phi | Sparsity matrix of the controller gain for the decentralized control strategy D2TUC with decentralized configuration |
Example: Load the Chania urban road network provided in SAFFRON
>> chania = SFMSynthesis('ChaniaUrbanRoadModel'); % Load Chania, Greece urban road network >> chania.S % Get number of stages ans = 42 >> chania.nStagesJunction(4) % Get number of stages associated with junction 4 ans = 3 >> chania.junctions{4} % Get the indices of the stages associated with junction 4 ans = 8 9 10 >> chania.links(13,:) % Get origin and destination junction of link 13 ans = 5 4 % Link 13 goes from junction 5 towards junction 4
It is possible to check if the traffic network is open and if it has a minimum complete stage strategy. These properties are defined with rigour in (Pedroso and Batista, 2021). They are closely related with the controllability of the store-and-forward model.
A traffic network is said to be open if there is a directed walk starting at every link which a vehicle may follow to exit the network with non-zero probability. (Pedroso and Batista, 2021)
A traffic network is said to be feasible if it is finite and open. (Pedroso and Batista, 2021)
To check if the store-and-forward model model is open, thus fesible, the following command is used
>> flag = isOpen(model);
which outputs a boolean.
To check if the store-and-forward model model has a minimum complete stage strategy, the following command is used
>> flag = isMinimumComplete(model);
which outputs a boolean.
Example: Check if the Chania urban road network provided in SAFFRON is open and if it has a minimum complete stage strategy
>> chania = SFMSynthesis('ChaniaUrbanRoadModel'); % Load Chania, Greece urban road network >> flag = isOpen(chania) % Check if it is open flag = logical 1 >> flag = isMinimumComplete(chania) % Get it has a minimum complete stage strategy flag = logical 1
The performance metrics total time spent (TTS)
and relative queue balance (RQB)
introcuced in (Aboudolas, Papageorgiou, and Kosmatopoulos, 2009) can be computed seamlessly with SAFFRON.
Let xNL be a
>> [TTS,RQB] = SFMMetrics(model,xNL);
outputs the TTS (in veh h) and the RQB (in veh).
The quadratic continuous knapsack problem often arises in a post-processing stage of a continous traffic signal control policy to allocate the green times among the stages. The command
>> x = knapsack(a,b,c,d);
where a,b, and d are column vectors and c is a scalar, outputs the solution. For more details see (Pedroso, Batista, Papageorgiou, and Kosmatopoulos, 2022). The algorithm that is implemented is poposed in (Helgason, Kennington, and Lall, 1980), it is detailled in the context of traffic signal control in (Diakaki, 1999).
Example: Quadratic continuous knapsack problem
>> a = [0;-1;0]; >> b = [4;2;1]; >> c = 5; >> d = [1;1;1]; >> x = knapsack(a,b,c,d) x = 2.5000 1.5000 1.0000
SAFFRON toolbox also provides simulation_template.m template file for the simulation of a traffic signal control policy in MATLAB making use of the nonlinear model with upstream gating that is proposed in (Aboudolas, Papageorgiou, and Kosmatopoulos, 2009). For more tecnhical details see (Pedroso, Batista, Papageorgiou Kosmatopoulos, 2022).
A control policy can be implemented seamlessly in this script by
- Setting the directory of the traffic network model
- Setting the initial occupancy and demand
- Synthesizing the novel control policy
- Implementing the novel control policy, i.e., compute the green-times of the stages as a function of the link occupancy
in the places indicated in the script. The template file simulation_template.m is well commented so that it is very easy to adapt the script.
The model of the urban traffic network of the city center of Chania, Greece is provided. This model has been extensively used by the DSSLab (Diakaki, 1999), (Aboudolas, Papageorgiou, Kosmatopoulos, 2009).
The Chania urban traffic network, consists of 16 signalized junctions and 60 links
The model data in enclosed in the folder ChaniaUrbanRoadModel includes
- model paramenters in a spreadsheet that follows the provided template and associated txt files
- model paramenters in the MAT-fite data.mat
- the image above of the topology of the network
To load the Chania urban road model one ca either syntheize the parameters from the spreadsheet running
>> chania = SFMSynthesis('ChaniaUrbanRoadModel');
or load the MAT-file running
>> chania = load('ChaniaUrbanRoadModel/data.mat');
Note that using load it is possible to select only a fraction of the struct fields, i.e.
>> chania = load('ChaniaUrbanRoadModel/data.mat','junctions','links');
Full source code of the application of SAFFRON to the implementation of
- the well-known TUC strategy (Diakaki, 1999)
- two recent decentralized signal control strategies proposed in (Pedroso and Batista, 2021)
is provided in the folder Examples/PedrosoBatista2021.
To run this example place the simulation script and auxiliary .m files in Examples/PedrosoBatista2021 in a directory with the SAFFRON source files. Alternatively, place the toolbox source files in a directory and add it to the MATLAB search path.
Example: Run simulation example of (Pedroso and Batista, 2021)
>> simulation
The simulation of the the D2TUC strategy with decentralized configuration
The community is encouraged to contribute with
- Suggestions
- Addition of tools
- Implementations of signal control strategies
To contribute to SAFFRON
- Open an issue (tutorial on how to create an issue)
- Make a pull request (tutorial on how to contribute to GitHub projects)
- Or, if you are not familiar with GitHub, contact the authors
Diakaki, C., 1999. Integrated control of traffic flow in corridor networks. Ph. D. Thesis.