SAFFRON:
_{🚦Store-And-Forward model toolbox For urban ROad Network signal control in MATLAB}

🎯 Features

• 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

---

🚀 Index

• Description
• Authors
• Contact
• Documentation
• Contributing to SAFFRON
• Lincense
• References

---

💡 Description

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

Pedroso, L., Batista, P., Papageorgiou, M. and Kosmatopoulos, E., 2022. SAFFRON: Store-And-Forward model toolbox For urban ROad Network signal control in MATLAB. 2022 IEEE 25th International Conference on Intelligent Transportation Systems (ITSC), pp. 3698-3703. doi:10.1109/ITSC55140.2022.9922508.

[Accepted version]

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.

---

✍🏼 Authors

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

---

📞 Contact

SAFFRON toolbox is currently maintained by Leonardo Pedroso (leonardo.pedroso@tecnico.ulisboa.pt).

---

📖 Documentation

The documentation is divided into the following categories:

• Model synthesis
• Utilities
  • Network properties
  • Performance metrics
  • Quadratic continuous knapsack solver
• Simulation script
• Chania urban road network
• Example

Model synthesis

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	$J$
Z	Number of junctions	$L$
nStages	Number of stages	$L$
C	Control cycle (s)	$C$
c	Upstream gating parameter	$c_{ug}$
Tsim	Simulation cycle (s)	$T$
lostTime	Column vector of lost times (s) in each junction	$\mathrm{col}(L_1,\ldots,L_J)$
nStagesJunction	Column vector of number of stages of each junction	$\mathrm{col}(&#124\mathcal{F}_1&#124,\ldots,&#124\mathcal{F}_S&#124))$
capacity	Column vector of capacity of each link (veh)	$\mathrm{col}(x_{1,\text{max}},\ldots,x_{Z,\text{max}})$
saturation	Column vector of saturation flow of each link (veh/s)	$\mathrm{col}(S_1,\ldots,S_Z)$
lanes	Column vector of number of lanes in each link	-
x0	Initial number of vehicles of each link (veh)	$\mathbf{x}(0)$
d	Column vector of demand on each link (veh/s)	$\mathrm{col}(d_1,\ldots,d_Z)$
gmin	Column vector of minimum green time of each stage (s)	$\mathrm{col}(g_{1,min},\ldots,g_{S,min})$
gN	Column vector of historic green time of each stage (s)	$\mathbf{g_N}$
T	Turning rates matrix	$\mathbf{T}$
t0	Exit rates vector	$\mathbf{t_0}$
S	Stage matrix	$\mathbf{S}$
junctions	Cell array indexed by junction number that contains the number of the stages associated with that junction (see example below)	-
links	$Z\times 2$ matrix whose rows are indexed by link number and the corresponding columns are the origin and destination junctions respectively, i.e., it is the ordered list of edges of the network graph (see example below)	-
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 $\mathbf{A}$ of the store-and-forward model of the network	$\mathbf{A}$
Bu	State-space matrix $\mathbf{A}$ of the store-and-forward model in equation (4) of (Pedroso, Batista, Papageorgiou, and Kosmatopoulos, 2022)	$\mathbf{B_u}$
BG	State-space matrix $\mathbf{A}$ of the store-and-forward model in equation (7) of (Pedroso, Batista, Papageorgiou, and Kosmatopoulos, 2022)	$\mathbf{B_G}$
Bg	State-space matrix $\mathbf{A}$ of the store-and-forward model in equation (8) of (Pedroso, Batista, Papageorgiou, and Kosmatopoulos, 2022)	$\mathbf{B_g}$
Bu_sim	State-space matrix $\mathbf{A}$ of the store-and-forward model in equation (4) of (Pedroso, Batista, Papageorgiou, and Kosmatopoulos, 2022) discretized with simulation cycle $T$	-
BG_sim	State-space matrix $\mathbf{A}$ of the store-and-forward model in equation (7) of (Pedroso, Batista, Papageorgiou, and Kosmatopoulos, 2022) discretized with simulation cycle $T$	-
Bg_sim	State-space matrix $\mathbf{A}$ of the store-and-forward model in equation (8) of (Pedroso, Batista, Papageorgiou, and Kosmatopoulos, 2022) discretized with simulation cycle $T$	-
C_z	State-space matrix $\mathbf{C}$ of the store-and-forward model of the network	$\mathbf{C}$
E_DTUC_psi	Sparsity matrix of the controller gain for the decentralized control strategy DTUC with decentralized configuration $\mathbf{\Psi}$ proposed in (Pedroso and Batista, 2021)	$\mathbf{E_{\Psi}}$
E_DTUC_phi	Sparsity matrix of the controller gain for the decentralized control strategy DTUC with decentralized configuration $\mathbf{\Phi}$ proposed in (Pedroso and Batista, 2021)	$\mathbf{E_{\Phi}}$
E_D2TUC_psi	Sparsity matrix of the controller gain for the decentralized control strategy D2TUC with decentralized configuration $\mathbf{\Psi}$ proposed in (Pedroso and Batista, 2021)	$\mathbf{E_{\Psi}}$
E_D2TUC_phi	Sparsity matrix of the controller gain for the decentralized control strategy D2TUC with decentralized configuration $\mathbf{\Phi}$ proposed in (Pedroso and Batista, 2021)	$\mathbf{E_{\Phi}}$

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

Utilities

Network properties

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

Performance metrics

The performance metrics total time spent (TTS)

$\mathrm{TTS} = T \sum\limits_{k}^{} \sum\limits_{z=1}^Z x_z(k)$

and relative queue balance (RQB)

$\mathrm{RQB} = \sum\limits_{k}^{} \sum\limits_{z=1}^Z \frac{x_z^2(k)}{x_{z,max}}$

introcuced in (Aboudolas, Papageorgiou, and Kosmatopoulos, 2009) can be computed seamlessly with SAFFRON. Let xNL be a $Z\times N_{sim}$ array, where $N_{sim}$ is the number of cycles that were simulated of a model model with the nonlinear dynamiccs (See Simulation script for a template to simulate the nonlinear dynamics and Example for an example). The $k$-th row of xNL, i.e. xNL(:,k), is the column vector of the link occupancy at time $t = (k-1)T$. The command

>> [TTS,RQB] = SFMMetrics(model,xNL);

outputs the TTS (in veh h) and the RQB (in veh).

Quadratic continuous knapsack solver

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 

Simulation script

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.

Chania urban road network

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');

Example

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 $\mathbf{\Phi}$ using SAFFRON tools in the Chania urban road network that is provided has the following occupancy and green time evolution

---

✨ Contributing to SAFFRON

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

---

📄 License

MIT License

---

💥 References

Pedroso, L., Batista, P., Papageorgiou, M. and Kosmatopoulos, E., 2022. SAFFRON: Store-And-Forward model toolbox For urban ROad Network signal control in MATLAB. 2022 IEEE 25th International Conference on Intelligent Transportation Systems (ITSC), pp. 3698-3703. doi:10.1109/ITSC55140.2022.9922508.

Aboudolas, K., Papageorgiou, M. and Kosmatopoulos, E., 2009. Store-and-forward based methods for the signal control problem in large-scale congested urban road networks. Transportation Research Part C: Emerging Technologies, 17(2), pp.163-174. doi:10.1016/j.trc.2008.10.002.

Diakaki, C., 1999. Integrated control of traffic flow in corridor networks. Ph. D. Thesis.

Helgason, R., Kennington, J. and Lall, H., 1980. A polynomially bounded algorithm for a singly constrained quadratic program. Mathematical Programming, 18(1), pp.338-343. doi:10.1007/BF01588328.

Pedroso, L. and Batista, P., 2021. Decentralized store-and-forward based strategies for the signal control problem in large-scale congested urban road networks. Transportation Research Part C: Emerging Technologies, 132, p.103412. doi:10.1016/j.trc.2021.103412.