# husal10/zuritwinbench architecture

> Architecture diagram of the GitHub repository husal10/zuritwinbench, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/husal10/zuritwinbench
- Repository: https://github.com/husal10/zuritwinbench

## Overview

ZuriTwinBench is a calibrated SUMO digital twin of Zürich’s Langstrasse intersection. Its main workflow uses observed detector and signal data to generate traffic demand, combines that demand with the intersection network, runs a full-day microscopic simulation, and evaluates simulated detector counts against observations. The repository also includes a benchmark scenario and protocol. The excerpts establish the demand-generation, build, simulation-runner, and calibration relationships; links among unsampled SUMO configuration files and runtime components are limited to relationships documented by the README.

Main entry points: [`demand/demand_generator.py`](https://github.com/husal10/zuritwinbench/blob/main/demand/demand_generator.py) (Demand generator), [`build_network.py`](https://github.com/husal10/zuritwinbench/blob/main/build_network.py) (Network builder), [`calibration/geh_evaluator.py`](https://github.com/husal10/zuritwinbench/blob/main/calibration/geh_evaluator.py) (Calibration evaluator), [`simulation/run_sumo.py`](https://github.com/husal10/zuritwinbench/blob/main/simulation/run_sumo.py) (TraCI simulation runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Observed Inputs"]
  node_field_data["Field observations<br/>[feb04_only.csv]"]
  node_demand_gen["Demand generator"]
end

subgraph group_model["Intersection Model"]
  node_network_sources["Network definitions"]
  node_network_builder["Network builder<br/>[build_network.py]"]
  node_sumo_network["Compiled network"]
end

subgraph group_simulation["Simulation"]
  node_routes["Vehicle flows &amp; routes<br/>[flows.rou.xml]"]
  node_trams["Tram schedules<br/>[trams.rou.xml]"]
  node_pedestrians["Pedestrian schedules"]
  node_detectors["Detector setup<br/>[detectors.add.xml]"]
  node_sim_config["SUMO scenario config"]
  node_runner["TraCI simulation runner<br/>[run_sumo.py]"]
  node_detector_output["Simulated detector counts"]
end

subgraph group_evaluation["Calibration &amp; Benchmark"]
  node_evaluator["Calibration evaluator<br/>[geh_evaluator.py]"]
  node_calibration_results["Calibration report &amp; figures"]
  node_benchmark["Benchmark scenario"]
end

node_engineer(("Model user"))
node_sumo{{"SUMO engine"}}

node_engineer -->|"builds model"| node_network_builder
node_engineer -->|"runs simulation"| node_runner
node_engineer -->|"validates calibration"| node_evaluator
node_field_data -->|"provides observations"| node_demand_gen
node_network_builder -->|"invokes generator"| node_demand_gen
node_network_builder -->|"compiles definitions"| node_network_sources
node_demand_gen -->|"writes flows"| node_routes
node_demand_gen -->|"writes schedules"| node_trams
node_demand_gen -->|"writes crossings"| node_pedestrians
node_demand_gen -->|"writes detectors"| node_detectors
node_network_builder -->|"generates network"| node_sumo_network
node_sim_config -->|"configures scenario"| node_sumo_network
node_runner -->|"loads configuration"| node_sim_config
node_runner -->|"controls simulation"| node_sumo
node_sumo -->|"writes counts"| node_detector_output
node_evaluator -->|"reads observations"| node_field_data
node_evaluator -->|"reads simulated counts"| node_detector_output
node_evaluator -->|"produces metrics"| node_calibration_results
node_engineer -->|"uses benchmark"| node_benchmark

click node_field_data "https://github.com/husal10/zuritwinbench/blob/main/data/feb04_only.csv"
click node_demand_gen "https://github.com/husal10/zuritwinbench/blob/main/demand/demand_generator.py"
click node_network_sources "https://github.com/husal10/zuritwinbench/tree/main/network"
click node_network_builder "https://github.com/husal10/zuritwinbench/blob/main/build_network.py"
click node_sumo_network "https://github.com/husal10/zuritwinbench/blob/main/simulation/intersection.net.xml"
click node_routes "https://github.com/husal10/zuritwinbench/blob/main/simulation/flows.rou.xml"
click node_trams "https://github.com/husal10/zuritwinbench/blob/main/simulation/trams.rou.xml"
click node_pedestrians "https://github.com/husal10/zuritwinbench/blob/main/simulation/pedestrians.rou.xml"
click node_detectors "https://github.com/husal10/zuritwinbench/blob/main/simulation/detectors.add.xml"
click node_sim_config "https://github.com/husal10/zuritwinbench/blob/main/simulation/intersection.sumocfg"
click node_runner "https://github.com/husal10/zuritwinbench/blob/main/simulation/run_sumo.py"
click node_detector_output "https://github.com/husal10/zuritwinbench/tree/main/simulation/output"
click node_evaluator "https://github.com/husal10/zuritwinbench/blob/main/calibration/geh_evaluator.py"
click node_calibration_results "https://github.com/husal10/zuritwinbench/tree/main/calibration"
click node_benchmark "https://github.com/husal10/zuritwinbench/tree/main/benchmark"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_field_data,node_demand_gen,node_engineer toneBlue
class node_network_sources,node_network_builder,node_sumo_network toneAmber
class node_routes,node_trams,node_pedestrians,node_detectors,node_sim_config,node_runner,node_detector_output toneMint
class node_evaluator,node_calibration_results,node_benchmark toneRose
class node_sumo toneIndigo
```

## Components

### Observed Inputs

- [Field observations](https://github.com/husal10/zuritwinbench/blob/main/data/feb04_only.csv): `data/feb04_only.csv`
- [Demand generator](https://github.com/husal10/zuritwinbench/blob/main/demand/demand_generator.py): `demand/demand_generator.py`

### Intersection Model

- [Network definitions](https://github.com/husal10/zuritwinbench/tree/main/network): `network`
- [Network builder](https://github.com/husal10/zuritwinbench/blob/main/build_network.py): `build_network.py`
- [Compiled network](https://github.com/husal10/zuritwinbench/blob/main/simulation/intersection.net.xml): `simulation/intersection.net.xml`

### Simulation

- [Vehicle flows & routes](https://github.com/husal10/zuritwinbench/blob/main/simulation/flows.rou.xml): `simulation/flows.rou.xml`
- [Tram schedules](https://github.com/husal10/zuritwinbench/blob/main/simulation/trams.rou.xml): `simulation/trams.rou.xml`
- [Pedestrian schedules](https://github.com/husal10/zuritwinbench/blob/main/simulation/pedestrians.rou.xml): `simulation/pedestrians.rou.xml`
- [Detector setup](https://github.com/husal10/zuritwinbench/blob/main/simulation/detectors.add.xml): `simulation/detectors.add.xml`
- [SUMO scenario config](https://github.com/husal10/zuritwinbench/blob/main/simulation/intersection.sumocfg): `simulation/intersection.sumocfg`
- [TraCI simulation runner](https://github.com/husal10/zuritwinbench/blob/main/simulation/run_sumo.py): `simulation/run_sumo.py`
- [Simulated detector counts](https://github.com/husal10/zuritwinbench/tree/main/simulation/output): `simulation/output`

### Calibration & Benchmark

- [Calibration evaluator](https://github.com/husal10/zuritwinbench/blob/main/calibration/geh_evaluator.py): `calibration/geh_evaluator.py`
- [Calibration report & figures](https://github.com/husal10/zuritwinbench/tree/main/calibration): `calibration`
- [Benchmark scenario](https://github.com/husal10/zuritwinbench/tree/main/benchmark): `benchmark`

### Other components

- **Model user**
- **SUMO engine**

## Connections

- Model user → Network builder: builds model (evidence: `README.md`)
- Model user → TraCI simulation runner: runs simulation (evidence: `README.md`)
- Model user → Calibration evaluator: validates calibration (evidence: `README.md`)
- Field observations → Demand generator: provides observations (evidence: `demand/demand_generator.py`)
- Network builder → Demand generator: invokes generator (evidence: `build_network.py`)
- Network builder → Network definitions: compiles definitions (evidence: `build_network.py`)
- Demand generator → Vehicle flows & routes: writes flows (evidence: `demand/demand_generator.py`)
- Demand generator → Tram schedules: writes schedules (evidence: `demand/demand_generator.py`)
- Demand generator → Pedestrian schedules: writes crossings (evidence: `demand/demand_generator.py`)
- Demand generator → Detector setup: writes detectors (evidence: `demand/demand_generator.py`)
- Network builder → Compiled network: generates network (evidence: `build_network.py`)
- SUMO scenario config → Compiled network: configures scenario (evidence: `README.md`)
- TraCI simulation runner → SUMO scenario config: loads configuration (evidence: `simulation/run_sumo.py`)
- TraCI simulation runner → SUMO engine: controls simulation (evidence: `simulation/run_sumo.py`)
- SUMO engine → Simulated detector counts: writes counts (evidence: `README.md`)
- Calibration evaluator → Field observations: reads observations (evidence: `calibration/geh_evaluator.py`)
- Calibration evaluator → Simulated detector counts: reads simulated counts (evidence: `calibration/geh_evaluator.py`)
- Calibration evaluator → Calibration report & figures: produces metrics (evidence: `README.md`)
- Model user → Benchmark scenario: uses benchmark (evidence: `README.md`)
