Metadata-Version: 2.5
Name: vessim
Version: 0.16.0
Summary: A co-simulation testbed for microgrids and energy-aware systems.
Author-email: Philipp Wiesner <wiesner@tu-berlin.de>
License-Expression: MIT
License-File: LICENSE
Keywords: carbon-aware computing,demand response,energy management,energy system,microgrid,simulation,software-in-the-loop,testbed
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Testing
Requires-Python: <3.16,>=3.9
Requires-Dist: loguru>=0.6.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pandas>=2.0.0
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pandas-stubs; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: types-psutil; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material; extra == 'docs'
Requires-Dist: mkdocstrings[python]; extra == 'docs'
Requires-Dist: setuptools; extra == 'docs'
Provides-Extra: live
Requires-Dist: fastapi>=0.104.0; extra == 'live'
Requires-Dist: prometheus-client>0.22.0; extra == 'live'
Requires-Dist: pydantic>=2.14.0; (python_version >= '3.15') and extra == 'live'
Requires-Dist: requests>=2.26.0; extra == 'live'
Requires-Dist: uvicorn>=0.23.0; extra == 'live'
Provides-Extra: mosaik
Requires-Dist: docopt-ng>=0.9.0; extra == 'mosaik'
Requires-Dist: mosaik-api-v3<4,>=3.0.4; extra == 'mosaik'
Requires-Dist: mosaik<4,>=3.6.0; extra == 'mosaik'
Description-Content-Type: text/markdown

<p align="center">
    <img alt="Vessim Logo" src="docs/assets/logo.png" width="250" />
</p>

Vessim is a Python library for simulating datacenter energy systems.

Vessim models the interaction between datacenter demand and energy infrastructure, helping you understand how design and control decisions affect cost, carbon emissions, and resilience.

[Documentation](https://vessim.readthedocs.io/en/latest/) · [Getting started](https://vessim.readthedocs.io/en/latest/getting_started/) · [Explore example results](https://vessim.readthedocs.io/en/latest/vessim_viewer/)

- **Simulation studies:** Compare infrastructure and control strategies across demand, weather, and operating scenarios.
  Explore design choices through parameter sweeps, optimization, or probabilistic simulations.
- **Live modeling:** Connect real applications to a simulated energy system through REST APIs.
  Test how a scheduler or controller responds to changing power availability.
- **Digital twins:** Model an energy system alongside the real installation using live measurements.
  Explore possible futures, such as prolonged low renewable generation or a grid outage.

## Getting started

Install Vessim with Python 3.9 to 3.15:

```console
python -m pip install vessim
```

This example models three days of datacenter demand, solar generation, and battery operation.
Surplus solar power charges the battery, which supplies demand when solar generation falls.
The grid supplies any remaining deficit and receives surplus power once the battery is full.

Download [solar_example.csv](https://raw.githubusercontent.com/dos-group/vessim/main/datasets/solar_example.csv) into your working directory, then run:

```python
import vessim as vs

# Scale the solar profile to a 2.4 kW installation.
solar = vs.Trace.from_csv("solar_example.csv", column="Berlin", scale=2400)

env = vs.Environment(sim_start="2026-01-01", step_size=5 * 60)
env.add_microgrid(
    name="site",
    actors=[
        vs.Consumer("load", signal=700),
        vs.Producer("solar", signal=solar),
    ],
    dispatchables=[vs.SimpleBattery("battery", capacity=1000), vs.GridConnection()],
)
recorder = env.add_controller(vs.Recorder("results/basic_example"))
env.run(until=3 * 24 * 3600)

metrics = recorder.metrics["microgrids"]["site"]
print(f"Grid import: {metrics['grid_import'] / 1000:.2f} kWh")
print(f"Grid export: {metrics['grid_export'] / 1000:.2f} kWh")
```

```text
Grid import: 26.71 kWh
Grid export: 11.08 kWh
```

[Explore this example in your browser](https://vessim.readthedocs.io/en/latest/viewer/index.html?study=getting-started#results), or open your saved results locally:

```console
python -m vessim view results/basic_example
```

The [Getting Started walkthrough](https://vessim.readthedocs.io/en/latest/getting_started/) explains how the components work together.
To use your own data, see [Actors and Signals](https://vessim.readthedocs.io/en/latest/concepts/signals/).

## Explore further

| Example | What you can explore |
| --- | --- |
| [Exploring microgrid configurations](examples/infrastructure_study.py) | Compare wind, solar, and battery configurations over a year. [View results](https://vessim.readthedocs.io/en/latest/viewer/index.html?study=infrastructure-year#results) |
| [Optimization](https://vessim.readthedocs.io/en/latest/concepts/optimization/) | Search for designs with different cost and emissions trade-offs. [View results](https://vessim.readthedocs.io/en/latest/viewer/index.html?study=optuna-search#results) |
| [Dispatch strategies](examples/strategy_comparison.py) | Compare control policies across demand scenarios. [View results](https://vessim.readthedocs.io/en/latest/viewer/index.html?study=dispatch-comparison#results) |
| [Demand response](examples/demand_response.py) | Adjust workload concurrency under a flexible grid connection agreement |
| [Custom metrics](examples/custom_metrics.py) | Calculate electricity costs, emissions, and your own study objectives |

[Run the examples locally](examples/README.md) with a shared setup and reproducible commands.

For [live measurements and REST control](https://vessim.readthedocs.io/en/latest/concepts/live/), install `pip install 'vessim[live]'` and use `vs.Environment.live()`.
To [connect external simulators](https://vessim.readthedocs.io/en/latest/concepts/coupling/) through Mosaik, install `pip install 'vessim[mosaik]'`.

## Publications

If you use Vessim in your research, please cite:

Philipp Wiesner, Ilja Behnke, Paul Kilian, Marvin Steinke, and Odej Kao.
[**Vessim: A Testbed for Carbon-Aware Applications and Systems.**](https://dl.acm.org/doi/pdf/10.1145/3727200.3727210)
*ACM SIGENERGY Energy Informatics Review 4 (5)*, 2024.

More papers are listed in the [documentation](https://vessim.readthedocs.io/en/latest/publications/)!


## About

Vessim was originally developed at the research group for [Distributed and Operating Systems](https://distributedsystems.berlin/) at TU Berlin. It is now maintained at the [Machine Learning Systems Lab](https://mlsys.cst.cam.ac.uk/) at the University of Cambridge.
