# suarna/gatraffic architecture

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

- Interactive diagram: https://gitdiagram.com/suarna/gatraffic
- Repository: https://github.com/suarna/gatraffic

## Overview

##### Project Type and Purpose
- Project Type: It is a simulation & optimization application that uses genetic algorithms (GA) to manage traffic flows and timing at intersections.
- Purpose: To experiment with decentralized traffic management using a GA to control simulation parameters in the SUMO traffic simulator. The program uses various configuration files, parameter settings, and simulation networks to test traffic control strategies.

##### File Structure
- Key directories/files:
- Parameter Files: “@param.txt” and “@param_test.txt” that control execution settings.
- Core Python Modules:
- gatraffic.py (entry point for GA simulation)
- gatraffictoolbox.py (helper functions)
- parameters.py & paramstorage.py (handle simulation parameters)
- sumoconnector.py (interface with the external SUMO simulator)
- trafficinteract.py and tlenvironment.py (manage simulation interactions and environment setup).
- Network/Simulation Files: Under the “Nets/SimpleNet” directory, there are XML and SUMO configuration files (e.g., sumocfg, net.net.xml, demand and detector files) which define the traffic network that SUMO will simulate.
- Data Handling: The “data” folder holds simulation results, and plots are stored under “Nets/SimpleNet/plots”.
- Others: Files like LICENSE.txt, README.md, and scripts (speed_up.sh) give additional context while Docker and dependency configuration (requirements.txt) provide deployment instructions.

a. Main Components:
- Parameter/Configuration Manager: Represents all parameter files (e.g., @param.txt, @param_test.txt, parameters.py, paramstorage.py) which are used to define simulation conditions and GA settings.
- Genetic Algorithm Engine: Centered around gatraffic.py and test-gatraffic.py, this module applies GA (with specified population size, mutation, crossover, selection strategies, etc.) to optimize traffic management.
- SUMO Connector Module: sumoconnector.py functions as the interface between the GA engine and the SUMO simulator. It reads the SUMO configuration files from the “Nets/SimpleNet” directory and drives the simulation.
- Traffic Interaction and Environment Modules: trafficinteract.py and tlenvironment.py manage real-time simulation interaction, communications with the SUMO environment, and potentially adjust simulation flow dynamically.
- Data Storage/Result Logger: The “data” folder for logs/results and “Nets/SimpleNet/plots” for output plots that record simulation metrics.
- Docker/Deployment Environment: Docker images and scripts (like speed_up.sh) define the deployment container and environment setup.

b. Relationships and Data Flow:
- The flow begins with configuration: parameters are loaded from the parameter files.
- The Genetic Algorithm engine uses these parameters to generate candidate signal timings or traffic management strategies.
- Each candidate’s performance is evaluated via the SUMO simulator, invoked through the SUMO Connector.
- The simulation network is configured using XML and SUMO configuration files from Nets/SimpleNet.
- Feedback from the simulation (e.g., traffic performance statistics) flows back to the GA engine which iterates over generations.
- Final outputs (results and performance plots) are then stored in the relevant “data” and “plots” directories.
- Optionally, different execution environments (direct Python run or Docker container) are supported.

c. Architectural Patterns and Principles:
- Modular Separation: Clear separation between configuration, genetic algorithm logic, simulation interaction, and data handling.
- Decoupling of Simulation and Optimization: The GA engine is isolated from the SUMO simulator via a dedicated connector, facilitating easier testing and potential component reuse.
- Configurability: Extensive use of external parameter and configuration files means that the system supports plug-and-play simulation settings.

