# ssossou-liege/microgridspy-expansion architecture

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

- Interactive diagram: https://gitdiagram.com/ssossou-liege/microgridspy-expansion
- Repository: https://github.com/ssossou-liege/microgridspy-expansion

## Overview

microgrid-expansion sizes off-grid community microgrids under demand, cost, and resource uncertainty. The main workflow starts with a project or site, builds demand and resource inputs, samples futures and reduces them to a scenario tree, then assembles and solves a capacity-expansion model; a separate branch-and-simulate search certifies a reference-year design against the deployed controller. Post-processing reports costs and KPIs. The graph preserves the UI, demand calibration, resource acquisition, multi-stage planning, and exact-sizing branches. Some subsystem links are documented rather than verified from full source; edges cite the README or indexed excerpts.

Main entry points: [`src/microgrid_expansion/demand/generator.py`](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/demand/generator.py) (Demand simulation), [`src/microgrid_expansion/ui/engine.py`](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/ui/engine.py) (Project engine), [`src/microgrid_expansion/run.py`](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/run.py) (Plan runner), [`src/microgrid_expansion/exact/certify.py`](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/exact/certify.py) (Exact sizing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Project interface"]
  node_ui["Local UI<br/>[server.py]"]
  node_project["Project engine<br/>[engine.py]"]
  node_settings["Project settings<br/>[settings.py]"]
end

subgraph group_inputs["Community inputs"]
  node_site["Site data<br/>[sites.py]"]
  node_demand["Demand simulation<br/>[generator.py]"]
  node_archetypes["Demand archetypes<br/>[archetypes.py]"]
  node_uses["Declared uses<br/>[uses.py]"]
  node_connection["Connection growth<br/>[connection.py]"]
  node_growth["Demand growth<br/>[growth.py]"]
  node_era5["ERA5 acquisition<br/>[era5.py]"]
  node_climate["Climate pathways<br/>[cmip6.py]"]
  node_yield["PV yield model<br/>[yield_model.py]"]
  node_instance["Year instance<br/>[instances.py]"]
end

subgraph group_uncertainty["Uncertainty planning"]
  node_scenario["Scenario sampling<br/>[assemble.py]"]
  node_tree["Scenario tree<br/>[build_tree.py]"]
  node_reduction["Tree reduction<br/>[reduce.py]"]
end

subgraph group_optimization["Sizing and certification"]
  node_run["Plan runner<br/>[run.py]"]
  node_model["Expansion model<br/>[build.py]"]
  node_solver["Solver driver<br/>[driver.py]"]
  node_certify["Exact sizing<br/>[certify.py]"]
  node_simulator["Dispatch simulator<br/>[simulator.py]"]
  node_lower["Cost lower bound<br/>[lower_bound.py]"]
end

subgraph group_results["Assessment"]
  node_appraisal["Economic appraisal<br/>[appraisal.py]"]
  node_report["Results reporting<br/>[report.py]"]
end

node_user(("Planner"))
node_cds[("Climate Data Store")]

node_user -->|"configures study"| node_ui
node_ui -->|"requests sizing"| node_project
node_project -->|"uses parameters"| node_settings
node_project -->|"runs tree plan"| node_run
node_project -->|"certifies year"| node_certify
node_site -->|"supplies community"| node_demand
node_demand -->|"uses profiles"| node_archetypes
node_demand -->|"samples activities"| node_uses
node_demand -->|"uses connection schedule"| node_connection
node_demand -->|"uses growth"| node_growth
node_cds -.->|"provides weather data"| node_era5
node_site -->|"sets request location"| node_era5
node_site -->|"selects site pathway"| node_climate
node_instance -->|"generates load"| node_demand
node_instance -->|"loads resource yield"| node_yield
node_era5 -.->|"supplies irradiance"| node_yield
node_run -->|"assembles futures"| node_scenario
node_scenario -->|"provides scenarios"| node_tree
node_tree -->|"reduces ensemble"| node_reduction
node_run -->|"assembles plan"| node_model
node_model -->|"solves MILP"| node_solver
node_certify -->|"computes lower bound"| node_lower
node_certify -->|"evaluates designs"| node_simulator
node_simulator -.->|"uses hourly inputs"| node_instance
node_run -.->|"appraises plan"| node_appraisal
node_certify -->|"appraises certificate"| node_appraisal
node_appraisal -.->|"feeds reporting"| node_report

click node_ui "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/ui/server.py"
click node_project "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/ui/engine.py"
click node_settings "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/settings.py"
click node_site "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/sites.py"
click node_demand "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/demand/generator.py"
click node_archetypes "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/demand/archetypes.py"
click node_uses "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/demand/uses.py"
click node_connection "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/demand/connection.py"
click node_growth "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/demand/growth.py"
click node_era5 "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/resource/era5.py"
click node_climate "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/resource/cmip6.py"
click node_yield "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/resource/yield_model.py"
click node_instance "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/instances.py"
click node_scenario "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/scenarios/assemble.py"
click node_tree "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/tree/build_tree.py"
click node_reduction "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/tree/reduce.py"
click node_run "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/run.py"
click node_model "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/model/build.py"
click node_solver "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/solve/driver.py"
click node_certify "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/exact/certify.py"
click node_simulator "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/exact/simulator.py"
click node_lower "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/exact/lower_bound.py"
click node_appraisal "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/post/appraisal.py"
click node_report "https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/post/report.py"

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_ui,node_project,node_settings toneBlue
class node_site,node_demand,node_archetypes,node_uses,node_connection,node_growth,node_era5,node_climate,node_yield,node_instance,node_cds toneAmber
class node_scenario,node_tree,node_reduction toneMint
class node_run,node_model,node_solver,node_certify,node_simulator,node_lower toneRose
class node_appraisal,node_report,node_user toneIndigo
```

## Components

### Project interface

- [Local UI](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/ui/server.py): `src/microgrid_expansion/ui/server.py`
- [Project engine](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/ui/engine.py): `src/microgrid_expansion/ui/engine.py`
- [Project settings](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/settings.py): `src/microgrid_expansion/settings.py`

### Community inputs

- [Site data](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/sites.py): `src/microgrid_expansion/sites.py`
- [Demand simulation](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/demand/generator.py): `src/microgrid_expansion/demand/generator.py`
- [Demand archetypes](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/demand/archetypes.py): `src/microgrid_expansion/demand/archetypes.py`
- [Declared uses](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/demand/uses.py): `src/microgrid_expansion/demand/uses.py`
- [Connection growth](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/demand/connection.py): `src/microgrid_expansion/demand/connection.py`
- [Demand growth](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/demand/growth.py): `src/microgrid_expansion/demand/growth.py`
- [ERA5 acquisition](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/resource/era5.py): `src/microgrid_expansion/resource/era5.py`
- [Climate pathways](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/resource/cmip6.py): `src/microgrid_expansion/resource/cmip6.py`
- [PV yield model](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/resource/yield_model.py): `src/microgrid_expansion/resource/yield_model.py`
- [Year instance](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/instances.py): `src/microgrid_expansion/instances.py`

### Uncertainty planning

- [Scenario sampling](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/scenarios/assemble.py): `src/microgrid_expansion/scenarios/assemble.py`
- [Scenario tree](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/tree/build_tree.py): `src/microgrid_expansion/tree/build_tree.py`
- [Tree reduction](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/tree/reduce.py): `src/microgrid_expansion/tree/reduce.py`

### Sizing and certification

- [Plan runner](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/run.py): `src/microgrid_expansion/run.py`
- [Expansion model](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/model/build.py): `src/microgrid_expansion/model/build.py`
- [Solver driver](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/solve/driver.py): `src/microgrid_expansion/solve/driver.py`
- [Exact sizing](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/exact/certify.py): `src/microgrid_expansion/exact/certify.py`
- [Dispatch simulator](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/exact/simulator.py): `src/microgrid_expansion/exact/simulator.py`
- [Cost lower bound](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/exact/lower_bound.py): `src/microgrid_expansion/exact/lower_bound.py`

### Assessment

- [Economic appraisal](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/post/appraisal.py): `src/microgrid_expansion/post/appraisal.py`
- [Results reporting](https://github.com/ssossou-liege/microgridspy-expansion/blob/master/src/microgrid_expansion/post/report.py): `src/microgrid_expansion/post/report.py`

### Other components

- **Planner**
- **Climate Data Store**

## Connections

- Planner → Local UI: configures study
- Local UI → Project engine: requests sizing (evidence: `src/microgrid_expansion/ui/server.py`)
- Project engine → Project settings: uses parameters (evidence: `src/microgrid_expansion/ui/engine.py`)
- Project engine → Plan runner: runs tree plan (evidence: `src/microgrid_expansion/ui/engine.py`)
- Project engine → Exact sizing: certifies year (evidence: `src/microgrid_expansion/ui/engine.py`)
- Site data → Demand simulation: supplies community (evidence: `src/microgrid_expansion/demand/generator.py`)
- Demand simulation → Demand archetypes: uses profiles (evidence: `src/microgrid_expansion/demand/generator.py`)
- Demand simulation → Declared uses: samples activities (evidence: `src/microgrid_expansion/demand/generator.py`)
- Demand simulation → Connection growth: uses connection schedule (evidence: `src/microgrid_expansion/demand/generator.py`)
- Demand simulation → Demand growth: uses growth (evidence: `src/microgrid_expansion/demand/generator.py`)
- Climate Data Store → ERA5 acquisition: provides weather data
- Site data → ERA5 acquisition: sets request location (evidence: `data/irradiance/download.py`)
- Site data → Climate pathways: selects site pathway (evidence: `src/microgrid_expansion/resource/cmip6.py`)
- Year instance → Demand simulation: generates load (evidence: `src/microgrid_expansion/instances.py`)
- Year instance → PV yield model: loads resource yield (evidence: `src/microgrid_expansion/instances.py`)
- ERA5 acquisition → PV yield model: supplies irradiance
- Plan runner → Scenario sampling: assembles futures
- Scenario sampling → Scenario tree: provides scenarios (evidence: `src/microgrid_expansion/tree/build_tree.py`)
- Scenario tree → Tree reduction: reduces ensemble (evidence: `src/microgrid_expansion/tree/build_tree.py`)
- Plan runner → Expansion model: assembles plan
- Expansion model → Solver driver: solves MILP
- Exact sizing → Cost lower bound: computes lower bound (evidence: `src/microgrid_expansion/exact/certify.py`)
- Exact sizing → Dispatch simulator: evaluates designs (evidence: `src/microgrid_expansion/exact/certify.py`)
- Dispatch simulator → Year instance: uses hourly inputs
- Plan runner → Economic appraisal: appraises plan
- Exact sizing → Economic appraisal: appraises certificate (evidence: `src/microgrid_expansion/exact/certify.py`)
- Economic appraisal → Results reporting: feeds reporting