# rwth-ebc/pycity_resilience architecture

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

- Interactive diagram: https://gitdiagram.com/rwth-ebc/pycity_resilience
- Repository: https://github.com/rwth-ebc/pycity_resilience

## Overview

##### Project Type & Purpose
- The project is an open-source tool focused on optimizing the configuration of urban energy systems under uncertainty.
- It acts as an extension to the pyCity ecosystem by integrating modules for city generation, genetic algorithm (GA) optimization, and Monte Carlo simulations, among other functionalities.
- The README shows that its main use case is in research and practical application in energy system resilience analysis.

##### Analysis of the File Structure
- Top-level Components:
- The main library is in the “pycity_resilience” directory.
- Inside, there are clear submodules such as “city_gen” and “city_gen_diverse_pop” for generating city layouts.
- The “ga” directory introduces a suite of genetic algorithm modules separated into subdirectories: “analyse”, “clustering”, “evolution” (with additional helpers), “evaluate”, “parser”, “postprocess”, “preprocess”, “selection”, and “verify”. This indicates a modular design centered around evolutionary optimization.
- There is also a “monte_carlo” module used for running MC simulations.
- The “inputs” directory contains configuration and sample input files for the city generation tasks.
- “others” provides additional experiments and comparison scripts, supporting auxiliary functions and even benchmarking.
- The “test” directory contains tests that outline unit testing for various components, indicating a focus on component verification.
- The “workspace” directory holds runtime artifacts such as initial populations, outputs from GA runs, and city objects.
- Configuration Files & Build Files:
- Files like setup.py, .travis.yml, and job.sh indicate that the project is set up for CI and deployment.

##### Extraction of Key Architectural Patterns
- Modularization: Each core functionality (city generation, genetic algorithm optimization, Monte Carlo simulation) is encapsulated in its own directory.
- Layered Architecture: You have layers—from input processing, generation of city models, GA-driven optimization, and analysis/postprocessing.
- Extensibility: The modular layout in “ga” (with distinct directories for evolution, parsing, analysis, etc.) shows the intention to extend or modify specific algorithmic tasks independently.
- Integration with External Libraries: The README highlights dependencies such as richardsonpy, uesgraphs, pyCity, pyCity_calc, and TEASER, which serve as building blocks for the simulation and analysis tasks.

##### Components
a. Core Modules:
- City Generation Modules:
- “city_gen” and “city_gen_diverse_pop”: Responsible for generating city models and possibly conditioning them with or without ESYS-based energy system configurations.
- Genetic Algorithm (GA) Framework:
- “ga” submodules, which include:
- Preprocessing: “preprocess” (data cleaning, adding basic energy system elements).
- Parsing: “parser” (translating city models into GA individuals and vice versa).
- Evolution: “evolution” (crossover, mutation, and ESYS changes) with helper functions.
- Selection: “selection” (selecting the fittest individuals).
- Evaluation: “evaluate” (assessing candidate solutions).
- Analysis & Postprocessing: “analyse”, “postprocess”, “verify” (further analysis and checking validity).
- Monte Carlo Simulation Module:
- “monte_carlo”: For running simulation studies to assess uncertainty impacts.
- Inputs & Workspace:
- “inputs”: Providing the initial data files in various formats (e.g., city input, ESYS input).
- “workspace”: A dedicated area for runtime data (initial populations, GA runners, outputs).
- Auxiliary & Experimental Components:
- “others”: Contains experimental scripts (deap experiments, energy benchmarking comparisons) that showcase alternative approaches or extensions.

