# ikramkhaecu/madrl_blackstart architecture

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

- Interactive diagram: https://gitdiagram.com/ikramkhaecu/madrl_blackstart
- Repository: https://github.com/ikramkhaecu/madrl_blackstart

## Overview

This repository is a small PI-MADRL black-start restoration simulation: a training script runs episodes in a restoration environment using DQN or PPO agents, then saves training history and an episode replay for inspection. The environment models switching, generation and load restoration, battery state, observations, and reward. The README describes a much broader v2 framework, but its listed modules are absent from this tree; the graph therefore reflects the available implementation and treats visualization wiring as unverified.

Main entry points: [`scripts/train.py`](https://github.com/ikramkhaecu/madrl_blackstart/blob/main/scripts/train.py) (Training runner), [`static/visualizer.html`](https://github.com/ikramkhaecu/madrl_blackstart/blob/main/static/visualizer.html) (Replay visualizer), [`src/envs/blackstart_env.py`](https://github.com/ikramkhaecu/madrl_blackstart/blob/main/src/envs/blackstart_env.py) (Black-start environment), [`src/agents/dqn_agent.py`](https://github.com/ikramkhaecu/madrl_blackstart/blob/main/src/agents/dqn_agent.py) (DQN agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiment["Training workflow"]
  node_trainer["Training runner<br/>[train.py]"]
end

subgraph group_restoration["Restoration simulation"]
  node_environment["Black-start environment<br/>[blackstart_env.py]"]
end

subgraph group_learning["RL agents and results"]
  node_dqn["DQN agent<br/>[dqn_agent.py]"]
  node_ppo["PPO agent<br/>[ppo_agent.py]"]
  node_artifacts["Training and replay files<br/>[train.py]"]
  node_visualizer["Replay visualizer<br/>[visualizer.html]"]
end

node_operator(("Experiment operator"))

node_operator -->|"runs training"| node_trainer
node_trainer -->|"steps episodes"| node_environment
node_trainer -->|"trains with"| node_dqn
node_trainer -->|"trains with"| node_ppo
node_trainer -->|"writes results"| node_artifacts
node_visualizer -.->|"may inspect"| node_artifacts

click node_trainer "https://github.com/ikramkhaecu/madrl_blackstart/blob/main/scripts/train.py"
click node_environment "https://github.com/ikramkhaecu/madrl_blackstart/blob/main/src/envs/blackstart_env.py"
click node_dqn "https://github.com/ikramkhaecu/madrl_blackstart/blob/main/src/agents/dqn_agent.py"
click node_ppo "https://github.com/ikramkhaecu/madrl_blackstart/blob/main/src/agents/ppo_agent.py"
click node_artifacts "https://github.com/ikramkhaecu/madrl_blackstart/blob/main/scripts/train.py"
click node_visualizer "https://github.com/ikramkhaecu/madrl_blackstart/blob/main/static/visualizer.html"

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_trainer toneBlue
class node_environment toneAmber
class node_dqn,node_ppo,node_artifacts,node_visualizer toneMint
class node_operator toneIndigo
```

## Components

### Training workflow

- [Training runner](https://github.com/ikramkhaecu/madrl_blackstart/blob/main/scripts/train.py): `scripts/train.py`

### Restoration simulation

- [Black-start environment](https://github.com/ikramkhaecu/madrl_blackstart/blob/main/src/envs/blackstart_env.py): `src/envs/blackstart_env.py`

### RL agents and results

- [DQN agent](https://github.com/ikramkhaecu/madrl_blackstart/blob/main/src/agents/dqn_agent.py): `src/agents/dqn_agent.py`
- [PPO agent](https://github.com/ikramkhaecu/madrl_blackstart/blob/main/src/agents/ppo_agent.py): `src/agents/ppo_agent.py`
- [Training and replay files](https://github.com/ikramkhaecu/madrl_blackstart/blob/main/scripts/train.py): `scripts/train.py`
- [Replay visualizer](https://github.com/ikramkhaecu/madrl_blackstart/blob/main/static/visualizer.html): `static/visualizer.html`

### Other components

- **Experiment operator**

## Connections

- Experiment operator → Training runner: runs training (evidence: `scripts/train.py`)
- Training runner → Black-start environment: steps episodes (evidence: `scripts/train.py`)
- Training runner → DQN agent: trains with (evidence: `scripts/train.py`)
- Training runner → PPO agent: trains with (evidence: `scripts/train.py`)
- Training runner → Training and replay files: writes results (evidence: `scripts/train.py`)
- Replay visualizer → Training and replay files: may inspect