andreavidali/deep-qlearning-agent-for-traffic-signal-control

How andreavidali/deep-qlearning-agent-for-traffic-signal-control works

TLCS trains and evaluates a DQN that controls a single SUMO intersection. The user starts a train or test run; validated settings configure the run, and each episode generates traffic routes, observes the simulation, chooses signal phases, and records rewards and queue statistics. Training turns episode history into replay samples and updates a neural network; testing loads a trained model. Runs save model/settings artifacts and plots. The graph follows documented capabilities and sampled call sites; SUMO is external, and unsampled internals are represented only where the README supports them.

Main entry points: main.py Run orchestration · agent.py Epsilon-greedy agent · env.py SUMO environment · model.py Q-network

Components 17

Run entry

Train/test CLI src/tlcs/cli.py
Settings validation src/tlcs/settings.py
Run orchestration src/tlcs/main.py

Simulation

Episode loop src/tlcs/episode.py
SUMO environment src/tlcs/env.py
Route generation src/tlcs/generator.py
Intersection scenario intersection/sumo_config.sumocfg

DQN learning

Epsilon-greedy agent src/tlcs/agent.py
Q-network src/tlcs/model.py
Replay buffer src/tlcs/memory.py

Run outputs

Run artifacts src/tlcs/main.py
Metrics plots src/tlcs/plots.py
Trained model src/tlcs/model.py

Other components

Operator
SUMO simulator
Training YAML settings/training_settings.yaml
Testing YAML settings/testing_settings.yaml

Connections 26

Operator → Train/test CLI: starts run
Train/test CLI → Run orchestration: dispatches
Train/test CLI → Settings validation: selects config
Run orchestration → Settings validation: loads settings
Training YAML → Settings validation: training values
Testing YAML → Settings validation: testing values
Run orchestration → Episode loop: runs episodes
Run orchestration → SUMO environment: configures
Run orchestration → Epsilon-greedy agent: creates or loads
Run orchestration → Replay buffer: creates buffer
Episode loop → SUMO environment: observes and acts
Episode loop → Epsilon-greedy agent: requests action
SUMO environment → Route generation: generates routes
Route generation → Intersection scenario: writes route file
SUMO environment → SUMO simulator: controls simulation
Intersection scenario → SUMO simulator: configures
Run orchestration → Replay buffer: adds transitions
Run orchestration → Epsilon-greedy agent: replays batches
Epsilon-greedy agent → Replay buffer: samples transitions
Epsilon-greedy agent → Q-network: predicts and trains
Run orchestration → Q-network: saves model
Q-network → Trained model: serializes weights
Run orchestration → Run artifacts: copies settings
Run orchestration → Metrics plots: saves metrics
Metrics plots → Run artifacts: writes plots and data
Trained model → Q-network: loads for testing

More Python diagrams: joriscos/librimix · perone/vectorvfs · phamquiluan/residualmaskingnetwork · ashuttl/linecast · canonical/maas

Drawn by GitDiagram on September 27, 2026 from the repository's file tree, README and source files. Read as Markdown ·