Metadata-Version: 2.5
Name: vessim
Version: 0.15.1
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: Topic :: Education
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Testing
Requires-Python: <3.14,>=3.9
Requires-Dist: docopt-ng>=0.9.0
Requires-Dist: loguru>=0.6.0
Requires-Dist: mosaik-api-v3>=3.0.4
Requires-Dist: mosaik>=3.3.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyyaml>=6.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-pyyaml; 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: sil
Requires-Dist: fastapi>=0.104.0; extra == 'sil'
Requires-Dist: prometheus-client>0.22.0; extra == 'sil'
Requires-Dist: requests>=2.26.0; extra == 'sil'
Requires-Dist: uvicorn>=0.23.0; extra == 'sil'
Description-Content-Type: text/markdown

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

Vessim is a **co-simulation testbed for microgrids**\*

Vessim lets you model how loads, (renewable) generation, energy storage, and the public grid interact, and test control and dispatch strategies against them, in pure simulation or with **real software and hardware** in the loop.

*\*By "microgrid" we mean any local energy system that combines loads, generation, and storage behind a grid connection. Grids can scale from small battery-constrained systems to a GW-scale datacenter campus.*

Check out the [website and documentation](https://vessim.readthedocs.io/en/latest/)!

## What can I do with Vessim?

Vessim helps you understand and optimize how loads, energy sources, and storage interact.
It was originally designed for energy-aware and carbon-aware data centers, but has also been used for other use cases such as battery price arbitrage and demand response for cooling warehouses.

- **Control and dispatch strategies**: Test battery charging/discharging, load-shifting, and price- or carbon-driven dispatch.
- **Demand response and power outages**: Simulate demand response signals or power outages to understand your system's flexibility and test mitigation strategies.
- **Microgrid composition**: Experiment with adding solar panels, wind turbines, or batteries to see how they would affect your energy costs and carbon emissions.
- **Energy- and carbon-aware computing**: Develop applications that adapt their energy consumption to the carbon intensity and price of electricity.

Vessim can simulate multiple distributed microgrids in parallel and easily integrates historical datasets and new simulators. 
Vessim’s software-in-the-loop capabilities let you run real systems against simulated microgrids. Connect live data sources like Prometheus and interact through REST APIs.


## Simple Example

The scenario below simulates a microgrid with a computing system drawing 700W, a solar panel, and a 1.5 kWh battery.

```python
import vessim as vs

environment = vs.Environment(sim_start="2022-06-09", step_size=300)

environment.add_microgrid(
    name="datacenter",
    actors=[
        vs.Actor(name="server", signal=vs.StaticSignal(value=700), consumer=True),
        vs.Actor(name="solar_panel", signal=vs.Trace.from_csv(
            "datasets/solar_example.csv", column="Berlin", scale=5000
        )),
    ],
    dispatchables=[
        vs.SimpleBattery(name="battery", capacity=1500, initial_soc=0.8, min_soc=0.3)
    ],
)

environment.add_controller(vs.CsvLogger("results/my_experiment"))
environment.run(until=24 * 3600)
```

Check out the [Getting Started walkthrough](https://vessim.readthedocs.io/en/latest/getting_started/) and [`examples/`](examples/) for software-in-the-loop simulations.


## 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 capabilities, install the `sil` extension:

```
pip install vessim[sil]
```

## 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://dl.acm.org/doi/pdf/10.1145/3727200.3727210)" _ACM SIGENERGY Energy Informatics Review 4 (5)_. 2024.

For details in Vessim's software-in-the-loop simulation methodology, refer to:

- 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 more related papers and concrete use cases, please refer to the [documentation](https://vessim.readthedocs.io/en/latest/publications).
