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.

The framework is organized around four modules — Network Environment, Initializer, Deployment, and RL Interaction — implemented as a single, Gym-compatible environment class (TrexEnv) whose incident behavior is switched on or off by one configuration parameter. This keeps the base (incident-free) and incident scenarios as two instances of the same environment rather than two separate code paths to maintain.

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.

In code, these map onto: TrexEnv (the Gym environment, network setup, and step loop) for the network environment; Initializer for incident sampling; Deployment for rerouting, speed adaptation, and lane-changing during the simulation; and the RL-agent implementations (IDQN, IPPO, MPLight, FMA2C, and rule-based baselines) plus the reward/state functions used to connect them to the environment.

# Base scenario -- incidents disabled, Initializer/Deployment never invoked
env = TrexEnv(..., incident_config=None)

# Incident scenario -- incidents enabled with the given parameters
env = TrexEnv(..., incident_config=IncidentConfig(level=2))

main.py selects between the two automatically from the --strategy flag (1 = base, 2 = incident), so switching a training run between conditions is a single command-line flag, not a different script.

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.

When incidents are randomly generated, the Initializer samples each parameter independently for every episode: the edge is drawn from a probability distribution weighted by historical traffic flow on real-world networks (uniformly at random on synthetic ones), the number of blocked lanes and their position along the edge are drawn uniformly, the start time is drawn uniformly within the episode window, and the duration is drawn from an exponential distribution — producing mostly short disruptions with an occasional long-tail incident, similar to real incident-clearance times. Alternatively, a scenario can pin every parameter to a fixed value for controlled, repeatable experiments (e.g. always blocking the same two lanes of the same edge for 5 minutes starting at minute 10).

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.

Awareness from the four sources is combined into a single probability per driver per step, and a driver who becomes aware evaluates rerouting through a binomial logit model of the expected gain from switching routes (Δp) and the loss avoided by not entering the affected arc (Δw):

P(reroute) = 1 / (1 + exp(-(β0 + β_gain·Δp − β_loss·Δw)))

The surface below plots exactly this function (β0 = −5, β_gain = β_loss = 2.5, as used in T-REX): rerouting probability stays low unless both the expected gain and the avoided loss are large enough to outweigh a driver's baseline reluctance to deviate from their planned route.

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.

T-REX computes each vehicle's stopping sight distance (SSD) from the AASHTO formula, combining a perception-reaction distance and a braking distance:

SSD = v · t_reaction + v² / (2 · a_decel)
      # t_reaction = 2.5 s, a_decel = 3.4 m/s² (AASHTO)

Once a vehicle is within its own SSD of the incident, its target speed and lane-change behavior are adjusted for the remainder of the approach; vehicles that have already passed the incident are returned to normal driving parameters.

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.

Concretely, vehicles inside the incident's influence zone get adjusted SUMO LC2013 lane-change parameters — increased strategic and cooperative lane-changing, reduced speed-gain-driven changes, and keep-right behavior disabled — so that merging around a blockage happens earlier and more cooperatively than default SUMO lane-changing would produce.

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. Rule-based baselines — Fixed-time, Random, Max-pressure, and a Greedy (max-wave) controller — are included as reference points for comparison against the learning-based methods.

Benchmark networks

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

Grid4x4 is a synthetic network used for controlled, easily-reproduced experiments; the Cologne and Ingolstadt networks are real-world networks built from the TAPAS Cologne and InTAS traffic datasets respectively, giving results on both idealized and realistic road geometries and demand patterns.

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.

Each simulated episode writes raw per-step traffic indicators (reward, queue length, waiting time per signal) and SUMO's own per-vehicle trip records; the robustness metrics below are computed from these logs across an entire training or evaluation run.

Installation

Clone the repository, install SUMO (set the SUMO_HOME environment variable to its install directory), and install the pinned Python dependencies:

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

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

T-REX requires SUMO, TraCI, Python 3.10+, Gym-compatible RL components, and the learning libraries used by the supported algorithms (PyTorch, TensorFlow, PFRL) — all pinned in requirements.txt. You can verify the install with a one-episode smoke test before running a full experiment:

export LIBSUMO_AS_TRACI=1
python main.py --agent MAXPRESSURE --map grid4x4 --eps 1 --strategy 1 --libsumo True

Run experiments

To run a base scenario without incidents:

export LIBSUMO_AS_TRACI=1
python main.py --agent IDQN --map grid4x4 --eps 100 --tr 0 --strategy 1 --libsumo True --seed 0

To run the same setup with incidents enabled, the only thing that changes is --strategy:

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

--seed seeds Python, NumPy, PyTorch, and SUMO itself for a reproducible run; the paper's reported results are averaged over 5 seeds, so a full reproduction runs each configuration with --seed 0 through --seed 4 and averages externally. Results — per-episode metrics and SUMO's own per-vehicle trip records — are saved under results/<run-name>/ 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}
}

The paper has been submitted to European Transport Research Review; the arXiv preprint above is the citable version until a journal volume/pages/DOI are assigned.