# eeeeeclectic/traffic_signal_control architecture

> Architecture diagram of the GitHub repository eeeeeclectic/traffic_signal_control, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eeeeeclectic/traffic_signal_control
- Repository: https://github.com/eeeeeclectic/traffic_signal_control

## Overview

##### Project Type and Purpose
- This is an open-source, Python-based framework and experiment suite for traffic signal control via multi-agent, graph-based reinforcement learning.
- It builds on SUMO (via TraCI) to simulate traffic, adds a modular “sumo_rl” library (environment, agents, graph-models), and provides “experiments/” scripts to drive training, evaluation, and plotting.

##### Main Architectural Components
A. External Simulation Service
- SUMO Simulator & TraCI API
B. Core Library (“sumo_rl/”)
1. environment/
– SumoEnvironment (Gymnasium/PettingZoo wrapper)
– TrafficSignal controller (phase, reward, observation)
– ObservationFunction abstractions
2. agents/
– QLearningAgent, PG_SingleAgent, PG_MultiAgent, DCRNN-enabled agents
3. models/
– base_model, dcrnn_cell, dcrnn_model, transformer_model
– util functions for graph construction, k-hop neighbors, temporal features
4. nets/
– Predefined network configs (.net.xml, .rou.xml, .sumocfg) for 1×1 up to real city grids
5. util/
– gen_route.py for generating SUMO route files
C. Experiment Orchestrator (“experiments/”)
– Python scripts (centralised_control.py, decentralised_control.py, DQN, PPO, Q-learning, SARSA variants)
– Each script instantiates SumoEnvironment + Agent + Model + logging
D. Persistence & Reporting
– models/ (.pth checkpoints)
– results/ (CSV training logs)
– outputs/ (PDF/PNG plots + plot.py)
E. Documentation & CI/CD
– docs/ (Sphinx sources, conf.py, examples, API md files)
– .github/workflows/ (build-publish, deploy-docs, tests, pre-commit)
– setup.py, pyproject.toml, requirements.txt

