# henry-don/grid-connected-bess-control-validation architecture

> Architecture diagram of the GitHub repository henry-don/grid-connected-bess-control-validation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/henry-don/grid-connected-bess-control-validation
- Repository: https://github.com/henry-don/grid-connected-bess-control-validation

## Overview

This repository is a staged grid-connected battery energy storage system (BESS) simulation and automated validation platform. The main workflow starts with a reviewed YAML case matrix, creates a manifest, runs MATLAB/Simulink batch simulations, independently checks metrics in Python, and produces HTML reports with waveforms and verdicts. The README also documents staged grid, control, battery, and protection models plus a separate physically coupled 30-case validation path. Python excerpts establish runner/tool calls; model internals and MATLAB batch implementations were not sampled, so their connections are documented by the README.

Main entry points: [`python/run_phase5.py`](https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/python/run_phase5.py) (Batch Runner), [`python/phase5_tools.py`](https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/python/phase5_tools.py) (Manifest and Checks), [`results`](https://github.com/henry-don/grid-connected-bess-control-validation/tree/main/results) (Simulation Results), [`python/run_physical_report.py`](https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/python/run_physical_report.py) (Physical Report Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_models["BESS Models"]
  node_grid["Grid Model"]
  node_control["Control Model"]
  node_battery["Battery Model"]
  node_protection["Protection Model"]
  node_fastmodel["Fast Batch Model"]
  node_coupled["Coupled BESS"]
  node_physical["Physical Validation"]
end

subgraph group_validation["Validation Workflow"]
  node_cases["Case Matrix<br/>[phase5_cases.yaml]"]
  node_runner["Batch Runner<br/>[run_phase5.py]"]
  node_tools["Manifest and Checks<br/>[phase5_tools.py]"]
  node_physicalreport["Physical Report Runner"]
  node_repoverify["Evidence Verifier"]
end

subgraph group_evidence["Results and Evidence"]
  node_results[("Simulation Results")]
  node_reports["HTML Reports"]
end

node_engineer(("Engineer"))
node_matlab["MATLAB / Simulink"]

node_engineer -->|"launches"| node_runner
node_cases -->|"configures"| node_runner
node_runner -->|"calls"| node_tools
node_runner -->|"launches batch"| node_matlab
node_matlab -->|"simulates"| node_fastmodel
node_fastmodel -->|"produces"| node_results
node_runner -->|"validates"| node_results
node_tools -->|"renders"| node_reports
node_engineer -->|"runs"| node_physicalreport
node_physicalreport -->|"calls"| node_tools
node_physicalreport -->|"validates"| node_results
node_matlab -->|"simulates"| node_physical
node_physical -->|"produces"| node_results
node_tools -->|"renders physical"| node_reports
node_repoverify -->|"reads YAML"| node_tools
node_engineer -->|"inspects"| node_grid
node_engineer -->|"inspects"| node_control
node_engineer -->|"inspects"| node_battery
node_engineer -->|"runs"| node_protection
node_engineer -->|"reviews"| node_coupled

click node_grid "https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/models/bess_phase1_grid_base.slx"
click node_control "https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/models/bess_phase2_controlled.slx"
click node_battery "https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/models/bess_phase3_battery_dcdc.slx"
click node_protection "https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/models/bess_phase4_protection.slx"
click node_fastmodel "https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/models/bess_phase5_integrated.slx"
click node_coupled "https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/models/bess_final_coupled.slx"
click node_physical "https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/models/bess_final_physical_validation.slx"
click node_cases "https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/cases/phase5_cases.yaml"
click node_runner "https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/python/run_phase5.py"
click node_tools "https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/python/phase5_tools.py"
click node_physicalreport "https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/python/run_physical_report.py"
click node_results "https://github.com/henry-don/grid-connected-bess-control-validation/tree/main/results"
click node_reports "https://github.com/henry-don/grid-connected-bess-control-validation/tree/main/results"
click node_repoverify "https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/python/verify_repository.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_grid,node_control,node_battery,node_protection,node_fastmodel,node_coupled,node_physical toneBlue
class node_cases,node_runner,node_tools,node_physicalreport,node_repoverify toneAmber
class node_results,node_reports toneMint
class node_engineer,node_matlab toneIndigo
```

## Components

### BESS Models

- [Grid Model](https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/models/bess_phase1_grid_base.slx): `models/bess_phase1_grid_base.slx`
- [Control Model](https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/models/bess_phase2_controlled.slx): `models/bess_phase2_controlled.slx`
- [Battery Model](https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/models/bess_phase3_battery_dcdc.slx): `models/bess_phase3_battery_dcdc.slx`
- [Protection Model](https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/models/bess_phase4_protection.slx): `models/bess_phase4_protection.slx`
- [Fast Batch Model](https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/models/bess_phase5_integrated.slx): `models/bess_phase5_integrated.slx`
- [Coupled BESS](https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/models/bess_final_coupled.slx): `models/bess_final_coupled.slx`
- [Physical Validation](https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/models/bess_final_physical_validation.slx): `models/bess_final_physical_validation.slx`

### Validation Workflow

- [Case Matrix](https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/cases/phase5_cases.yaml): `cases/phase5_cases.yaml`
- [Batch Runner](https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/python/run_phase5.py): `python/run_phase5.py`
- [Manifest and Checks](https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/python/phase5_tools.py): `python/phase5_tools.py`
- [Physical Report Runner](https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/python/run_physical_report.py): `python/run_physical_report.py`
- [Evidence Verifier](https://github.com/henry-don/grid-connected-bess-control-validation/blob/main/python/verify_repository.py): `python/verify_repository.py`

### Results and Evidence

- [Simulation Results](https://github.com/henry-don/grid-connected-bess-control-validation/tree/main/results): `results`
- [HTML Reports](https://github.com/henry-don/grid-connected-bess-control-validation/tree/main/results): `results`

### Other components

- **Engineer**
- **MATLAB / Simulink**

## Connections

- Engineer → Batch Runner: launches (evidence: `README.md`)
- Case Matrix → Batch Runner: configures (evidence: `python/run_phase5.py`)
- Batch Runner → Manifest and Checks: calls (evidence: `python/run_phase5.py`)
- Batch Runner → MATLAB / Simulink: launches batch (evidence: `python/run_phase5.py`)
- MATLAB / Simulink → Fast Batch Model: simulates (evidence: `README.md`)
- Fast Batch Model → Simulation Results: produces (evidence: `README.md`)
- Batch Runner → Simulation Results: validates (evidence: `python/run_phase5.py`)
- Manifest and Checks → HTML Reports: renders
- Engineer → Physical Report Runner: runs (evidence: `README.md`)
- Physical Report Runner → Manifest and Checks: calls (evidence: `python/run_physical_report.py`)
- Physical Report Runner → Simulation Results: validates (evidence: `python/run_physical_report.py`)
- MATLAB / Simulink → Physical Validation: simulates (evidence: `README.md`)
- Physical Validation → Simulation Results: produces (evidence: `README.md`)
- Manifest and Checks → HTML Reports: renders physical
- Evidence Verifier → Manifest and Checks: reads YAML (evidence: `python/verify_repository.py`)
- Engineer → Grid Model: inspects (evidence: `README.md`)
- Engineer → Control Model: inspects (evidence: `README.md`)
- Engineer → Battery Model: inspects (evidence: `README.md`)
- Engineer → Protection Model: runs (evidence: `README.md`)
- Engineer → Coupled BESS: reviews (evidence: `README.md`)
