# tumcps/commonpower architecture

> Architecture diagram of the GitHub repository tumcps/commonpower, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tumcps/commonpower
- Repository: https://github.com/tumcps/commonpower

## Overview

##### Project type and purpose
- CommonPower is a Python-based framework (library) for modeling power systems, performing forecasts, and applying single- and multi-agent control (RL and MPC). It provides an object-oriented model of grid components, a Pyomo-based symbolic equation generator, interfaces to RL algorithms, safety layers, and benchmarking tools.

##### Main architectural layers and components

A. Data & External Services
- File-based Data Sources (CSVDataSource, other DataProviders)
- Forecasting Engines (PersistenceForecaster, PerfectKnowledgeForecaster, NNForecaster)
- External DB for benchmarking (docker-compose-launched database)
- External Solver (Gurobi via Pyomo)

B. Core Modeling Layer
- commonpower.models
- Entities: Busses (RTPricedBus, ExternalGrid)
- Components: Load, RenewableGen, ESSLinear, Lines, Buses, PowerFlow
- commonpower.core.System
- Assembles entities into a unified Pyomo model (PowerBalanceModel)
- Pyomo Symbolic Math
- Translates object graph → system equations → solver interface

C. Forecasting Layer
- commonpower.data_forecasting
- DataGenerators, DataSources
- Forecasters (base, nn_forecasting submodule)
- DataProvider: binds DataSource + Forecaster → time-series forecast

D. Control Layer
- Controllers
- OptimalController (MPC / Pyomo-based)
- RLControllerMA (IPPO/MAPPO wrapper)
- Safety Layer
- ActionProjectionSafetyLayer, penalty callbacks
- Wrappers
- MultiAgentWrapper
- Runners
- MAPPOTrainer (training loop)
- DeploymentRunner (execution loop)
- Logging & Callbacks (commonpower.control.logging_utils)

E. Benchmarking & Extensions
- Benchmark scripts (commonpower.benchmark.benchmark.py)
- benchmark/database/docker-compose.yml
- commonpower.extensions (cost_allocation, network_import, factories)

F. Application / User Code
- Example scripts (in docs/tutorials and user’s code)
- Jupyter notebooks for tutorials

##### Relationships and data flows
1. User/Application calls core.System, adds Entities → builds Pyomo model
2. DataProvider fetches raw data from DataSources → Forecasters produce forecasts
3. On each timestep:
- Runners invoke Controller (MPC or RL) → Controller queries forecast → produces actions
- Actions fed to System → System simulates next state via the Pyomo model + solver
- Safety Layer intercepts actions, enforces constraints
- Logging Utils capture metrics/callbacks
4. Benchmark harness triggers sequences of runs, stores results in external DB

##### Architectural patterns and design principles
- Layered architecture (separation of concerns: data, modeling, control, execution)
- Dependency injection via DataProvider and configuration modules
- Plugin / extension points (commonpower.extensions, forecasting backends)
- MVC-like pattern: Model = power system, Controller = RL/MPC, View = logs & metrics

##### Technologies and frameworks to annotate
- Python 3.8+
- Pyomo (symbolic math & solver interface)
- Gurobi (default optimization solver)
- IPPO/MAPPO (multi-agent RL via forked on-policy repo)
- Docker Compose (benchmark database)

