How rwth-ebc/pycity_resilience works
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.