sumoITScontrol is an open-source Python framework that provides a standardized collection of established traffic controllers for the SUMO simulator for signal control and freeway ramp metering algorithms. It enables reproducible, variance-aware benchmarking of intelligent traffic control methods through consistent implementations and rigorous evaluation practices.
Table of Contents
| Covered Controllers | ||
| Intersection Management | Ramp Metering | |
|
|
|
 |
 |
 |
 |
==> Link to Documentation Page <==
The python package sumoITScontrol can be installed using pip:
pip install sumoITScontrolYou can use sumoITScontrol as a Python library to easily integrate ITS controllers into your SUMO simulations. For this, you need to include only one line of code into your main loop when using SUMO with TraCI. Certain preparation, such as defining sensors and traffic lights, or control parameters, is necessary additionally. The usage is exemplified at the example of ALINEA controler and ramp metering. For further details, please see the section on Case Study Demonstrations.
Step 1: Define Sensors and Traffic Lights
You need to provide a control context such as a RampMeter or RampMeterCoordinationGroup in the context of ramp metering, and Intersection or IntersectionGroup in the context of signalised intersection management.
The context informs sumoITScontrol about relevant sensors (e2_5, e2_4, e2_0) and traffic lights (J0).
ramp_meter = RampMeter(
tl_id="J0",
mainline_sensors=["e2_5", "e2_4"],
queue_sensors=["e2_0"],
)Step 2: Define Control Parameters
You need to provide a controller and relevant parameters to connect the controller to the control context such as ALINEA, HERO, or METALINE in the context of ramp metering, and MaxPressure_Fix, MaxPressure_Flex or ScootScats in the context of singalised intersection management.
controller = ALINEA(
params={
"target_occupancy": 10,
"K_P": 30,
"K_I": 0,
"cycle_duration": 60,
"measurement_period": int(
60 / 0.5
), # int(cycle_duration / simulation.time_step)
"min_rate": 5,
"max_rate": 100,
},
ramp_meter=ramp_meter,
)Step 3: Add One Line to Main Loop
Any SUMO simulation that is executed with TraCI somehow has the structure of starting traci, inside a loop calling traci.simulationStep() for the duration of the simulation, and then closing traci.
Anything you have to do (for most controllers) is to simply add one line of code inside your loop, as outlined below.
Please Note: For the controller ScootScats, you might need to add one line to the initialization (after traci.start() but before traci.simulationStep()). For further details, please see the section on Case Study Demonstrations.
# Start Sumo
traci.start(SUMO_CMD)
# Initialize
# Execute Simulation
for simulation_timestep in range(0, SIMULATION_DURATION):
# run one step
traci.simulationStep()
# retrieve time
current_time = traci.simulation.getCurrentTime()
# execute control
controller.execute_control(current_time) # <-- !!! ADD THIS LINE !!!
# Stop Sumo
traci.close()Demo Python scripts and SUMO simulations for each implemented controller can be found in the folder .\sumoITScontrol\demos\*.py and .\sumoITScontrol\demos\demo_simulation_models\.
The Python scripts open sumo-gui for the simulation, and afterwards render figures with control-relevant statistics as reported in the paper.
There are three case studies:
- Control in the context of ramp metering
- Control in the context of signalised intersection management
- Calibration / Fine-tuning of control parameters
Details
The ramp metering case study consists of a network with three different ramp designs. There are multiple different demand scenarios, to showcase the performance of local controllers (e.g. ALINEA), and coordinated controllers (e.g. HERO, METALINE).Relevant demos include:
python demo_ALINEA.py
python demo_HERO.py
python demo_METALINE.py
Details
The signalised intersection management case study consists of an arterial network (Schorndorfer Strasse, Esslingen am Neckar) with seven intersections, where five are signalised (controlled). The case study serves to demonstrate the performance of local controllers (e.g. Max-Pressure), and coordinated controllers (e.g. SCOOT/SCATS).Relevant demos include:
python demo_MAX_FIX.py
python demo_MAX_FLEX.py
python demo_SCOSCA.pyDetails
At the example of the ramp metering study and the ALINEA controller, this script explores different parameters for ALINEA, by running SUMO simulations with different random seeds (20), and then reporting mean and standard deviation for different controller configurations (parameters).Relevant demos include:
python demo_optimisation.pywhich calls the python script demo_optimisation_execute_script.py.
This documentation lists specific details to control context objects and traffic control algorithms for ramp metering and signalised intersection management.
Details
This is the example of RampMetering object specification. The sensors can be E2 sensors or E1 sensors.
ramp_meter = RampMeter(
tl_id="J0",
mainline_sensors=["e2_5", "e2_4"],
queue_sensors=["e2_0"],
)This is the example of RampMeterCoordinationGroup object specification. The sensors can be E2 sensors or E1 sensors.
ramp_meter_group = RampMeterCoordinationGroup(
ramp_meters_ordered=[
RampMeter(
tl_id="J12",
mainline_sensors=["e1_13", "e1_14"],
queue_sensors=["e2_1", "e2_2"],
smoothening_factor=0.1,
saturation_flow_veh_per_sec=0.5,
),
RampMeter(
tl_id="J11",
mainline_sensors=["e1_2", "e1_3"],
queue_sensors=["e2_3"],
smoothening_factor=0.1,
saturation_flow_veh_per_sec=0.5,
),
RampMeter(
tl_id="J0",
mainline_sensors=["e2_5", "e2_4"],
queue_sensors=["e2_0"],
smoothening_factor=0.1,
saturation_flow_veh_per_sec=0.5,
),
],
ramp_meter_ids=["J12", "J11", "J0"],
)This is the example of Intersection object specification.
You can either provide a list of sensors (E2 sensors) or a list of lanes (links) to measure traffic states (queue lengths, degree of saturation).
If both are provided, sensors are taken first.
Provision of green_states and yellow_states is only necessary for SCOOT/SCATS.
intersection2 = Intersection(
tl_id="intersection2",
phases=[0, 2, 4],
# links = {0:["183049933#0_1", "-38361908#1_1"],
# 2:["-38361908#1_1", "-38361908#1_2"],
# 4:["-25973410#1_1", "758088375#0_1", "758088375#0_2"]},
sensors={
0: ["e2_183049933#0_1", "e2_-38361908#1_1"],
2: ["e2_-38361908#1_1", "e2_-38361908#1_2"],
4: ["e2_-25973410#1", "e2_758088375#0_1", "e2_758088375#0_2"],
},
green_states=["GGrrrGrr", "GGGrrrrr", "rrrGGrGG"],
yellow_states=["yyrrryrr", "yyyrrrrr", "rrryyryy"],
)This is the example of IntersectionGroup object specification. You can either provide a list of sensors (E2 sensors) or a list of lanes (links) to measure traffic states (queue lengths, degree of saturation). If both are provided, sensors are taken first.
intersection1 = Intersection(
tl_id="intersection1",
...
)
intersection2 = Intersection(
tl_id="intersection2",
...
)
intersection3 = Intersection(
tl_id="intersection3",
...
)
intersection4 = Intersection(
tl_id="intersection4",
...
)
intersection5 = Intersection(
tl_id="intersection5",
...
)
districts = {
"front": ["intersection1", "intersection2"],
"middle": ["intersection3", "intersection4"],
"back": ["intersection5"],
}
critical_district_order = {
"front": [
"intersection1",
"intersection2",
"intersection3",
"intersection4",
"intersection5",
],
"middle": [
"intersection3",
"intersection2",
"intersection4",
"intersection1",
"intersection5",
],
"back": [
"intersection5",
"intersection4",
"intersection3",
"intersection2",
"intersection1",
],
}
connection_between_intersections = {
"intersection1": ["183049934_1", "183049933#0_1", "1164287131#0_1"], # To Int 2
"intersection2": ["38361908#1_1", "E3_1"], # To Int 3
"intersection3": [
"E1_1",
"758088377#1_1",
"758088377#2_1",
"22889927#0_1",
], # To Int 4
"intersection4": [
"22889927#2_1",
"22889927#3_1",
"22889927#4_1",
"387296014#0_1",
"387296014#1_1",
"696225646#1_1",
"696225646#2_1",
"696225646#3_1",
"130569446_1",
"E5_1",
"E6_1",
], # To Int 5
}
intersection_group = IntersectionGroup(
intersections=[
intersection1,
intersection2,
intersection3,
intersection4,
intersection5,
],
districts=districts,
critical_district_order=critical_district_order,
connection_between_intersections=connection_between_intersections,
)This is the example of ALINEA object specification.
controller = ALINEA(
params={
"target_occupancy": 10,
"K_P": 30,
"K_I": 0,
"cycle_duration": 60,
"measurement_period": int(
60 / 0.5
), # int(cycle_duration / simulation.time_step)
"min_rate": 5,
"max_rate": 100,
},
ramp_meter=ramp_meter,
)This is the example of HERO object specification.
controller = HERO(
params={
"hero_cycle_duration": 60, # similar to ALINEA cycle duration
"queue_activation_threshold_m": 15.0, # master queue trigger
"queue_release_threshold_m": 2.5, # dissolve cluster
"min_queue_setpoint_m": 5.0, # for slaves
"anticipation_factor": 1.0, # factor to obtain nonconservative prediction of demand to come in next control period
"avg_vehicle_spacing": 7.5, # average vehicle spacing to convert meters to vehicles and vice versa, from queue length measurements
},
coordination_group=ramp_meter_group,
alinea_controllers={
"J12": alinea_controller1,
"J11": alinea_controller2,
"J0": alinea_controller3,
},
)This is the example of METALINE object specification.
controller = METALINE(
params={
"cycle_duration": 60, # control cycle
"measurement_period": int(
60 / 0.5
), # int(cycle_duration / simulation.time_step)
"min_rate": 5,
"max_rate": 100,
},
coordination_group=ramp_meter_group,
target_occupancies=[10, 10, 10],
# Interaction gain matrix (3x3)
K_P=np.array(
[
[30, -5, 0], # ramp 1 influenced negatively by ramp 2
[-3, 25, -2], # ramp 2 influenced by neighbors
[0, -4, 20],
]
),
# Optional integral gain matrix
K_I=np.zeros(shape=(3, 3)),
)This is the example of MaxPressure_Fix object specification.
controller = MaxPressure_Fix(
params={
"T_L": 3, # Yellow Time
"G_T_MIN": 5, # Min Greentime (used for Max. Pressure)
"G_T_MAX": 50, # Max Greentime (used for Max. Pressure)
"measurement_period": int(1 / 0.25), # int(1 / simulation.time_step)
"cycle_duration": 120,
},
intersection=intersection1
)This is the example of MaxPressure_Flex object specification.
controller = MaxPressure_Flex(
params={
"T_A": 5, # Recheck-Pressure Time (used for Max.Pressure)
"T_L": 3, # Yellow Time
"G_T_MIN": 5, # Min Greentime (used for Max. Pressure)
"G_T_MAX": 50, # Max Greentime (used for Max. Pressure)
"measurement_period": int(1 / 0.25), # int(1 / simulation.time_step)
"cycle_duration": 120,
},
intersection=intersection1
)This is the example of ScootScats object specification.
controller = ScootScats(
scosca_params = {
"adaptation_cycle": 30,
"adaptation_green": 10,
"green_thresh": 2,
"adaptation_offset": 1,
"offset_thresh": 0.5,
"min_cycle_length": 50,
"max_cycle_length": 180,
"ds_upper_val": 0.925,
"ds_lower_val": 0.875,
"measurement_period": int(1 / 0.25), # 1 / simulation_step_size
"travel_time_adjustments": {
"intersection1": ["183049934_1", 2],
"intersection3": ["E1_1", 3],
"intersection4": ["22889927#3_1", 9],
},
"intersection_offset_rules": {
"intersection2": {
"base_offset_from": None,
"travel_time_from": "intersection2",
},
"intersection4": {
"base_offset_from": None,
"travel_time_from": "intersection3",
},
"intersection1": {
"base_offset_from": "intersection2",
"travel_time_from": "intersection1",
},
"intersection3": {
"base_offset_from": "intersection4",
"travel_time_from": "intersection4",
},
"default": {
"base_offset_from": "intersection4",
"travel_time_from": "intersection4",
},
},
},
intersection_group=intersection_group1,
initial_greentimes={
"intersection1": [30, 30, 21],
"intersection2": [30, 30, 21],
"intersection3": [30, 30, 21],
"intersection4": [40, 30],
"intersection5": [30, 30, 21],
},
initial_cycle_length=120,
)Please cite our paper if you find sumoITScontrol useful:
@inproceedings{riehl2026sumoITScontrol,
title={sumoITScontrol: Traffic Controller Collection for SUMO Traffic Simulations},
author={Riehl, Kevin and Kouvelas, Anastasios and Makridis, Michail A.},
booktitle={SUMO Conference Proceedings},
year={2026}
}