# Vessim
[](https://pypi.org/project/vessim/)
[](https://pypi.org/project/vessim/)
[](https://pypi.org/project/vessim/)
Vessim is a **co-simulation testbed for carbon-aware systems** that allows you to simulate how your computing systems interact with local renewable energy sources, battery storage, and the public grid.
It connects domain-specific simulators for power generation and energy storage with **real software and hardware**.
## What can I do with Vessim?
Vessim helps you to understand and optimize how your (distributed) computing system interacts with (distributed) renewable energy sources and battery storage.
- **Carbon-aware applications**: Develop applications that automatically reduce their energy consumption when the grid is powered by fossil fuels, and increase activity when renewable energy is abundant.
- **Energy system composition**: Experiment with adding solar panels, wind turbines, or batteries to see how they would affect your energy costs and carbon emissions.
- **Plan for outages and extreme events**: Simulate power outages or renewable energy fluctuations to understand risks and test backup strategies.
- **Quality assurance**: Apply Vessim in continuous integrating testing to validate software roll-outs in a controlled environment.
Vessim can run simulations faster than real-time, includes historical datasets for realistic scenarios, and can simulate multiple microgrids in parallel.
You can test scenarios using historical data or connect real applications and hardware to simulated energy systems.
**Check out the official [documentation](https://vessim.readthedocs.io/en/latest/)!**
## Simple scenario
The scenario below simulates a microgrid consisting of a simulated computing system (which consistently draws 700W),
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 in a CSV file.
```python
import vessim as vs
environment = vs.Environment(sim_start="2022-06-15", step_size=300) # 5 minute step size
microgrid = environment.add_microgrid(
name="datacenter",
actors=[
vs.Actor(name="server", signal=vs.StaticSignal(value=-700)), # negative = consumes power
vs.Actor(name="solar_panel", signal=vs.Trace.load("solcast2022_global", column="Berlin", params={"scale": 5000})), # 5kW maximum
],
storage=vs.SimpleBattery(capacity=100),
)
# Write results to CSV
monitor = vs.Monitor([microgrid], outfile="./results.csv")
environment.add_controller(monitor)
environment.run(until=24 * 3600) # 24h simulated time
```
## Software-in-the-loop scenario
Vessim can simulate the energy systems of real applications and hardware.
The following example
1. pulls energy consumption data from a Prometheus monitoring system
2. exposes the simulated microgrid via a REST API, including the current marginal carbon intensity of the public grid (provided by [Watttime](https://watttime.org/)).
```python
import vessim as vs
environment = vs.Environment(sim_start="2022-06-15", step_size=5) # 5 second step size
microgrid = environment.add_microgrid(
name=f"gpu_cluster_in_berlin",
actors=[
vs.Actor(name="gpu_cluster", signal=vs.PrometheusSignal(
prometheus_url="http://localhost:30826/prometheus",
query=f"sum(DCGM_FI_DEV_POWER_USAGE)", # sum of all GPUs' power consumption
username="username",
password="xxxxxxxxxx"
))
],
grid_signals={"mci_index": vs.WatttimeSignal(
username="username",
password="xxxxxxxxxx",
location=(52.5200, 13.4050), # Berlin coordinates
)},
)
rest_api = vs.Api([microgrid], export_prometheus=True)
environment.add_controller(rest_api)
environment.run(until=24 * 3600, rt_factor=1) # 24h in real-time mode
```
## 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]
```
## 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:
- **Vessim X Exalsius**: We are working on integrating Vessim into [Exalsius](https://www.exalsius.ai/)' GPU provisioning and scheduling.
- **Vessim X Flower**: We are working on integrating Vessim into the federated learning framework [Flower](https://flower.ai).
- **Vessim X Vidur**: We are working on integrating Vessim into the LLM simulator [Vidur](https://github.com/microsoft/vidur).
- **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.
- **Battery degradation**: We are working on integrating NREL's [BLAST-Lite](https://github.com/NREL/BLAST-Lite) for modeling battery lifetime and degradation
- **Calibration**: We are working on a methodology for calibrating Vessim simulations on 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:
- Philipp Wiesner, Ilja Behnke, Paul Kilian, Marvin Steinke, and Odej Kao. "[Vessim: A Testbed for Carbon-Aware Applications and Systems.](https://arxiv.org/pdf/2306.09774.pdf)" _3rd Workshop on Sustainable Computer Systems (HotCarbon)_. 2024.
For details in Vessim's software-in-the-loop simulation methodology, refer to our journal paper:
- 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.
For BibTeX citations and more related papers, please refer to the [documentation](https://vessim.readthedocs.io/en/latest/about.html#publications).
Raw data
{
"_id": null,
"home_page": null,
"name": "vessim",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.9",
"maintainer_email": null,
"keywords": "carbon-aware computing, energy system, simulation, software-in-the-loop, testbed",
"author": null,
"author_email": "Philipp Wiesner <wiesner@tu-berlin.de>",
"download_url": "https://files.pythonhosted.org/packages/2d/bc/3b5de38664dcd6a55af6ea5be008296e146d66cb1eda8e8dbe9649270bc8/vessim-0.12.0.tar.gz",
"platform": null,
"description": "# Vessim\n\n[](https://pypi.org/project/vessim/)\n\n[](https://pypi.org/project/vessim/)\n[](https://pypi.org/project/vessim/)\n\nVessim is a **co-simulation testbed for carbon-aware systems** that allows you to simulate how your computing systems interact with local renewable energy sources, battery storage, and the public grid.\nIt connects domain-specific simulators for power generation and energy storage with **real software and hardware**.\n\n\n## What can I do with Vessim?\n\nVessim helps you to understand and optimize how your (distributed) computing system interacts with (distributed) renewable energy sources and battery storage.\n\n- **Carbon-aware applications**: Develop applications that automatically reduce their energy consumption when the grid is powered by fossil fuels, and increase activity when renewable energy is abundant.\n- **Energy system composition**: Experiment with adding solar panels, wind turbines, or batteries to see how they would affect your energy costs and carbon emissions.\n- **Plan for outages and extreme events**: Simulate power outages or renewable energy fluctuations to understand risks and test backup strategies.\n- **Quality assurance**: Apply Vessim in continuous integrating testing to validate software roll-outs in a controlled environment.\n\nVessim can run simulations faster than real-time, includes historical datasets for realistic scenarios, and can simulate multiple microgrids in parallel. \nYou can test scenarios using historical data or connect real applications and hardware to simulated energy systems.\n\n**Check out the official [documentation](https://vessim.readthedocs.io/en/latest/)!**\n\n\n## Simple scenario\n\nThe scenario below simulates a microgrid consisting of a simulated computing system (which consistently draws 700W), \na single producer (a solar power plant who's production is modelled based on a dataset provided by [Solcast](https://solcast.com/)), and a battery. \nThe *Monitor* periodically stores the energy system state in a CSV file.\n\n```python\nimport vessim as vs\n\nenvironment = vs.Environment(sim_start=\"2022-06-15\", step_size=300) # 5 minute step size\n\nmicrogrid = environment.add_microgrid(\n name=\"datacenter\",\n actors=[\n vs.Actor(name=\"server\", signal=vs.StaticSignal(value=-700)), # negative = consumes power\n vs.Actor(name=\"solar_panel\", signal=vs.Trace.load(\"solcast2022_global\", column=\"Berlin\", params={\"scale\": 5000})), # 5kW maximum\n ],\n storage=vs.SimpleBattery(capacity=100),\n)\n\n# Write results to CSV\nmonitor = vs.Monitor([microgrid], outfile=\"./results.csv\")\nenvironment.add_controller(monitor)\n\nenvironment.run(until=24 * 3600) # 24h simulated time\n```\n\n\n## Software-in-the-loop scenario\n\nVessim can simulate the energy systems of real applications and hardware.\nThe following example \n\n1. pulls energy consumption data from a Prometheus monitoring system\n2. exposes the simulated microgrid via a REST API, including the current marginal carbon intensity of the public grid (provided by [Watttime](https://watttime.org/)).\n\n```python\nimport vessim as vs\n\nenvironment = vs.Environment(sim_start=\"2022-06-15\", step_size=5) # 5 second step size\n\nmicrogrid = environment.add_microgrid(\n name=f\"gpu_cluster_in_berlin\",\n actors=[\n vs.Actor(name=\"gpu_cluster\", signal=vs.PrometheusSignal(\n prometheus_url=\"http://localhost:30826/prometheus\",\n query=f\"sum(DCGM_FI_DEV_POWER_USAGE)\", # sum of all GPUs' power consumption\n username=\"username\",\n password=\"xxxxxxxxxx\"\n ))\n ],\n grid_signals={\"mci_index\": vs.WatttimeSignal(\n username=\"username\",\n password=\"xxxxxxxxxx\",\n location=(52.5200, 13.4050), # Berlin coordinates\n )},\n)\n\nrest_api = vs.Api([microgrid], export_prometheus=True)\nenvironment.add_controller(rest_api)\n\nenvironment.run(until=24 * 3600, rt_factor=1) # 24h in real-time mode\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\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- **Vessim X Exalsius**: We are working on integrating Vessim into [Exalsius](https://www.exalsius.ai/)' GPU provisioning and scheduling.\n- **Vessim X Flower**: We are working on integrating Vessim into the federated learning framework [Flower](https://flower.ai).\n- **Vessim X Vidur**: We are working on integrating Vessim into the LLM simulator [Vidur](https://github.com/microsoft/vidur).\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- **Battery degradation**: We are working on integrating NREL's [BLAST-Lite](https://github.com/NREL/BLAST-Lite) for modeling battery lifetime and degradation\n- **Calibration**: We are working on a methodology for calibrating Vessim simulations on 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:\n\n- Philipp Wiesner, Ilja Behnke, Paul Kilian, Marvin Steinke, and Odej Kao. \"[Vessim: A Testbed for Carbon-Aware Applications and Systems.](https://arxiv.org/pdf/2306.09774.pdf)\" _3rd Workshop on Sustainable Computer Systems (HotCarbon)_. 2024.\n\nFor details in Vessim's software-in-the-loop simulation methodology, refer to our journal paper:\n\n- 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.\n\nFor BibTeX citations and more related papers, please refer to the [documentation](https://vessim.readthedocs.io/en/latest/about.html#publications).\n",
"bugtrack_url": null,
"license": null,
"summary": "A simulator for carbon-aware applications and systems.",
"version": "0.12.0",
"project_urls": null,
"split_keywords": [
"carbon-aware computing",
" energy system",
" simulation",
" software-in-the-loop",
" testbed"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cf9ea5c389beab51c5528562fce487b75c23094e860661a4fd423aaa450927a4",
"md5": "452be8471e90ec59836e40db42170185",
"sha256": "4a84e85588f1c74268c3b717fb204aab5faea8ec5db218eace9f427af594fe57"
},
"downloads": -1,
"filename": "vessim-0.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "452be8471e90ec59836e40db42170185",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.9",
"size": 35127,
"upload_time": "2025-07-31T15:47:32",
"upload_time_iso_8601": "2025-07-31T15:47:32.611150Z",
"url": "https://files.pythonhosted.org/packages/cf/9e/a5c389beab51c5528562fce487b75c23094e860661a4fd423aaa450927a4/vessim-0.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2dbc3b5de38664dcd6a55af6ea5be008296e146d66cb1eda8e8dbe9649270bc8",
"md5": "5b7fb98244a9dc02aa9b23cb516dd157",
"sha256": "e030a0ac7f4b3d80c32ef663fccaae6e8a1382aae483c8c4fbeeffb52612e0e7"
},
"downloads": -1,
"filename": "vessim-0.12.0.tar.gz",
"has_sig": false,
"md5_digest": "5b7fb98244a9dc02aa9b23cb516dd157",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.9",
"size": 10439822,
"upload_time": "2025-07-31T15:47:34",
"upload_time_iso_8601": "2025-07-31T15:47:34.702001Z",
"url": "https://files.pythonhosted.org/packages/2d/bc/3b5de38664dcd6a55af6ea5be008296e146d66cb1eda8e8dbe9649270bc8/vessim-0.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 15:47:34",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "vessim"
}
JSON