FlowLight: Intrinsically Safe Adaptive Traffic Signal Control for Mixed-Autonomy Intersections

This repository contains the full implementation of FlowLight, a PPO-based adaptive traffic signal controller that demonstrates intrinsic safety through mobility optimization in mixed-autonomy environments.

---

Table of Contents

• Overview
• Repository Structure
• Requirements
• Installation
• Dataset
• Execution Steps
  • Train PPO Agents
  • Train DDQN Baseline
  • Run Classical Baselines
  • Evaluate All Agents
  • Generate Plots
  • Statistical Tests
• Reproducing Paper Figures

---

Overview

FlowLight investigates whether an optimally scaled mobility reward can intrinsically maximize surrogate safety in mixed-autonomy traffic signal control, rendering explicit Time-to-Collision (TTC) constraints redundant. The framework:

• Trains a PPO agent with a 33-dimensional mixed-autonomy state (HDV queues, CAV queues, current phase)
• Compares a mobility-only reward (QWT) against a safety-augmented reward (QWT+TTC)
• Evaluates generalization on real-world CN+ Bremen demand data
• Compares PPO against DDQN to explore value-based method vulnerabilities

---

Repository Structure

FlowLight/
│
├── src/
│   ├── run_baselines.py
│   ├── generate_custom_road.py
│   ├── travel_metrics.py
│   ├── ttc_utils.py
│   ├── lane_reader.py
│   ├── metrics.py
│   ├── plot_RLVsBasline.py
│   ├── plot_training_logs.py
│   └── plot_ppoVsddqn.py
├── src/rl_agent/
│   ├── sumo_rl_env.py 
│   ├── train_agent.py
│   ├── evaluate_agent.py
│   
├── sumo_env/   # SUMO network and config files
│   ├── flowlight.net.xml
│   ├── flowlight.sumocfg
│   └── flowlight.rou.xml
│
├── models/
├── logs/
├── figures/
├── requirements.txt
└── README.md

---

Requirements

• Python 3.10 or 3.12 (Python 3.14 is not supported due to scipy incompatibility)
• SUMO 1.19.0 or later - Download SUMO Verify SUMO is installed and on your PATH:

sumo --version

---

Installation

1. Clone the repository:

git clone https://github.com/AARC-lab/Flowlight.git
cd Flowlight

2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate        # Linux / macOS
# trsaenv\Scripts\activate         # Windows

3. Install all dependencies:

pip install -r requirements.txt

4. Set SUMO_HOME environment variable:

export SUMO_HOME=/path/to/sumo

Add this line to your ~/.bashrc or ~/.zshrc to make it permanent.

---

Dataset

To evaluate our model performance we use real-world demand scenarios CN+ Bremen dataset:

Karunathilake, Thenuka, Meyo Zongo, Dinithi Amarawardana, and Anna Förster. "Cn+: vehicular dataset at traffic light regulated intersection in bremen, germany." Scientific data 11, no. 1 (2024): 665.

Download the preprocessed dataset:

Google Drive Link

After downloading, place the files in:

Flowlight/datasets/

Synthetic demand (peak 4000 veh/hr, flat 1500 veh/hr) is generated automatically by generate_custom_road.py and does not require any download.

---

Execution Steps

All commands are run from FlowLight/.

---

Train PPO Agents

PPO with QWT reward:

python src/train_agent.py \
    --algo ppo \
    --reward_name qwt \
    --mpr 0.5 \
    --timesteps 200000 \
    --seed 42 \
    --logdir logs/evaluation \
    --model-out models/ppo_qwt

PPO with QWT+TTC reward:

python src/train_agent.py \
    --algo ppo \
    --reward_name qwt_ttc \
    --mpr 0.5 \
    --timesteps 200000 \
    --seed 42 \
    --logdir logs/evaluation \
    --model-out models/ppo_qwt_ttc

Train DDQN

DDQN with QWT reward:

python train_agent.py \
    --algo ddqn \
    --reward_name qwt \
    --mpr 0.5 \
    --timesteps 200000 \
    --seed 42 \
    --logdir logs/evaluation \
    --model-out models/ddqn_qwt

DDQN with QWT+TTC reward:

python train_agent.py \
    --algo ddqn \
    --reward_name qwt_ttc \
    --mpr 0.5 \
    --timesteps 200000 \
    --seed 42 \
    --logdir logs/evaluation \
    --model-out models/ddqn_qwt_ttc

Run Classical Baseline Controllers

# Synthetic demand
python run_baselines.py --demand peak --mpr 0.5 --episodes 30 --logdir logs/evaluation
python run_baselines.py --demand flat --mpr 0.5 --episodes 30 --logdir logs/evaluation
 
# Real-world CN+ demand
python run_baselines.py --demand cn_plus_peak --mpr 0.5 --episodes 30 --logdir logs/evaluation
python run_baselines.py --demand cn_plus_flat --mpr 0.5 --episodes 30 --logdir logs/evaluation

---

Evaluate All Agents

Run evaluation for every combination of model, demand, and algorithm:

chmod +x evaluate_RL_agents.sh
./evaluate_RL_agents.sh

Generate Plots

Training convergence and MPR sensitivity:

python plot_training_logs.py \
    --logdir logs/training_metrics \
    --outdir figuers/training \
    --no-raw

RL vs baseline comparison:

python plot_RLVsBaseline.py \
    --logdir logs/rl_vs_baseline \
    --outdir figuers \

PPO vs DDQN algorithm comparison:

python plot_algo_comparison.py \
    --outdir figuers/algo_comparison \
    --no-raw

---