##### Essential elements
- Clear, distinct labels for each of the five layers and their constituent modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & External Services Layer
    subgraph "Data & External Services"
        classDef data fill:#E0F7FA,stroke:#00838F,color:#004D40
        DS["CSVDataSource & DataProvider Interfaces"]:::data
        DG["Data Generators"]:::data
        BF["Base Forecasters"]:::data
        NNFN["NN Forecasting Engine"]:::data
        DBX[(Benchmark External DB)]:::data
        SV[(Gurobi Solver)]:::data
    end

    %% Core Modeling Layer
    subgraph "Core Modeling"
        classDef core fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20
        BUSES["Buses Entities"]:::core
        COMPS["Components (Load, Gen, ESS)"]:::core
        LINES["Lines Model"]:::core
        PFL["Power Flow"]:::core
        MIP["Pyomo Symbolic Math / MIP Builder"]:::core
        SYS["System Assembly (PowerBalanceModel)"]:::core
    end

    %% Forecasting Layer
    subgraph "Forecasting"
        classDef forecast fill:#FFFDE7,stroke:#F9A825,color:#F57F17
        DP["DataProvider"]:::forecast
    end

    %% Control Layer
    subgraph "Control"
        classDef control fill:#FFF3E0,stroke:#EF6C00,color:#E65100
        MPC["OptimalController (MPC)"]:::control
        RL["RLControllerMA"]:::control
        SAFE["Safety Layer"]:::control
        WRAP["MultiAgentWrapper"]:::control
        RUN["Runners (MAPPOTrainer, DeploymentRunner)"]:::control
        LOG["Logging & Callbacks"]:::control
    end

    %% Benchmarking & Extensions Layer
    subgraph "Benchmark & Extensions"
        classDef bench fill:#ECEFF1,stroke:#546E7A,color:#263238
        BM["Benchmark Script"]:::bench
        EXT1["Cost Allocation Ext"]:::bench
        EXT2["Network Import Ext"]:::bench
        EXT3["Factories Ext"]:::bench
    end

    %% Application / User Code
    subgraph "Application / User Code"
        classDef app fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C
        TUT["Tutorials / Example Notebooks"]:::app
    end

    %% Data & Forecasting Flow
    DS -->|"raw data"| BF
    BF -->|"forecasts"| DP
    NNFN -->|"nn forecasts"| DP
    DG -->|"generated data"| DP

    %% Forecasting to Control & Core
    DP -->|"forecast time-series"| MPC
    DP -->|"forecast time-series"| RL

    %% Control Flow
    MPC -->|"actions"| SAFE
    RL -->|"actions"| SAFE
    SAFE -->|"safe actions"| SYS

    %% Core Modeling Flow
    BUSES --> MIP
    COMPS --> MIP
    LINES --> MIP
    PFL --> MIP
    MIP --> SYS
    SYS -->|"Pyomo model"| SV

    %% Execution Loop
    RUN -->|"invoke controller"| MPC
    RUN -->|"invoke controller"| RL
    RUN -->|"update system"| SYS
    SYS -->|"state update"| RUN

    %% Logging
    MPC --> LOG
    RL --> LOG
    SAFE --> LOG
    RUN --> LOG

    %% Benchmarking
    BM --> DBX
    RUN --> BM

    %% Extensions
    EXT1 --> SYS
    EXT2 --> SYS
    EXT3 --> SYS

    %% Application Code
    TUT --> DP
    TUT --> SYS
    TUT --> MPC
    TUT --> RL

    %% Click Events
    click DS "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/data_forecasting/data_sources.py"
    click DG "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/data_forecasting/data_generators.py"
    click BF "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/data_forecasting/forecasters.py"
    click NNFN "https://github.com/tumcps/commonpower/tree/PUBLIC/commonpower/data_forecasting/nn_forecasting/"
    click DBX "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/benchmark/database/docker-compose.yaml"
    click SV "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/utils/default_solver.py"
    click SYS "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/core.py"
    click MIP "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/modeling/mip_builder.py"
    click BUSES "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/models/buses.py"
    click COMPS "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/models/components.py"
    click LINES "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/models/lines.py"
    click PFL "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/models/powerflow.py"
    click MPC "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/control/controllers.py"
    click RL "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/control/controllers.py"
    click SAFE "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/control/safety_layer/safety_layers.py"
    click WRAP "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/control/wrappers.py"
    click RUN "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/control/runners.py"
    click LOG "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/control/logging_utils/loggers.py"
    click BM "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/benchmark/benchmark.py"
    click EXT1 "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/extensions/cost_allocation.py"
    click EXT2 "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/extensions/network_import.py"
    click EXT3 "https://github.com/tumcps/commonpower/blob/PUBLIC/commonpower/extensions/factories.py"
    click TUT "https://github.com/tumcps/commonpower/tree/PUBLIC/docs/source/tutorials/"

    %% Styles
    class DS,DG,BF,NNFN,DBX,SV data
    class BUSES,COMPS,LINES,PFL,MIP,SYS core
    class DP forecast
    class MPC,RL,SAFE,WRAP,RUN,LOG control
    class BM,EXT1,EXT2,EXT3 bench
    class TUT app
```
