Getting Started with T-REX

Overview

T-REX is an open-source, SUMO-based simulation framework for training and evaluating traffic signal control methods under disruptive traffic incidents. It is designed to move beyond standard recurrent congestion benchmarks by introducing incident-driven distribution shifts such as lane blockages, rerouting, speed adaptation, and congestion propagation.

Why T-REX?

Many reinforcement learning-based traffic signal control studies evaluate algorithms under stable simulation conditions. However, real urban networks are affected by incidents, blocked lanes, uncertain driver responses, and non-recurrent congestion. T-REX addresses this gap by providing a reproducible environment for testing whether control policies remain stable and efficient when the traffic network is disrupted.

The main idea is simple: instead of only asking whether an algorithm performs well in normal traffic, T-REX asks whether it remains reliable when the network changes unexpectedly.

Framework architecture

T-REX is organized around four main modules: the network environment, initializer, deployment module, and reinforcement learning interaction module. The network environment loads the SUMO scenario, including the road network, routes, traffic signals, and vehicle attributes. The initializer defines incident parameters such as location, duration, blocked lanes, and start time. The deployment module injects incidents and modifies vehicle behavior. The RL interaction module connects the simulation with traffic signal control agents.

Incident modeling

T-REX models incidents as lane-blocking events that can occur at selected edges, positions, times, and durations. Incidents can be generated randomly or specified by the user. The framework supports partial or full lane blockages, multiple simultaneous incidents, and reproducible scenario generation.

In the recommended virtual blockage approach, dummy incident vehicles are inserted into the simulation to block selected lanes. This gives precise control over the incident location and timing while avoiding some of the limitations of simply reducing speed limits or manually editing network capacity.

Figure 2. Vehicle speed adaptation behavior around a lane-blocking incident.

Driver behavior under incidents

A key feature of T-REX is that incidents do not only block lanes. They also change driver behavior. The framework models three important behavioral responses: rerouting, speed adaptation, and contextual lane changing.

Rerouting

T-REX implements rerouting behavior using the Information Comply Model. Drivers may become aware of an incident through direct observation, fixed-time information, fixed-place information, or online information sources. Once aware, they may choose an alternative route depending on the expected benefit of rerouting.

Speed adaptation

Vehicles approaching an incident reduce speed based on a stopping-sight-distance mechanism. This represents cautious driving behavior near blocked lanes or disabled vehicles.

Contextual lane changing

T-REX modifies lane-changing behavior so that vehicles can make earlier and more strategic lane changes when approaching an obstruction. This helps simulate more realistic congestion propagation around incidents.

RL interaction

T-REX uses the RESCO interface to connect SUMO with reinforcement learning agents. At each decision interval, agents observe local traffic states, select signal phases, apply actions through TraCI, and receive rewards based on traffic performance.

Observation → queue length, pressure, incoming flow
Action      → discrete traffic signal phase
Reward      → delay, queue, throughput, pressure, or custom objective

T-REX can be used with existing RL-TSC algorithms such as IDQN, IPPO, MPLight, and FMA2C, as well as custom control methods implemented through the Gym-compatible interface.

Benchmark networks

T-REX supports multiple synthetic and real-world benchmark networks, ranging from small corridors to larger urban regions.

Robustness metrics

T-REX evaluates traffic control methods using both standard traffic efficiency indicators and robustness-aware learning metrics. This is important because good final performance alone does not necessarily imply safe or stable behavior during training, transfer, or incident-driven distribution shifts.

Installation

Clone the repository and create the environment.

git clone https://github.com/andngdtudk/T-REX.git
cd T-REX

conda env create -f environment.yml
conda activate trex

T-REX requires SUMO, TraCI, Python, Gym-compatible RL components, and the learning libraries used by the supported algorithms.

Run experiments

To run a base scenario without incidents:

python main.py --agent IDQN --map grid4x4 --eps 100 --tr 0 --strategy 1

To run an incident scenario:

python main.py --agent IDQN --map grid4x4 --eps 100 --tr 0 --strategy 2

Results are saved under the corresponding results folder and can be used to compare algorithms across normal and incident conditions.

Citation

If you use T-REX in your research, please cite the corresponding paper.

@misc{nguyen2025robustnessreinforcementlearningbasedtraffic,
  title={Robustness of Reinforcement Learning-Based Traffic Signal Control under Incidents: A Comparative Study},
  author={Dang Viet Anh Nguyen and Carlos Lima Azevedo and Tomer Toledo and Filipe Rodrigues},
  year={2025},
  eprint={2506.13836},
  archivePrefix={arXiv},
  primaryClass={cs.LG},
  url={https://arxiv.org/abs/2506.13836}
}