How tumcps/commonpower works
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