d. Relevant Technologies and Frameworks:
- Python (core language and modules)
- SUMO (Simulation of Urban MObility) for traffic simulation
- Docker (for containerized deployment)
- Possible use of libraries such as NumPy (hinted by parameter expressions) and any GA-specific libraries, though the custom implementation integrates many of these aspects.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Parameter Management Layer
    subgraph "Configuration & Parameter Management"
        CP1["@param.txt"]:::config
        CP2["@param_test.txt"]:::config
        CP3["parameters.py"]:::config
        CP4["paramstorage.py"]:::config
    end

    %% Genetic Algorithm Engine Layer
    subgraph "Genetic Algorithm Engine"
        GA1["gatraffic.py"]:::ga
        GA2["test-gatraffic.py"]:::ga
        GA3["gatraffictoolbox.py"]:::ga
    end

    %% SUMO Simulation Environment Layer
    subgraph "SUMO Simulation Environment"
        SC1["sumoconnector.py"]:::simo
        SC2["Nets/SimpleNet (Network Configs)"]:::simoNet
    end

    %% Traffic Interaction & Environment Layer
    subgraph "Traffic Interaction & Environment"
        TI1["trafficinteract.py"]:::traffic
        TI2["tlenvironment.py"]:::traffic
    end

    %% Data Storage/Result Logger Layer
    subgraph "Data Storage / Result Logger"
        DS1["data (Results)"]:::data
        DS2["Nets/SimpleNet/plots (Output Plots)"]:::data
    end

    %% Deployment & Containerization Layer
    subgraph "Deployment & Containerization"
        DE1["speed_up.sh"]:::deploy
        DE2["Docker & requirements.txt"]:::deploy
    end

    %% Connections between layers
    %% Configuration feeds into GA Engine
    CP3 -->|"loads"| GA1
    CP1 -->|"loads"| GA1
    CP2 -->|"loads"| GA1
    CP4 -->|"loads"| GA1

    %% GA Engine initiates simulation via SUMO Connector
    GA1 -->|"executes"| SC1

    %% SUMO Connector reads network configurations
    SC1 -->|"reads"| SC2

    %% SUMO Connector triggers Traffic Interaction
    SC1 -->|"initiates"| TI1

    %% Traffic Interaction returns simulation feedback to GA Engine
    TI1 -->|"feedback"| GA1
    TI2 -->|"supports"| TI1

    %% GA Engine stores simulation results
    GA1 -->|"logs"| DS1
    GA1 -->|"generates"| DS2

    %% Deployment options
    GA1 -->|"run_direct"| DE2
    GA1 -->|"containerized"| DE1

    %% Styles
    classDef config fill:#ffefdb,stroke:#e89b53,stroke-width:2px;
    classDef ga fill:#e0f7fa,stroke:#00acc1,stroke-width:2px;
    classDef simo fill:#e8f5e9,stroke:#43a047,stroke-width:2px;
    classDef simoNet fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,stroke-dasharray: 5 5;
    classDef traffic fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px;
    classDef data fill:#fff3e0,stroke:#fb8c00,stroke-width:2px;
    classDef deploy fill:#eceff1,stroke:#607d8b,stroke-width:2px;

    %% Click Events for Configuration & Parameter Management
    click CP1 "https://github.com/suarna/gatraffic/blob/master/@param.txt"
    click CP2 "https://github.com/suarna/gatraffic/blob/master/@param_test.txt"
    click CP3 "https://github.com/suarna/gatraffic/blob/master/parameters.py"
    click CP4 "https://github.com/suarna/gatraffic/blob/master/paramstorage.py"

    %% Click Events for Genetic Algorithm Engine
    click GA1 "https://github.com/suarna/gatraffic/blob/master/gatraffic.py"
    click GA2 "https://github.com/suarna/gatraffic/blob/master/test-gatraffic.py"
    click GA3 "https://github.com/suarna/gatraffic/blob/master/gatraffictoolbox.py"

    %% Click Events for SUMO Connector Module
    click SC1 "https://github.com/suarna/gatraffic/blob/master/sumoconnector.py"
    click SC2 "https://github.com/suarna/gatraffic/tree/master/Nets/SimpleNet"

    %% Click Events for Traffic Interaction & Environment Modules
    click TI1 "https://github.com/suarna/gatraffic/blob/master/trafficinteract.py"
    click TI2 "https://github.com/suarna/gatraffic/blob/master/tlenvironment.py"

    %% Click Events for Data Storage/Result Logger
    click DS1 "https://github.com/suarna/gatraffic/tree/master/data"
    click DS2 "https://github.com/suarna/gatraffic/tree/master/Nets/SimpleNet/plots"

    %% Click Events for Deployment & Containerization
    click DE1 "https://github.com/suarna/gatraffic/blob/master/speed_up.sh"
    click DE2 "https://github.com/suarna/gatraffic/blob/master/requirements.txt"
```