b. Relationships & Interactions:
- Data Flow:
- Input data from “inputs” (and workspace) flows into the city generation modules.
- Generated city models then feed into the GA framework (initial parsing, evolution processes).
- The GA modules interact among themselves: preprocess → parser → evolution → selection → evaluation → postprocess.
- Monte Carlo simulation often takes outcomes from GA (or directly from the city generation outcomes) to run multiple simulation scenarios.
- External Integrations:
- How the project uses external packages (richardsonpy, uesgraphs, pyCity, etc.) within these modules.
- Testing & Validation:
- “test” module as a component that validates the output of core components.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data/Input Layer
    subgraph "Data/Input Layer"
         I["Inputs"]
         W["Workspace"]
    end

    %% City Generation Modules
    subgraph "City Generation"
         CG1["City Generation"]
         CG2["City Gen Diverse Pop"]
    end

    %% Genetic Algorithm Framework
    subgraph "Genetic Algorithm Framework"
         GA1["GA Preprocessing"]
         GA2["GA Parsing"]
         GA3A["GA Evolution Core"]
         GA3B["GA Evolution Helpers"]
         GA4["GA Selection"]
         GA5["GA Evaluation"]
         GA6["GA Analysis & Postprocessing"]
         GA7["GA Verification"]
    end

    %% Simulation & Analysis Layer
    subgraph "Simulation & Analysis"
         MC["Monte Carlo Simulation"]
    end

    %% Other Components
    subgraph "Other Components"
         AUX["Auxiliary & Experimental Scripts"]
         TEST["Testing & Validation"]
    end

    %% External Dependencies
    subgraph "External Dependencies"
         EXT["External Libraries"]
    end

    %% Data Flow Connections
    I --> CG1
    I --> CG2
    W --> CG1

    CG1 --> GA1
    CG2 --> GA1

    GA1 --> GA2
    GA2 --> GA3A
    GA3A --> GA3B
    GA3B --> GA4
    GA4 --> GA5
    GA5 --> GA6
    GA6 --> GA7

    GA6 --> MC
    GA3B --> AUX
    GA7 --> TEST

    %% External Dependencies Influencing Components
    EXT -.-> GA2
    EXT -.-> GA3A
    EXT -.-> MC

    %% Click Events
    click CG1 "https://github.com/rwth-ebc/pycity_resilience/tree/master/pycity_resilience/city_gen"
    click CG2 "https://github.com/rwth-ebc/pycity_resilience/tree/master/pycity_resilience/city_gen_diverse_pop"
    click GA1 "https://github.com/rwth-ebc/pycity_resilience/tree/master/pycity_resilience/ga/preprocess"
    click GA2 "https://github.com/rwth-ebc/pycity_resilience/tree/master/pycity_resilience/ga/parser"
    click GA3A "https://github.com/rwth-ebc/pycity_resilience/tree/master/pycity_resilience/ga/evolution"
    click GA3B "https://github.com/rwth-ebc/pycity_resilience/tree/master/pycity_resilience/ga/evolution/helpers"
    click GA4 "https://github.com/rwth-ebc/pycity_resilience/tree/master/pycity_resilience/ga/selection"
    click GA5 "https://github.com/rwth-ebc/pycity_resilience/tree/master/pycity_resilience/ga/evaluate"
    click GA6 "https://github.com/rwth-ebc/pycity_resilience/tree/master/pycity_resilience/ga/analyse"
    click GA6 "https://github.com/rwth-ebc/pycity_resilience/tree/master/pycity_resilience/ga/postprocess"
    click GA7 "https://github.com/rwth-ebc/pycity_resilience/tree/master/pycity_resilience/ga/verify"
    click MC "https://github.com/rwth-ebc/pycity_resilience/tree/master/pycity_resilience/monte_carlo"
    click I "https://github.com/rwth-ebc/pycity_resilience/tree/master/pycity_resilience/inputs"
    click W "https://github.com/rwth-ebc/pycity_resilience/tree/master/workspace"
    click AUX "https://github.com/rwth-ebc/pycity_resilience/tree/master/pycity_resilience/others"
    click TEST "https://github.com/rwth-ebc/pycity_resilience/tree/master/pycity_resilience/test"

    %% Styles and Colors
    classDef dataLayer fill:#f2f2f2,stroke:#333,stroke-width:2px;
    classDef cityGeneration fill:#bbd,stroke:#333,stroke-width:2px;
    classDef genetic fill:#aaf,stroke:#333,stroke-width:2px;
    classDef simulation fill:#afa,stroke:#333,stroke-width:2px;
    classDef other fill:#ffa,stroke:#333,stroke-width:2px;
    classDef external fill:#ddd,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;

    class I,W dataLayer;
    class CG1,CG2 cityGeneration;
    class GA1,GA2,GA3A,GA3B,GA4,GA5,GA6,GA7 genetic;
    class MC simulation;
    class AUX,TEST other;
    class EXT external;
```
