# cresym/harmony architecture

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

- Interactive diagram: https://gitdiagram.com/cresym/harmony
- Repository: https://github.com/cresym/harmony

## Overview

Harmony is a framework for modeling and analyzing converter-rich AC/DC power systems, with command-line and graphical entry points. The principal workflow is to provide a JSON configuration, construct a simulation and its network components, then run power-system computations and inspect results. The model covers network elements, renewable plants, converters, and controls; analysis branches include power flow/OPF, state-space modeling, stability estimation, and stability certificates. The README documents CLI, GUI, JSON, and C++-script usage. Sampled source confirms CLI dispatch and JSON component construction; wiring among unsampled subsystems is intentionally left out.

Main entry points: [`src/network.cpp`](https://github.com/cresym/harmony/blob/main/src/network.cpp) (Network), [`src/json/component_builder.cpp`](https://github.com/cresym/harmony/blob/main/src/json/component_builder.cpp) (Component factory), [`src/cli.cpp`](https://github.com/cresym/harmony/blob/main/src/cli.cpp) (CLI dispatch), [`src/main.cpp`](https://github.com/cresym/harmony/blob/main/src/main.cpp) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI dispatch<br/>[cli.cpp]"]
  node_main["CLI entry<br/>[main.cpp]"]
  node_gui["GUI launcher"]
  node_gui_main["GUI entry"]
end

subgraph group_configuration["Configuration"]
  node_json_validation["JSON validation<br/>[json_validator.cpp]"]
  node_json_params["JSON parameters"]
  node_json_expressions["JSON expressions"]
  node_component_builder["Component factory"]
  node_simulation_builder["Simulation builder"]
  node_computation_runner["Computation runner"]
end

subgraph group_model["Power system model"]
  node_network["Network<br/>[network.cpp]"]
  node_subnetwork["Subnetwork<br/>[SubNetwork.cpp]"]
  node_elements["Grid elements<br/>[Element.cpp]"]
  node_converter["Converters<br/>[MMC.cpp]"]
  node_renewables["Renewable plants<br/>[PV_plant.cpp]"]
end

subgraph group_analysis["Analysis and results"]
  node_powerflow["Power flow and OPF"]
  node_state_space["State-space model"]
  node_stability["Stability estimate"]
  node_certificates["Stability certificates"]
  node_visualization["Visualization<br/>[Visualization.cpp]"]
end

subgraph group_control["Control dynamics"]
  node_control["Control blocks<br/>[Control_block.cpp]"]
  node_controllers["P and PI controllers"]
end

node_cli_user(("CLI user"))
node_gui_user(("GUI user"))
node_json_input["JSON input"]
node_cpp_input["C++ scripts"]

node_cli_user -->|"invokes"| node_main
node_main -->|"parses options"| node_cli
node_cli -->|"runs JSON simulation"| node_computation_runner
node_json_input -->|"configures run"| node_computation_runner
node_gui_user -->|"launches"| node_gui
node_gui -->|"starts interface"| node_gui_main
node_cpp_input -->|"selects example"| node_cli
node_json_validation -->|"validates"| node_json_input
node_json_params -->|"resolves parameters"| node_json_input
node_json_expressions -->|"parses expressions"| node_json_input
node_component_builder -->|"constructs elements"| node_elements
node_component_builder -->|"constructs converters"| node_converter
node_component_builder -->|"constructs plants"| node_renewables
node_simulation_builder -->|"builds simulation network"| node_network
node_network -->|"organizes network"| node_subnetwork
node_network -->|"supplies network data"| node_powerflow
node_network -->|"supplies system model"| node_state_space
node_state_space -->|"supports stability analysis"| node_stability
node_stability -->|"informs certification"| node_certificates
node_powerflow -->|"provides results"| node_visualization
node_converter -->|"uses control dynamics"| node_control
node_control -->|"specialized by"| node_controllers

click node_cli "https://github.com/cresym/harmony/blob/main/src/cli.cpp"
click node_main "https://github.com/cresym/harmony/blob/main/src/main.cpp"
click node_gui "https://github.com/cresym/harmony/blob/main/src/ui/harmony_launcher.cpp"
click node_gui_main "https://github.com/cresym/harmony/blob/main/src/ui/harmony_ui_main.cpp"
click node_json_validation "https://github.com/cresym/harmony/blob/main/src/json/json_validator.cpp"
click node_json_params "https://github.com/cresym/harmony/blob/main/src/json/json_parameters.cpp"
click node_json_expressions "https://github.com/cresym/harmony/blob/main/src/json/json_expression.cpp"
click node_component_builder "https://github.com/cresym/harmony/blob/main/src/json/component_builder.cpp"
click node_simulation_builder "https://github.com/cresym/harmony/blob/main/src/json/simulation_builder.cpp"
click node_computation_runner "https://github.com/cresym/harmony/blob/main/src/json/computation_runner.cpp"
click node_network "https://github.com/cresym/harmony/blob/main/src/network.cpp"
click node_subnetwork "https://github.com/cresym/harmony/blob/main/src/SubNetwork.cpp"
click node_elements "https://github.com/cresym/harmony/blob/main/src/Elements/Element.cpp"
click node_converter "https://github.com/cresym/harmony/blob/main/src/Elements/Converter/MMC.cpp"
click node_renewables "https://github.com/cresym/harmony/blob/main/src/Elements/RES/PV_plant.cpp"
click node_powerflow "https://github.com/cresym/harmony/blob/main/src/Solver/OPF/Powerflow_solver.cpp"
click node_state_space "https://github.com/cresym/harmony/blob/main/src/Solver/State_Space_Model/State_Space_Model.cpp"
click node_stability "https://github.com/cresym/harmony/blob/main/src/Solver/Stability_Estimate/Stability_estimate.cpp"
click node_certificates "https://github.com/cresym/harmony/blob/main/src/Solver/Certificate/Stability_certificate.cpp"
click node_visualization "https://github.com/cresym/harmony/blob/main/src/Solver/Helper_Functions/Visualization.cpp"
click node_control "https://github.com/cresym/harmony/blob/main/src/Control/Control_block.cpp"
click node_controllers "https://github.com/cresym/harmony/blob/main/src/Control/Controller/ProportionalIntegral_controller.cpp"

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_cli,node_main,node_gui,node_gui_main,node_cli_user,node_gui_user toneBlue
class node_json_validation,node_json_params,node_json_expressions,node_component_builder,node_simulation_builder,node_computation_runner toneAmber
class node_network,node_subnetwork,node_elements,node_converter,node_renewables toneMint
class node_powerflow,node_state_space,node_stability,node_certificates,node_visualization toneRose
class node_control,node_controllers,node_json_input,node_cpp_input toneIndigo
```

## Components

### User interfaces

- [CLI dispatch](https://github.com/cresym/harmony/blob/main/src/cli.cpp): `src/cli.cpp`
- [CLI entry](https://github.com/cresym/harmony/blob/main/src/main.cpp): `src/main.cpp`
- [GUI launcher](https://github.com/cresym/harmony/blob/main/src/ui/harmony_launcher.cpp): `src/ui/harmony_launcher.cpp`
- [GUI entry](https://github.com/cresym/harmony/blob/main/src/ui/harmony_ui_main.cpp): `src/ui/harmony_ui_main.cpp`

### Configuration

- [JSON validation](https://github.com/cresym/harmony/blob/main/src/json/json_validator.cpp): `src/json/json_validator.cpp`
- [JSON parameters](https://github.com/cresym/harmony/blob/main/src/json/json_parameters.cpp): `src/json/json_parameters.cpp`
- [JSON expressions](https://github.com/cresym/harmony/blob/main/src/json/json_expression.cpp): `src/json/json_expression.cpp`
- [Component factory](https://github.com/cresym/harmony/blob/main/src/json/component_builder.cpp): `src/json/component_builder.cpp`
- [Simulation builder](https://github.com/cresym/harmony/blob/main/src/json/simulation_builder.cpp): `src/json/simulation_builder.cpp`
- [Computation runner](https://github.com/cresym/harmony/blob/main/src/json/computation_runner.cpp): `src/json/computation_runner.cpp`

### Power system model

- [Network](https://github.com/cresym/harmony/blob/main/src/network.cpp): `src/network.cpp`
- [Subnetwork](https://github.com/cresym/harmony/blob/main/src/SubNetwork.cpp): `src/SubNetwork.cpp`
- [Grid elements](https://github.com/cresym/harmony/blob/main/src/Elements/Element.cpp): `src/Elements/Element.cpp`
- [Converters](https://github.com/cresym/harmony/blob/main/src/Elements/Converter/MMC.cpp): `src/Elements/Converter/MMC.cpp`
- [Renewable plants](https://github.com/cresym/harmony/blob/main/src/Elements/RES/PV_plant.cpp): `src/Elements/RES/PV_plant.cpp`

### Analysis and results

- [Power flow and OPF](https://github.com/cresym/harmony/blob/main/src/Solver/OPF/Powerflow_solver.cpp): `src/Solver/OPF/Powerflow_solver.cpp`
- [State-space model](https://github.com/cresym/harmony/blob/main/src/Solver/State_Space_Model/State_Space_Model.cpp): `src/Solver/State_Space_Model/State_Space_Model.cpp`
- [Stability estimate](https://github.com/cresym/harmony/blob/main/src/Solver/Stability_Estimate/Stability_estimate.cpp): `src/Solver/Stability_Estimate/Stability_estimate.cpp`
- [Stability certificates](https://github.com/cresym/harmony/blob/main/src/Solver/Certificate/Stability_certificate.cpp): `src/Solver/Certificate/Stability_certificate.cpp`
- [Visualization](https://github.com/cresym/harmony/blob/main/src/Solver/Helper_Functions/Visualization.cpp): `src/Solver/Helper_Functions/Visualization.cpp`

### Control dynamics

- [Control blocks](https://github.com/cresym/harmony/blob/main/src/Control/Control_block.cpp): `src/Control/Control_block.cpp`
- [P and PI controllers](https://github.com/cresym/harmony/blob/main/src/Control/Controller/ProportionalIntegral_controller.cpp): `src/Control/Controller/ProportionalIntegral_controller.cpp`

### Other components

- **CLI user**
- **GUI user**
- **JSON input**
- **C++ scripts**

## Connections

- CLI user → CLI entry: invokes
- CLI entry → CLI dispatch: parses options
- CLI dispatch → Computation runner: runs JSON simulation
- JSON input → Computation runner: configures run
- GUI user → GUI launcher: launches
- GUI launcher → GUI entry: starts interface
- C++ scripts → CLI dispatch: selects example
- JSON validation → JSON input: validates
- JSON parameters → JSON input: resolves parameters
- JSON expressions → JSON input: parses expressions
- Component factory → Grid elements: constructs elements
- Component factory → Converters: constructs converters
- Component factory → Renewable plants: constructs plants
- Simulation builder → Network: builds simulation network
- Network → Subnetwork: organizes network
- Network → Power flow and OPF: supplies network data
- Network → State-space model: supplies system model
- State-space model → Stability estimate: supports stability analysis
- Stability estimate → Stability certificates: informs certification
- Power flow and OPF → Visualization: provides results
- Converters → Control blocks: uses control dynamics
- Control blocks → P and PI controllers: specialized by