# spk-22/urban_el architecture

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

- Interactive diagram: https://gitdiagram.com/spk-22/urban_el
- Repository: https://github.com/spk-22/urban_el

## Overview

This is a Bengaluru urban-infrastructure cascading-failure research project. Researchers reconstruct road, power, and water networks, seed disruptions, and simulate layer-specific failure propagation; Phase 2 maps dependencies and iterates coupled cascades, then compares scenarios and sensitivities. The graph preserves the documented validation, spatial-map, and coupling-hierarchy branches. Source excerpts show key model behavior and some orchestration; several analysis steps are represented by their indexed entry-point files, so uncertain internal calls are omitted.

Main entry points: [`models/graph_builder.py`](https://github.com/spk-22/urban_el/blob/main/models/graph_builder.py) (Graph builder), [`simulations/run_all_phase1_validation.py`](https://github.com/spk-22/urban_el/blob/main/simulations/run_all_phase1_validation.py) (Phase 1 validation), [`simulations/run_phase2_analysis.py`](https://github.com/spk-22/urban_el/blob/main/simulations/run_phase2_analysis.py) (Phase 2 analysis), [`simulations/plot_m7_propagation_curves.py`](https://github.com/spk-22/urban_el/blob/main/simulations/plot_m7_propagation_curves.py) (M7 propagation analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_networks["Network reconstruction"]
  node_graph_builder["Graph builder<br/>[graph_builder.py]"]
  node_road_graph["Road network<br/>[graph_builder.py]"]
  node_power_graph["Power network<br/>[graph_builder.py]"]
  node_water_graph["Water network<br/>[graph_builder.py]"]
end

subgraph group_single["Single-layer cascades"]
  node_road_engine["Road cascade<br/>[road_cascade.py]"]
  node_power_engine["Power cascade<br/>[power_cascade.py]"]
  node_water_engine["Water cascade<br/>[water_cascade.py]"]
  node_phase1_validation["Phase 1 validation"]
end

subgraph group_coupled["Cross-layer coupling"]
  node_dependency_mapper["Dependency mapper"]
  node_coupled_controller["Coupled cascade controller"]
  node_phase2_analysis["Phase 2 analysis"]
end

subgraph group_research["Research analysis"]
  node_hierarchy_analysis["Coupling hierarchy experiments"]
  node_propagation_analysis["M7 propagation analysis"]
  node_phase1_report["Phase 1 findings<br/>[PHASE1_REPORT.md]"]
  node_phase2_report["Phase 2 findings<br/>[PHASE2_REPORT.md]"]
end

subgraph group_presentation["Maps and results"]
  node_phase2_results["Phase 2 result tables"]
  node_spatial_maps["Spatial maps"]
  node_map_outputs["Map outputs"]
end

node_researcher(("Researcher"))
node_processed_data["Processed networks"]

node_researcher -->|"runs validation"| node_phase1_validation
node_researcher -->|"runs analysis"| node_phase2_analysis
node_processed_data -.->|"supplies network data"| node_graph_builder
node_graph_builder -->|"reconstructs"| node_road_graph
node_graph_builder -->|"reconstructs"| node_power_graph
node_graph_builder -->|"reconstructs"| node_water_graph
node_phase1_validation -->|"builds graphs"| node_graph_builder
node_phase1_validation -->|"runs scenarios"| node_road_engine
node_phase1_validation -->|"runs scenarios"| node_power_engine
node_phase1_validation -->|"runs scenarios"| node_water_engine
node_phase1_validation -.->|"informs findings"| node_phase1_report
node_phase2_analysis -->|"builds graphs"| node_graph_builder
node_phase2_analysis -->|"maps dependencies"| node_dependency_mapper
node_phase2_analysis -->|"runs coupled cases"| node_coupled_controller
node_dependency_mapper -->|"provides dependency maps"| node_coupled_controller
node_coupled_controller -->|"runs inner cascade"| node_power_engine
node_coupled_controller -->|"runs inner cascade"| node_water_engine
node_coupled_controller -.->|"runs inner cascade"| node_road_engine
node_phase2_analysis -.->|"records comparisons"| node_phase2_results
node_phase2_analysis -.->|"informs findings"| node_phase2_report
node_researcher -->|"runs experiments"| node_hierarchy_analysis
node_hierarchy_analysis -->|"builds graphs"| node_graph_builder
node_hierarchy_analysis -->|"maps dependencies"| node_dependency_mapper
node_hierarchy_analysis -.->|"tests coupling models"| node_coupled_controller
node_researcher -.->|"inspects propagation"| node_propagation_analysis
node_propagation_analysis -->|"builds graphs"| node_graph_builder
node_propagation_analysis -->|"maps dependencies"| node_dependency_mapper
node_propagation_analysis -->|"runs cascade"| node_power_engine
node_propagation_analysis -->|"runs cascade"| node_water_engine
node_propagation_analysis -->|"runs cascade"| node_road_engine
node_researcher -->|"generates maps"| node_spatial_maps
node_spatial_maps -->|"builds graphs"| node_graph_builder
node_spatial_maps -->|"writes maps"| node_map_outputs

click node_processed_data "https://github.com/spk-22/urban_el/tree/main/processed"
click node_graph_builder "https://github.com/spk-22/urban_el/blob/main/models/graph_builder.py"
click node_road_graph "https://github.com/spk-22/urban_el/blob/main/models/graph_builder.py"
click node_power_graph "https://github.com/spk-22/urban_el/blob/main/models/graph_builder.py"
click node_water_graph "https://github.com/spk-22/urban_el/blob/main/models/graph_builder.py"
click node_road_engine "https://github.com/spk-22/urban_el/blob/main/models/road_cascade.py"
click node_power_engine "https://github.com/spk-22/urban_el/blob/main/models/power_cascade.py"
click node_water_engine "https://github.com/spk-22/urban_el/blob/main/models/water_cascade.py"
click node_phase1_validation "https://github.com/spk-22/urban_el/blob/main/simulations/run_all_phase1_validation.py"
click node_dependency_mapper "https://github.com/spk-22/urban_el/blob/main/models/dependency_mapper.py"
click node_coupled_controller "https://github.com/spk-22/urban_el/blob/main/models/multi_layer_cascade.py"
click node_phase2_analysis "https://github.com/spk-22/urban_el/blob/main/simulations/run_phase2_analysis.py"
click node_hierarchy_analysis "https://github.com/spk-22/urban_el/blob/main/simulations/run_coupling_hierarchy.py"
click node_propagation_analysis "https://github.com/spk-22/urban_el/blob/main/simulations/plot_m7_propagation_curves.py"
click node_phase1_report "https://github.com/spk-22/urban_el/blob/main/PHASE1_REPORT.md"
click node_phase2_report "https://github.com/spk-22/urban_el/blob/main/PHASE2_REPORT.md"
click node_phase2_results "https://github.com/spk-22/urban_el/tree/main/phase2_results/tables"
click node_spatial_maps "https://github.com/spk-22/urban_el/blob/main/simulations/generate_spatial_maps.py"
click node_map_outputs "https://github.com/spk-22/urban_el/tree/main/outputs/figures"

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_graph_builder,node_road_graph,node_power_graph,node_water_graph toneBlue
class node_road_engine,node_power_engine,node_water_engine,node_phase1_validation toneAmber
class node_dependency_mapper,node_coupled_controller,node_phase2_analysis toneMint
class node_hierarchy_analysis,node_propagation_analysis,node_phase1_report,node_phase2_report toneRose
class node_phase2_results,node_spatial_maps,node_map_outputs,node_researcher toneIndigo
class node_processed_data toneTeal
```

## Components

### Network reconstruction

- [Graph builder](https://github.com/spk-22/urban_el/blob/main/models/graph_builder.py): `models/graph_builder.py`
- [Road network](https://github.com/spk-22/urban_el/blob/main/models/graph_builder.py): `models/graph_builder.py`
- [Power network](https://github.com/spk-22/urban_el/blob/main/models/graph_builder.py): `models/graph_builder.py`
- [Water network](https://github.com/spk-22/urban_el/blob/main/models/graph_builder.py): `models/graph_builder.py`

### Single-layer cascades

- [Road cascade](https://github.com/spk-22/urban_el/blob/main/models/road_cascade.py): `models/road_cascade.py`
- [Power cascade](https://github.com/spk-22/urban_el/blob/main/models/power_cascade.py): `models/power_cascade.py`
- [Water cascade](https://github.com/spk-22/urban_el/blob/main/models/water_cascade.py): `models/water_cascade.py`
- [Phase 1 validation](https://github.com/spk-22/urban_el/blob/main/simulations/run_all_phase1_validation.py): `simulations/run_all_phase1_validation.py`

### Cross-layer coupling

- [Dependency mapper](https://github.com/spk-22/urban_el/blob/main/models/dependency_mapper.py): `models/dependency_mapper.py`
- [Coupled cascade controller](https://github.com/spk-22/urban_el/blob/main/models/multi_layer_cascade.py): `models/multi_layer_cascade.py`
- [Phase 2 analysis](https://github.com/spk-22/urban_el/blob/main/simulations/run_phase2_analysis.py): `simulations/run_phase2_analysis.py`

### Research analysis

- [Coupling hierarchy experiments](https://github.com/spk-22/urban_el/blob/main/simulations/run_coupling_hierarchy.py): `simulations/run_coupling_hierarchy.py`
- [M7 propagation analysis](https://github.com/spk-22/urban_el/blob/main/simulations/plot_m7_propagation_curves.py): `simulations/plot_m7_propagation_curves.py`
- [Phase 1 findings](https://github.com/spk-22/urban_el/blob/main/PHASE1_REPORT.md): `PHASE1_REPORT.md`
- [Phase 2 findings](https://github.com/spk-22/urban_el/blob/main/PHASE2_REPORT.md): `PHASE2_REPORT.md`

### Maps and results

- [Phase 2 result tables](https://github.com/spk-22/urban_el/tree/main/phase2_results/tables): `phase2_results/tables`
- [Spatial maps](https://github.com/spk-22/urban_el/blob/main/simulations/generate_spatial_maps.py): `simulations/generate_spatial_maps.py`
- [Map outputs](https://github.com/spk-22/urban_el/tree/main/outputs/figures): `outputs/figures`

### Other components

- **Researcher**
- [Processed networks](https://github.com/spk-22/urban_el/tree/main/processed): `processed`

## Connections

- Researcher → Phase 1 validation: runs validation (evidence: `README.md`)
- Researcher → Phase 2 analysis: runs analysis (evidence: `README.md`)
- Processed networks → Graph builder: supplies network data
- Graph builder → Road network: reconstructs (evidence: `models/graph_builder.py`)
- Graph builder → Power network: reconstructs (evidence: `models/graph_builder.py`)
- Graph builder → Water network: reconstructs (evidence: `models/graph_builder.py`)
- Phase 1 validation → Graph builder: builds graphs (evidence: `simulations/run_all_phase1_validation.py`)
- Phase 1 validation → Road cascade: runs scenarios (evidence: `simulations/run_all_phase1_validation.py`)
- Phase 1 validation → Power cascade: runs scenarios (evidence: `simulations/run_all_phase1_validation.py`)
- Phase 1 validation → Water cascade: runs scenarios (evidence: `simulations/run_all_phase1_validation.py`)
- Phase 1 validation → Phase 1 findings: informs findings
- Phase 2 analysis → Graph builder: builds graphs (evidence: `simulations/run_phase2_analysis.py`)
- Phase 2 analysis → Dependency mapper: maps dependencies (evidence: `simulations/run_phase2_analysis.py`)
- Phase 2 analysis → Coupled cascade controller: runs coupled cases (evidence: `simulations/run_phase2_analysis.py`)
- Dependency mapper → Coupled cascade controller: provides dependency maps (evidence: `models/multi_layer_cascade.py`)
- Coupled cascade controller → Power cascade: runs inner cascade (evidence: `models/multi_layer_cascade.py`)
- Coupled cascade controller → Water cascade: runs inner cascade (evidence: `models/multi_layer_cascade.py`)
- Coupled cascade controller → Road cascade: runs inner cascade (evidence: `models/multi_layer_cascade.py`)
- Phase 2 analysis → Phase 2 result tables: records comparisons
- Phase 2 analysis → Phase 2 findings: informs findings
- Researcher → Coupling hierarchy experiments: runs experiments (evidence: `README.md`)
- Coupling hierarchy experiments → Graph builder: builds graphs (evidence: `simulations/run_coupling_hierarchy.py`)
- Coupling hierarchy experiments → Dependency mapper: maps dependencies (evidence: `simulations/run_coupling_hierarchy.py`)
- Coupling hierarchy experiments → Coupled cascade controller: tests coupling models (evidence: `simulations/run_coupling_hierarchy.py`)
- Researcher → M7 propagation analysis: inspects propagation
- M7 propagation analysis → Graph builder: builds graphs (evidence: `simulations/plot_m7_propagation_curves.py`)
- M7 propagation analysis → Dependency mapper: maps dependencies (evidence: `simulations/plot_m7_propagation_curves.py`)
- M7 propagation analysis → Power cascade: runs cascade (evidence: `simulations/plot_m7_propagation_curves.py`)
- M7 propagation analysis → Water cascade: runs cascade (evidence: `simulations/plot_m7_propagation_curves.py`)
- M7 propagation analysis → Road cascade: runs cascade (evidence: `simulations/plot_m7_propagation_curves.py`)
- Researcher → Spatial maps: generates maps (evidence: `README.md`)
- Spatial maps → Graph builder: builds graphs (evidence: `simulations/generate_spatial_maps.py`)
- Spatial maps → Map outputs: writes maps (evidence: `simulations/generate_spatial_maps.py`)
