# alaa-sleimi/pypsa-mga-explorer architecture

> Architecture diagram of the GitHub repository alaa-sleimi/pypsa-mga-explorer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alaa-sleimi/pypsa-mga-explorer
- Repository: https://github.com/alaa-sleimi/pypsa-mga-explorer

## Overview

pypsa-mga-explorer is a notebook-driven tool for exploring near-optimal alternatives in PyPSA energy-system models. Its preparation phase finds the cost optimum, samples the near-optimal space, prices the samples, and caches the results. Its interactive phase loads those samples, turns user preferences into a target, and analyzes the path to that target; it can also project the space for plotting and attempt experimental surrogate cost recovery. The README and sampled module docstrings establish the main stages; the notebook’s cell-level wiring and some module internals were not sampled, so uncertain links are omitted.

Main entry points: [`mga_exploration.ipynb`](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_exploration.ipynb) (Workflow notebook), [`mga_engine/preparation_state.py`](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/preparation_state.py) (Preparation orchestration), [`mga_engine/vertex_sampling.py`](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/vertex_sampling.py) (Boundary sampling), [`mga_engine/interior_sampling.py`](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/interior_sampling.py) (Interior sampling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_preparation["Preparation"]
  node_poi["PoI definitions<br/>[poi.py]"]
  node_vertex["Boundary sampling<br/>[vertex_sampling.py]"]
  node_interior["Interior sampling"]
  node_pricing["Sample pricing<br/>[gp_solver.py]"]
  node_prep["Preparation orchestration"]
end

subgraph group_exploration["Exploration"]
  node_notebook["Workflow notebook"]
  node_navigation["Preference navigation<br/>[navigation.py]"]
  node_traverse["Path analysis<br/>[traverse.py]"]
  node_ccp["CCP solver<br/>[ccp_solver.py]"]
end

subgraph group_analysis["Analysis and plots"]
  node_projection["Live projection<br/>[projection.py]"]
  node_alpha["Sample projection"]
  node_surrogate["Surrogate recovery<br/>[surrogate.py]"]
end

subgraph group_state["Cached state"]
  node_cache[("Preparation cache")]
end

node_user(("Analyst"))
node_solver(("HiGHS solver"))

node_user -->|"runs workflow"| node_notebook
node_notebook -->|"requests preparation"| node_prep
node_prep -->|"builds PoIs"| node_poi
node_prep -->|"samples boundary"| node_vertex
node_prep -->|"samples interior"| node_interior
node_interior -->|"calls sampler"| node_vertex
node_prep -->|"prices samples"| node_pricing
node_prep -->|"saves state"| node_cache
node_cache -->|"loads state"| node_notebook
node_notebook -->|"submits preferences"| node_navigation
node_notebook -->|"requests path analysis"| node_traverse
node_traverse -->|"prices path points"| node_ccp
node_notebook -.->|"requests live projection"| node_projection
node_notebook -.->|"requests sample projection"| node_alpha
node_notebook -.->|"requests recovery"| node_surrogate
node_vertex -->|"solves LP"| node_solver
node_pricing -->|"solves LP"| node_solver
node_navigation -->|"solves LPs"| node_solver
node_ccp -->|"solves LP"| node_solver
node_projection -->|"solves LPs"| node_solver
node_surrogate -->|"solves MILP"| node_solver

click node_notebook "https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_exploration.ipynb"
click node_poi "https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/poi.py"
click node_vertex "https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/vertex_sampling.py"
click node_interior "https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/interior_sampling.py"
click node_pricing "https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/gp_solver.py"
click node_prep "https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/preparation_state.py"
click node_cache "https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/preparation_state.py"
click node_navigation "https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/navigation.py"
click node_traverse "https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/traverse.py"
click node_ccp "https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/ccp_solver.py"
click node_projection "https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/projection.py"
click node_alpha "https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/alpha_projection.py"
click node_surrogate "https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/surrogate.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_poi,node_vertex,node_interior,node_pricing,node_prep toneBlue
class node_notebook,node_navigation,node_traverse,node_ccp toneAmber
class node_projection,node_alpha,node_surrogate toneMint
class node_cache toneRose
class node_user,node_solver toneIndigo
```

## Components

### Preparation

- [PoI definitions](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/poi.py): `mga_engine/poi.py`
- [Boundary sampling](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/vertex_sampling.py): `mga_engine/vertex_sampling.py`
- [Interior sampling](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/interior_sampling.py): `mga_engine/interior_sampling.py`
- [Sample pricing](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/gp_solver.py): `mga_engine/gp_solver.py`
- [Preparation orchestration](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/preparation_state.py): `mga_engine/preparation_state.py`

### Exploration

- [Workflow notebook](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_exploration.ipynb): `mga_exploration.ipynb`
- [Preference navigation](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/navigation.py): `mga_engine/navigation.py`
- [Path analysis](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/traverse.py): `mga_engine/traverse.py`
- [CCP solver](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/ccp_solver.py): `mga_engine/ccp_solver.py`

### Analysis and plots

- [Live projection](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/projection.py): `mga_engine/projection.py`
- [Sample projection](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/alpha_projection.py): `mga_engine/alpha_projection.py`
- [Surrogate recovery](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/surrogate.py): `mga_engine/surrogate.py`

### Cached state

- [Preparation cache](https://github.com/alaa-sleimi/pypsa-mga-explorer/blob/master/mga_engine/preparation_state.py): `mga_engine/preparation_state.py`

### Other components

- **Analyst**
- **HiGHS solver**

## Connections

- Analyst → Workflow notebook: runs workflow
- Workflow notebook → Preparation orchestration: requests preparation
- Preparation orchestration → PoI definitions: builds PoIs
- Preparation orchestration → Boundary sampling: samples boundary
- Preparation orchestration → Interior sampling: samples interior
- Interior sampling → Boundary sampling: calls sampler
- Preparation orchestration → Sample pricing: prices samples
- Preparation orchestration → Preparation cache: saves state
- Preparation cache → Workflow notebook: loads state
- Workflow notebook → Preference navigation: submits preferences
- Workflow notebook → Path analysis: requests path analysis
- Path analysis → CCP solver: prices path points
- Workflow notebook → Live projection: requests live projection
- Workflow notebook → Sample projection: requests sample projection
- Workflow notebook → Surrogate recovery: requests recovery
- Boundary sampling → HiGHS solver: solves LP
- Sample pricing → HiGHS solver: solves LP
- Preference navigation → HiGHS solver: solves LPs
- CCP solver → HiGHS solver: solves LP
- Live projection → HiGHS solver: solves LPs
- Surrogate recovery → HiGHS solver: solves MILP