##### Relationships and Data Flow
1. experiments/*.py → import sumo_rl.environment & agents → instantiate SumoEnvironment
2. SumoEnvironment calls SUMO via TraCI:
env.reset()  → TraCI launches sim → returns initial observation
env.step(action) → TrafficSignal sets phase → TraCI advances sim → returns next obs & reward
3. Agent receives observation → Model (DCRNN/Transformer/Q-table) computes action → back to env.step()
4. After each episode or epoch:
– metrics logged to results/*.csv
– model weights saved to models/*.pth
– plots generated via outputs/plot.py → outputs/*.pdf
5. docs/ updated → CI builds and deploys Sphinx site → badge updates

##### Architectural Patterns & Design Principles
- Modular Plugin Architecture: easily swap ObservationFunction, RewardFunction, Agent, Model
- Separation of Concerns:
- Environment layer (sumo_rl/environment)
- Agent layer (sumo_rl/agents)
- Model layer (sumo_rl/models)
- Data definitions (sumo_rl/nets)
- Graph-based RL: explicit pre-processing in util, DCRNN & transformer graph encoders/decoders
- Experiment-Driven Development: scripts in experiments/ form the entry points
- CI/CD for Quality: automated tests, pre-commit hooks, docs deployment

##### Detail to Capture
- Class names (SumoEnvironment, TrafficSignal, base_model, dcrnn_cell, transformer_model)
- File-level patterns (nets/ configurations, experiment scripts)
- Data artifacts and formats (​.pth, .csv, .pdf)
- CI workflows (build, test, deploy-docs)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Simulation Service
    subgraph "External Simulation Service"
        direction TB
        SUMO["SUMO Simulator\nvia TraCI API"]:::external
    end

    %% Core Library
    subgraph "Core Library (sumo_rl/)" 
        direction TB
        subgraph "Environment Module" 
            direction TB
            Env["SumoEnvironment"]:::library
            TS["TrafficSignal\nController"]:::library
            Obs["ObservationFunction\nAbstractions"]:::library
        end
        subgraph "Agents Module"
            direction TB
            QL["QLearningAgent"]:::library
            PG1["PG_SingleAgent"]:::library
            PG2["PG_MultiAgent"]:::library
            DCRNN_A["PG_MultiAgent_DCRNN"]:::library
        end
        subgraph "Models Module"
            direction TB
            BM["base_model"]:::library
            DC["dcrnn_cell"]:::library
            DM["dcrnn_model"]:::library
            TM["transformer_model"]:::library
            UTIL["util.py\n(graph utils)"]:::library
        end
        subgraph "Network Configurations (nets/)"
            direction TB
            Nets[".net/.rou/.sumocfg files"]:::library
        end
        subgraph "Utility Scripts"
            direction TB
            Gen["gen_route.py"]:::library
        end
    end

    %% Experiment Orchestrator
    subgraph "Experiment Orchestrator (experiments/)" 
        direction TB
        CE["centralised_control.py"]:::exp
        DE["decentralised_control.py"]:::exp
        DD["decentralised_control_dcrnn.py"]:::exp
        D21["dqn_2way-single-intersection.py"]:::exp
        DBI["dqn_big-intersection.py"]:::exp
        P4["ppo_4x4grid.py"]:::exp
        Q21["ql_2way-single-intersection.py"]:::exp
        Q4["ql_4x4grid.py"]:::exp
        Q4P["ql_4x4grid_pz.py"]:::exp
        QS["ql_single-intersection.py"]:::exp
        S21["sarsa_2way-single-intersection.py"]:::exp
        SD["sarsa_double.py"]:::exp
        SR["sarsa_resco.py"]:::exp
        SB3["sb3_grid4x4.py"]:::exp
    end

    %% Persistence & Reporting
    subgraph "Persistence & Reporting"
        direction TB
        ModelsStore["models/ (.pth)"]:::datastore
        Results["results/ (.csv)"]:::datastore
        Outputs["outputs/ (.pdf)"]:::datastore
        Plot["plot.py"]:::library
    end

    %% Documentation & CI/CD
    subgraph "Docs & CI/CD"
        direction TB
        Docs["docs/ (Sphinx sources)"]:::ci
        CI1["build-publish.yml"]:::ci
        CI2["deploy-docs.yml"]:::ci
        CI3["linux-test.yml"]:::ci
        CI4["pre-commit.yml"]:::ci
        Config["setup.py,\npyproject.toml,\nrequirements.txt"]:::ci
    end

    %% Relationships & Data Flow
    CE -->|"imports"| Env
    DE -->|"imports"| Env
    DD -->|"imports"| Env
    D21 -->|"imports"| Env
    DBI -->|"imports"| Env
    P4 -->|"imports"| Env
    Q21 -->|"imports"| Env
    Q4 -->|"imports"| Env
    Q4P -->|"imports"| Env
    QS -->|"imports"| Env
    S21 -->|"imports"| Env
    SD -->|"imports"| Env
    SR -->|"imports"| Env
    SB3 -->|"imports"| Env

    Env -->|"calls reset()/step()"| SUMO
    SUMO -->|"returns obs/reward"| Env
    Env -->|"provides observation"| QL & PG1 & PG2 & DCRNN_A
    QL & PG1 & PG2 & DCRNN_A -->|"action"| Env

    QL & PG1 & PG2 & DCRNN_A -->|"uses"| BM & DC & DM & TM & UTIL
    Env -->|"uses"| TS & Obs

    %% After episode
    Env -->|"logs metrics"| Results
    QL & PG1 & PG2 & DCRNN_A -->|"saves weights"| ModelsStore
    Plot -->|"generates plots"| Outputs

    %% CI/CD and Docs
    Docs --> CI1 & CI2 & CI3 & CI4
    CI3 -->|"runs tests"| Env & QL & BM
    CI2 -->|"deploys docs"| Docs

    %% Click Events
    click SUMO "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/sumo_rl/environment/env.py"
    click Env "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/sumo_rl/environment/env.py"
    click TS "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/sumo_rl/environment/traffic_signal.py"
    click Obs "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/sumo_rl/environment/observations.py"
    click QL "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/sumo_rl/agents/ql_agent.py"
    click PG1 "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/sumo_rl/agents/pg_single_agent.py"
    click PG2 "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/sumo_rl/agents/pg_multi_agent.py"
    click DCRNN_A "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/sumo_rl/agents/pg_multi_agent_dcrnn.py"
    click BM "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/sumo_rl/models/base_model.py"
    click DC "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/sumo_rl/models/dcrnn_cell.py"
    click DM "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/sumo_rl/models/dcrnn_model.py"
    click TM "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/sumo_rl/models/transformer_model.py"
    click UTIL "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/sumo_rl/models/util.py"
    click Nets "https://github.com/eeeeeclectic/traffic_signal_control/tree/main/sumo_rl/nets/"
    click Gen "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/sumo_rl/util/gen_route.py"
    click CE "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/experiments/centralised_control.py"
    click DE "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/experiments/decentralised_control.py"
    click DD "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/experiments/decentralised_control_dcrnn.py"
    click D21 "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/experiments/dqn_2way-single-intersection.py"
    click DBI "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/experiments/dqn_big-intersection.py"
    click P4 "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/experiments/ppo_4x4grid.py"
    click Q21 "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/experiments/ql_2way-single-intersection.py"
    click Q4 "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/experiments/ql_4x4grid.py"
    click Q4P "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/experiments/ql_4x4grid_pz.py"
    click QS "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/experiments/ql_single-intersection.py"
    click S21 "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/experiments/sarsa_2way-single-intersection.py"
    click SD "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/experiments/sarsa_double.py"
    click SR "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/experiments/sarsa_resco.py"
    click SB3 "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/experiments/sb3_grid4x4.py"
    click ModelsStore "https://github.com/eeeeeclectic/traffic_signal_control/tree/main/models/"
    click Results "https://github.com/eeeeeclectic/traffic_signal_control/tree/main/results/"
    click Plot "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/outputs/plot.py"
    click Docs "https://github.com/eeeeeclectic/traffic_signal_control/tree/main/docs/"
    click CI1 "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/.github/workflows/build-publish.yml"
    click CI2 "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/.github/workflows/deploy-docs.yml"
    click CI3 "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/.github/workflows/linux-test.yml"
    click CI4 "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/.github/workflows/pre-commit.yml"
    click Config "https://github.com/eeeeeclectic/traffic_signal_control/blob/main/setup.py"

    %% Styles
    classDef library fill:#D6EAF8,stroke:#1B4F72,color:#154360
    classDef external fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef datastore fill:#FAD7A0,stroke:#B9770E,color:#784212
    classDef ci fill:#D5D8DC,stroke:#808B96,color:#566573
    classDef exp fill:#E8DAEF,stroke:#6C3483,color:#4A235A
```
