# Vessim
[![PyPI version](https://img.shields.io/pypi/v/vessim.svg?color=52c72b)](https://pypi.org/project/vessim/)
![Tests](https://github.com/dos-group/vessim/actions/workflows/linting-and-testing.yml/badge.svg)
[![License](https://img.shields.io/pypi/l/vessim.svg)](https://pypi.org/project/vessim/)
[![Supported versions](https://img.shields.io/pypi/pyversions/vessim.svg)](https://pypi.org/project/vessim/)
Vessim is a versatile **co-simulation testbed for carbon-aware applications and systems** which connects domain-specific simulators for renewable power generation and energy storage with real software and hardware.
It simulates energy systems that interact with real or simulated computing systems for:
- **Carbon-aware applications**: Simulated microgrids offer real-time visibility and control via APIs, enabling the development of novel applications that interact with their energy system.
- **Energy system composition**: Examine how the integration of solar panels, wind energy, or batteries would affect the energy mix of your datacenters.
- **Digital Twins**: Predict future system states in carbon-aware datacenters, aid decision-making, and assess risks during extreme events like power outages.
- **Quality Assurance**: Apply Vessim in continuous integrating testing or use it to validate software roll-outs in a controlled environment.
Vessim can simulate large numbers of microgrids in parallel, comes with ready-to-use datasets, can execute simulated experiments faster than real-time, and is easily extendable with new simulators of any platform through [Mosaik](https://mosaik.offis.de)'s TCP interface.
**Check out the official [documentation](https://vessim.readthedocs.io/en/latest/)!**
## Example scenario
The scenario below simulates a microgrid consisting of a simulated computing system (which consistently draws 400W), a single producer (a solar power plant who's production is modelled based on a dataset provided by [Solcast](https://solcast.com/)), and a battery. The *Monitor* periodically stores the energy system state.
```python
from vessim.actor import ComputingSystem, Generator
from vessim.controller import Monitor
from vessim.cosim import Environment
from vessim.power_meter import MockPowerMeter
from vessim.signal import HistoricalSignal
from vessim.storage import SimpleBattery
environment = Environment(sim_start="15-06-2022")
monitor = Monitor()
environment.add_microgrid(
actors=[
ComputingSystem(power_meters=[MockPowerMeter(p=400)]),
Generator(signal=HistoricalSignal.from_dataset("solcast2022_global"), column="Berlin"),
],
controllers=[monitor],
storage=SimpleBattery(capacity=100),
step_size=60,
)
environment.run(until=24 * 3600) # 24h
monitor.to_csv("result.csv")
```
## Installation
You can install the [latest release](https://pypi.org/project/vessim/) of Vessim
via [pip](https://pip.pypa.io/en/stable/quickstart/):
```
pip install vessim
```
If you require software-in-the-loop (SiL) capabilities, you should additionally install the `sil` extension:
```
pip install vessim[sil]
```
For complex scenarios that involve custom co-simulation actors we recommend cloning and editing this depository directly.
## Work in progress
Our team at the [Distributed and Operating Systems](https://distributedsystems.berlin/) group at TU Berlin is actively working to improve Vessim.
We are currently working on the following aspects and features:
- **Software-in-the-loop API**: We will soon release a new API for SiL simulations with new examples and better documentation.
- **System Advisor Model (SAM)**: We are working on integrating NREL's [SAM](https://sam.nrel.gov/) as a subsystem in Vessim, allowing for better simulation of solar arrays, wind farms, and other types of renewable energy generators.
- **Flower**: We are working on integrating Vessim into the federated learning framework [Flower](https://flower.ai).
- **Validation**: We are working on validating the accuracy of Vessim compared to real hardware testbeds.
## Datasets
Vessim comes with ready-to-user datasets for solar irradiance and average carbon intensity provided by
<p float="left">
<img src="docs/_static/solcast_logo.png" width="120" />
<span> and </span>
<img src="docs/_static/watttime_logo.png" width="120" />
</p>
We're working on documentation on how to include custom datasets for your simulations.
## Publications
If you use Vessim in your research, please cite our paper on software-in-the-loop simulation for carbon-aware applications:
Philipp Wiesner, Marvin Steinke, Henrik Nickel, Yazan Kitana, and Odej Kao. "[Software-in-the-Loop Simulation for Developing and Testing Carbon-Aware Applications](https://doi.org/10.1002/spe.3275)" Software: Practice and Experience, 53 (12). 2023.
```
@article{wiesner2023sil,
author = {Wiesner, Philipp and Steinke, Marvin and Nickel, Henrik and Kitana, Yazan and Kao, Odej},
title = {Software-in-the-loop simulation for developing and testing carbon-aware applications},
journal = {Software: Practice and Experience},
year = {2023},
volume = {53},
number = {12},
pages = {2362-2376},
doi = {https://doi.org/10.1002/spe.3275}
}
```
Also have a look at our overall vision paper:
Philipp Wiesner, Ilja Behnke and Odej Kao. "[A Testbed for Carbon-Aware Applications and Systems](https://arxiv.org/pdf/2306.09774.pdf)" arXiv:2302.08681 [cs.DC]. 2023.
```
@misc{wiesner2023vessim,
title={A Testbed for Carbon-Aware Applications and Systems},
author={Wiesner, Philipp and Behnke, Ilja and Kao, Odej},
year={2023},
eprint={2306.09774},
archivePrefix={arXiv},
primaryClass={cs.DC}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/dos-group/vessim",
"name": "vessim",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<3.13",
"maintainer_email": "",
"keywords": "simulation,energy system,testbed,carbon-aware computing,software-in-the-loop",
"author": "Philipp Wiesner",
"author_email": "wiesner@tu-berlin.de",
"download_url": "https://files.pythonhosted.org/packages/75/e7/76b0068f486aa61504915db94bc082614a5be6bb5c625171f7c3883c1d31/vessim-0.5.1.tar.gz",
"platform": null,
"description": "# Vessim\n\n[![PyPI version](https://img.shields.io/pypi/v/vessim.svg?color=52c72b)](https://pypi.org/project/vessim/)\n![Tests](https://github.com/dos-group/vessim/actions/workflows/linting-and-testing.yml/badge.svg)\n[![License](https://img.shields.io/pypi/l/vessim.svg)](https://pypi.org/project/vessim/)\n[![Supported versions](https://img.shields.io/pypi/pyversions/vessim.svg)](https://pypi.org/project/vessim/)\n\nVessim is a versatile **co-simulation testbed for carbon-aware applications and systems** which connects domain-specific simulators for renewable power generation and energy storage with real software and hardware.\n\nIt simulates energy systems that interact with real or simulated computing systems for:\n\n- **Carbon-aware applications**: Simulated microgrids offer real-time visibility and control via APIs, enabling the development of novel applications that interact with their energy system.\n- **Energy system composition**: Examine how the integration of solar panels, wind energy, or batteries would affect the energy mix of your datacenters.\n- **Digital Twins**: Predict future system states in carbon-aware datacenters, aid decision-making, and assess risks during extreme events like power outages.\n- **Quality Assurance**: Apply Vessim in continuous integrating testing or use it to validate software roll-outs in a controlled environment.\n\nVessim can simulate large numbers of microgrids in parallel, comes with ready-to-use datasets, can execute simulated experiments faster than real-time, and is easily extendable with new simulators of any platform through [Mosaik](https://mosaik.offis.de)'s TCP interface.\n\n**Check out the official [documentation](https://vessim.readthedocs.io/en/latest/)!**\n\n## Example scenario\n\nThe scenario below simulates a microgrid consisting of a simulated computing system (which consistently draws 400W), a single producer (a solar power plant who's production is modelled based on a dataset provided by [Solcast](https://solcast.com/)), and a battery. The *Monitor* periodically stores the energy system state.\n\n```python\nfrom vessim.actor import ComputingSystem, Generator\nfrom vessim.controller import Monitor\nfrom vessim.cosim import Environment\nfrom vessim.power_meter import MockPowerMeter\nfrom vessim.signal import HistoricalSignal\nfrom vessim.storage import SimpleBattery\n\nenvironment = Environment(sim_start=\"15-06-2022\")\n\nmonitor = Monitor()\nenvironment.add_microgrid(\n actors=[\n ComputingSystem(power_meters=[MockPowerMeter(p=400)]),\n Generator(signal=HistoricalSignal.from_dataset(\"solcast2022_global\"), column=\"Berlin\"),\n ],\n controllers=[monitor],\n storage=SimpleBattery(capacity=100),\n step_size=60,\n)\n\nenvironment.run(until=24 * 3600) # 24h\nmonitor.to_csv(\"result.csv\")\n```\n\n\n## Installation\n\nYou can install the [latest release](https://pypi.org/project/vessim/) of Vessim \nvia [pip](https://pip.pypa.io/en/stable/quickstart/):\n\n```\npip install vessim\n```\n\nIf you require software-in-the-loop (SiL) capabilities, you should additionally install the `sil` extension:\n\n```\npip install vessim[sil]\n```\n\nFor complex scenarios that involve custom co-simulation actors we recommend cloning and editing this depository directly.\n\n\n## Work in progress\n\nOur team at the [Distributed and Operating Systems](https://distributedsystems.berlin/) group at TU Berlin is actively working to improve Vessim.\nWe are currently working on the following aspects and features:\n\n- **Software-in-the-loop API**: We will soon release a new API for SiL simulations with new examples and better documentation.\n- **System Advisor Model (SAM)**: We are working on integrating NREL's [SAM](https://sam.nrel.gov/) as a subsystem in Vessim, allowing for better simulation of solar arrays, wind farms, and other types of renewable energy generators.\n- **Flower**: We are working on integrating Vessim into the federated learning framework [Flower](https://flower.ai).\n- **Validation**: We are working on validating the accuracy of Vessim compared to real hardware testbeds.\n\n\n## Datasets\n\nVessim comes with ready-to-user datasets for solar irradiance and average carbon intensity provided by\n\n<p float=\"left\">\n <img src=\"docs/_static/solcast_logo.png\" width=\"120\" />\n <span> and </span>\n <img src=\"docs/_static/watttime_logo.png\" width=\"120\" />\n</p>\n\nWe're working on documentation on how to include custom datasets for your simulations.\n\n\n## Publications\n\nIf you use Vessim in your research, please cite our paper on software-in-the-loop simulation for carbon-aware applications:\n\nPhilipp Wiesner, Marvin Steinke, Henrik Nickel, Yazan Kitana, and Odej Kao. \"[Software-in-the-Loop Simulation for Developing and Testing Carbon-Aware Applications](https://doi.org/10.1002/spe.3275)\" Software: Practice and Experience, 53 (12). 2023.\n\n```\n@article{wiesner2023sil,\n author = {Wiesner, Philipp and Steinke, Marvin and Nickel, Henrik and Kitana, Yazan and Kao, Odej},\n title = {Software-in-the-loop simulation for developing and testing carbon-aware applications},\n journal = {Software: Practice and Experience},\n year = {2023},\n volume = {53},\n number = {12},\n pages = {2362-2376},\n doi = {https://doi.org/10.1002/spe.3275}\n}\n```\n\nAlso have a look at our overall vision paper:\n\nPhilipp Wiesner, Ilja Behnke and Odej Kao. \"[A Testbed for Carbon-Aware Applications and Systems](https://arxiv.org/pdf/2306.09774.pdf)\" arXiv:2302.08681 [cs.DC]. 2023.\n\n```\n@misc{wiesner2023vessim,\n title={A Testbed for Carbon-Aware Applications and Systems}, \n author={Wiesner, Philipp and Behnke, Ilja and Kao, Odej},\n year={2023},\n eprint={2306.09774},\n archivePrefix={arXiv},\n primaryClass={cs.DC}\n}\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simulator for carbon-aware applications and systems.",
"version": "0.5.1",
"project_urls": {
"Bug Reports": "https://github.com/dos-group/vessim/issues",
"Documentation": "https://github.com/dos-group/vessim",
"Homepage": "https://github.com/dos-group/vessim",
"Repository": "https://github.com/dos-group/vessim"
},
"split_keywords": [
"simulation",
"energy system",
"testbed",
"carbon-aware computing",
"software-in-the-loop"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2414fca7097d75c493d189b346bd49f84b9401811087cec71adc91228347a2df",
"md5": "67613c02705344114517fa05fd9df7c4",
"sha256": "17b2b2826b34622271ea4337671811c0d318ad271b9c5e9d3c6c2823024d256b"
},
"downloads": -1,
"filename": "vessim-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "67613c02705344114517fa05fd9df7c4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<3.13",
"size": 21962,
"upload_time": "2024-03-14T11:46:29",
"upload_time_iso_8601": "2024-03-14T11:46:29.124256Z",
"url": "https://files.pythonhosted.org/packages/24/14/fca7097d75c493d189b346bd49f84b9401811087cec71adc91228347a2df/vessim-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "75e776b0068f486aa61504915db94bc082614a5be6bb5c625171f7c3883c1d31",
"md5": "1543b6d30621bad7299627577a8e6e6a",
"sha256": "8f2e96c0b779667fbed0e8e0da092acc311b614731365003b7cc977811708883"
},
"downloads": -1,
"filename": "vessim-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "1543b6d30621bad7299627577a8e6e6a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<3.13",
"size": 21292,
"upload_time": "2024-03-14T11:46:31",
"upload_time_iso_8601": "2024-03-14T11:46:31.256559Z",
"url": "https://files.pythonhosted.org/packages/75/e7/76b0068f486aa61504915db94bc082614a5be6bb5c625171f7c3883c1d31/vessim-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-14 11:46:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dos-group",
"github_project": "vessim",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "vessim"
}