CommonPower
===========
Introduction
-------------
CommonPower provides a flexible framework to model power systems, interface to single-agent and multi-agent RL controllers,
and maintain safety based on a symbolic representation of the system equations.
Alternatively, the system model can directly be used to solve a given use case via the built-in model predictive controller.
Following a modular design philosophy, CommonPower is an easily extendable tool for the development and benchmarking
of RL controllers in the context of smart grids. The initial focus is on energy management and economic dispatch.
Additionally, CommonPower readily allows the influence of forecast quality to be studied.
The primary features are
- an object-oriented approach to modelling power system entities,
- a Pyomo-based symbolic math representation of entities to obtain all relevant system equations in the background,
- interfaces for single/multi-agent reinforcement learning and optimal control,
- a flexible interface to make use of diverse data sources and forecasting models.
Documentation
--------------
Our documentation is available on [ReadtheDocs](https://commonpower.readthedocs.io).
Example
--------
The following code is an illustrative example of a multi-agent scenario with three housholds and heterogeneous controllers.
Two of the households are controlled by a multi-agent RL algorithm, the third by a model predictive controller.
This example covers the system creation, training, and deployment.
```python
from commonpower.core import System
from commonpower.models.components import Load, RenewableGen, ESSLinear
from commonpower.models.busses import RTPricedBus, ExternalGrid
from commonpower.models.powerflow import PowerBalanceModel
from commonpower.data_forecasting import CSVDataSource, DataProvider, PersistenceForecaster, PerfectKnowledgeForecaster
from commonpower.control.runners import DeploymentRunner, MAPPOTrainer
from commonpower.control.controllers import OptimalController, RLControllerMA
from commonpower.control.wrappers import MultiAgentWrapper
from commonpower.control.safety_layer.safety_layers import ActionProjectionSafetyLayer
pv_data = CSVDataSource("<path_to_data>")
load_data = CSVDataSource("<path_to_data>")
price_data = CSVDataSource("<path_to_data>")
# create 3 identical households
households = []
for i in range(3):
household = RTPricedBus(f"household{i}").add_data_provider(DataProvider(price_data, PersistenceForecaster()))
household.add_node(
RenewableGen(f"pv{i}").add_data_provider(DataProvider(pv_data, PersistenceForecaster()))
).add_node(
Load(f"load{i}").add_data_provider(DataProvider(load_data, PerfectKnowledgeForecaster()))
).add_node(
ESSLinear(f"ess{i}", {
"p": [-1.5, 1.5], # active power limits in kW
"q": [0.0, 0.0], # reactive power limits in kW
"soc": [0.2, 9], # state of charge limits in kWh
"soc_init": 5.0 # initial state of charge
})
)
households.append(household)
substation = ExternalGrid("substation")
sys = System(PowerBalanceModel()).add_node(households[0]).add_node(households[1]).add_node(households[2]).add_node(substation)
mpc_controller = OptimalController("mpc1").add_entity(households[0])
rl_agent1 = RLControllerMA("agent1", safety_layer=ActionProjectionSafetyLayer()).add_entity(households[1])
rl_agent2 = RLControllerMA("agent2", safety_layer=ActionProjectionSafetyLayer()).add_entity(households[2])
# traning
train_runner = MAPPOTrainer(sys, alg_config={"<your>": "<config>"}, wrapper=MultiAgentWrapper)
train_runner.run()
# deployment
deploy_runner = DeploymentRunner(sys, wrapper=MultiAgentWrapper)
deploy_runner.run()
```
For more examples, have a look at our [Tutorials](https://commonpower.readthedocs.io/en/latest/tutorials.html).
Reference
----------
CommonPower was developed and is maintained by the Cyber-Physical Systems Group at the Chair for Robotics and Embedded Systems at Technical University of Munich.
If you use CommonPower, please cite the corresponding [tool paper](https://arxiv.org/abs/2406.03231) as
```
@misc{eichelbeck2024commonpower,
title={CommonPower: Supercharging Machine Learning for Smart Grids},
author={Michael Eichelbeck and Hannah Markgraf and Matthias Althoff},
year={2024},
eprint={2406.03231},
archivePrefix={arXiv},
}
```
Installing CommonPower
----------------------
You will need [Python](https://www.python.org/downloads/) >= 3.8 installed on your system.
We recommend using a [virtual environment](https://docs.python.org/3/library/venv.html) to work with CommonPower.
To create a virtual environment run
```bash
python -m venv </path/to/new/virtual/environment>
```
You can then activate the virtual environment.
Linux:
```bash
source <path/to/venv>/bin/activate
```
Windows:
```bash
<path/to/venv>\Scripts\activate.bat
```
You can then proceed to install CommonPower.
For local development, install the library in editable mode:
```bash
cd <your/working/directory>
git clone "https://github.com/TUMcps/commonpower.git"
pip install -e <absolute/path/to/the/commonpower/directory>
```
Otherwise, install CommonPower via PyPI:
```bash
pip install commonpower
```
Multi-agent reinforcement learning
----------------------------------
At the moment, CommonPower supports multi-agent reinforcement learning using the IPPO/MAPPO implementation detailed in this [paper](https://arxiv.org/abs/2103.01955).
Since we had to make a few adjustments, we forked the original repository. Please clone our [fork](https://github.com/TUMcps/on-policy), cd into the repository and install the package to your virtual environment using
`pip install -e .`.
Gurobi
------
We use Gurobi as a default solver for our optimization problems. As a student, you can obtain an [academic license](https://www.gurobi.com/academia/academic-program-and-licenses/).
There are two options: If you want to run CommonPower on you laptop, you can use the named-user license. To run it on a server, you need the WLS license.
After obtaining a license, follow the Gurobi [quickstart guide](https://www.gurobi.com/documentation/quickstart.html) (choose the appropriate one for your system) to install Gurobi and retrieve your license.
If you use Gurobi on a server (with the WLS license) and receive the error that it requires two many cores, you can just [submit a ticket](https://support.gurobi.com/hc/en-us/requests/new?ticket_form_id=360000629792) with the error message and your WLS license will be upgraded.
Get started
------------
Have a look at the [Introduction Tutorial](https://commonpower.readthedocs.io/en/latest/tutorials/Introduction.html) to learn more about how CommonPower is structured.
Raw data
{
"_id": null,
"home_page": null,
"name": "commonpower",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "Power System, Smart Grid, Control, Safety, Simulation, Reinforcement learning, Mutli-Agent Systems",
"author": null,
"author_email": "Michael Eichelbeck <michael.eichelbeck@tum.de>, Hannah Markgraf <hannah.markgraf@tum.de>",
"download_url": "https://files.pythonhosted.org/packages/ea/f0/89966dcb0d389590737463f99dd7c606dad81de42d6d21c23c4ddc91de92/commonpower-0.4.0.tar.gz",
"platform": null,
"description": "CommonPower\n===========\n\nIntroduction\n-------------\n\nCommonPower provides a flexible framework to model power systems, interface to single-agent and multi-agent RL controllers,\nand maintain safety based on a symbolic representation of the system equations.\nAlternatively, the system model can directly be used to solve a given use case via the built-in model predictive controller.\nFollowing a modular design philosophy, CommonPower is an easily extendable tool for the development and benchmarking\nof RL controllers in the context of smart grids. The initial focus is on energy management and economic dispatch.\nAdditionally, CommonPower readily allows the influence of forecast quality to be studied.\nThe primary features are\n\n- an object-oriented approach to modelling power system entities,\n\n- a Pyomo-based symbolic math representation of entities to obtain all relevant system equations in the background,\n\n- interfaces for single/multi-agent reinforcement learning and optimal control,\n\n- a flexible interface to make use of diverse data sources and forecasting models.\n\nDocumentation\n--------------\n\nOur documentation is available on [ReadtheDocs](https://commonpower.readthedocs.io).\n\nExample\n--------\n\nThe following code is an illustrative example of a multi-agent scenario with three housholds and heterogeneous controllers.\nTwo of the households are controlled by a multi-agent RL algorithm, the third by a model predictive controller.\nThis example covers the system creation, training, and deployment.\n\n```python\nfrom commonpower.core import System\nfrom commonpower.models.components import Load, RenewableGen, ESSLinear\nfrom commonpower.models.busses import RTPricedBus, ExternalGrid\nfrom commonpower.models.powerflow import PowerBalanceModel\nfrom commonpower.data_forecasting import CSVDataSource, DataProvider, PersistenceForecaster, PerfectKnowledgeForecaster\nfrom commonpower.control.runners import DeploymentRunner, MAPPOTrainer\nfrom commonpower.control.controllers import OptimalController, RLControllerMA\nfrom commonpower.control.wrappers import MultiAgentWrapper\nfrom commonpower.control.safety_layer.safety_layers import ActionProjectionSafetyLayer\n\npv_data = CSVDataSource(\"<path_to_data>\")\nload_data = CSVDataSource(\"<path_to_data>\")\nprice_data = CSVDataSource(\"<path_to_data>\")\n\n# create 3 identical households\nhouseholds = []\nfor i in range(3):\n household = RTPricedBus(f\"household{i}\").add_data_provider(DataProvider(price_data, PersistenceForecaster()))\n household.add_node(\n RenewableGen(f\"pv{i}\").add_data_provider(DataProvider(pv_data, PersistenceForecaster()))\n ).add_node(\n Load(f\"load{i}\").add_data_provider(DataProvider(load_data, PerfectKnowledgeForecaster()))\n ).add_node(\n ESSLinear(f\"ess{i}\", {\n \"p\": [-1.5, 1.5], # active power limits in kW\n \"q\": [0.0, 0.0], # reactive power limits in kW\n \"soc\": [0.2, 9], # state of charge limits in kWh\n \"soc_init\": 5.0 # initial state of charge\n })\n )\n households.append(household)\n\nsubstation = ExternalGrid(\"substation\")\n\nsys = System(PowerBalanceModel()).add_node(households[0]).add_node(households[1]).add_node(households[2]).add_node(substation)\n\nmpc_controller = OptimalController(\"mpc1\").add_entity(households[0])\nrl_agent1 = RLControllerMA(\"agent1\", safety_layer=ActionProjectionSafetyLayer()).add_entity(households[1])\nrl_agent2 = RLControllerMA(\"agent2\", safety_layer=ActionProjectionSafetyLayer()).add_entity(households[2])\n\n# traning\ntrain_runner = MAPPOTrainer(sys, alg_config={\"<your>\": \"<config>\"}, wrapper=MultiAgentWrapper)\ntrain_runner.run()\n\n# deployment\ndeploy_runner = DeploymentRunner(sys, wrapper=MultiAgentWrapper)\ndeploy_runner.run()\n```\n\nFor more examples, have a look at our [Tutorials](https://commonpower.readthedocs.io/en/latest/tutorials.html).\n\n\nReference\n----------\n\nCommonPower was developed and is maintained by the Cyber-Physical Systems Group at the Chair for Robotics and Embedded Systems at Technical University of Munich.\n\nIf you use CommonPower, please cite the corresponding [tool paper](https://arxiv.org/abs/2406.03231) as \n```\n@misc{eichelbeck2024commonpower,\n title={CommonPower: Supercharging Machine Learning for Smart Grids}, \n author={Michael Eichelbeck and Hannah Markgraf and Matthias Althoff},\n year={2024},\n eprint={2406.03231},\n archivePrefix={arXiv},\n}\n```\n\nInstalling CommonPower\n----------------------\n\nYou will need [Python](https://www.python.org/downloads/) >= 3.8 installed on your system.\n\nWe recommend using a [virtual environment](https://docs.python.org/3/library/venv.html) to work with CommonPower. \nTo create a virtual environment run\n```bash\npython -m venv </path/to/new/virtual/environment>\n```\nYou can then activate the virtual environment.\n\nLinux: \n```bash\nsource <path/to/venv>/bin/activate\n```\n\nWindows:\n```bash\n<path/to/venv>\\Scripts\\activate.bat\n```\n\nYou can then proceed to install CommonPower.\nFor local development, install the library in editable mode:\n```bash\ncd <your/working/directory>\ngit clone \"https://github.com/TUMcps/commonpower.git\"\npip install -e <absolute/path/to/the/commonpower/directory>\n```\n\nOtherwise, install CommonPower via PyPI:\n```bash\npip install commonpower\n```\n\nMulti-agent reinforcement learning\n----------------------------------\n\nAt the moment, CommonPower supports multi-agent reinforcement learning using the IPPO/MAPPO implementation detailed in this [paper](https://arxiv.org/abs/2103.01955). \nSince we had to make a few adjustments, we forked the original repository. Please clone our [fork](https://github.com/TUMcps/on-policy), cd into the repository and install the package to your virtual environment using\n`pip install -e .`.\n\nGurobi\n------\n\nWe use Gurobi as a default solver for our optimization problems. As a student, you can obtain an [academic license](https://www.gurobi.com/academia/academic-program-and-licenses/). \nThere are two options: If you want to run CommonPower on you laptop, you can use the named-user license. To run it on a server, you need the WLS license.\nAfter obtaining a license, follow the Gurobi [quickstart guide](https://www.gurobi.com/documentation/quickstart.html) (choose the appropriate one for your system) to install Gurobi and retrieve your license. \nIf you use Gurobi on a server (with the WLS license) and receive the error that it requires two many cores, you can just [submit a ticket](https://support.gurobi.com/hc/en-us/requests/new?ticket_form_id=360000629792) with the error message and your WLS license will be upgraded.\n\nGet started\n------------\n\nHave a look at the [Introduction Tutorial](https://commonpower.readthedocs.io/en/latest/tutorials/Introduction.html) to learn more about how CommonPower is structured.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A package for the exploration of safe single/multi-agent reinforcement learning in smart grids.",
"version": "0.4.0",
"project_urls": {
"Documentation": "https://commonpower.readthedocs.io",
"Homepage": "https://github.com/TUMcps/commonpower"
},
"split_keywords": [
"power system",
" smart grid",
" control",
" safety",
" simulation",
" reinforcement learning",
" mutli-agent systems"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4d54602f3cdfe436caf099172aac513973741710eb0b65fde65e73431522fb6d",
"md5": "def82ab738c0a3bf0d8a033b88446ddf",
"sha256": "4c9d6a09470666ac9cc75fc0d372a8110e1f7c72d0fc84bd21a1b0496bcc373b"
},
"downloads": -1,
"filename": "commonpower-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "def82ab738c0a3bf0d8a033b88446ddf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 132836,
"upload_time": "2024-11-26T12:22:40",
"upload_time_iso_8601": "2024-11-26T12:22:40.834855Z",
"url": "https://files.pythonhosted.org/packages/4d/54/602f3cdfe436caf099172aac513973741710eb0b65fde65e73431522fb6d/commonpower-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "eaf089966dcb0d389590737463f99dd7c606dad81de42d6d21c23c4ddc91de92",
"md5": "83e7e052729afd60e56b40a5b2ee2aab",
"sha256": "873a5ed5eb587e86d8aa34e051f76ecdedd91c10e8ce052c15a8446fc54ad0fc"
},
"downloads": -1,
"filename": "commonpower-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "83e7e052729afd60e56b40a5b2ee2aab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 122065,
"upload_time": "2024-11-26T12:22:42",
"upload_time_iso_8601": "2024-11-26T12:22:42.412003Z",
"url": "https://files.pythonhosted.org/packages/ea/f0/89966dcb0d389590737463f99dd7c606dad81de42d6d21c23c4ddc91de92/commonpower-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-26 12:22:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TUMcps",
"github_project": "commonpower",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "commonpower"
}
JSON
