Metadata-Version: 2.1
Name: vessim
Version: 0.5.0a1
Summary: A simulator for carbon-aware applications and systems.
Home-page: https://github.com/dos-group/vessim
License: MIT
Keywords: simulation,energy system,testbed,carbon-aware computing,software-in-the-loop
Author: Philipp Wiesner
Author-email: wiesner@tu-berlin.de
Requires-Python: >=3.8,<3.13
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.8
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 :: Only
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Testing
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: sil
Requires-Dist: black ; extra == "dev"
Requires-Dist: docker ; extra == "sil"
Requires-Dist: fastapi ; extra == "sil"
Requires-Dist: furo ; extra == "docs"
Requires-Dist: loguru
Requires-Dist: mosaik
Requires-Dist: mosaik-api
Requires-Dist: mypy ; extra == "dev"
Requires-Dist: numpy (>=1.22,<2.0) ; python_version < "3.12"
Requires-Dist: numpy (>=1.26,<2.0) ; python_version >= "3.12"
Requires-Dist: pandas
Requires-Dist: pandas-stubs ; extra == "dev"
Requires-Dist: pytest ; extra == "dev"
Requires-Dist: redis ; extra == "sil"
Requires-Dist: requests ; extra == "sil"
Requires-Dist: ruff ; extra == "dev"
Requires-Dist: sphinx-copybutton ; extra == "docs"
Requires-Dist: types-psutil ; extra == "dev"
Requires-Dist: types-requests ; extra == "dev"
Requires-Dist: uvicorn ; extra == "sil"
Project-URL: Bug Reports, https://github.com/dos-group/vessim/issues
Project-URL: Documentation, https://github.com/dos-group/vessim
Project-URL: Repository, https://github.com/dos-group/vessim
Description-Content-Type: text/markdown

# 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.

## Simulated energy systems for computing systems

Vessim allows you to simulate energy systems next to real or simulated computing systems:

```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=100)]),
        Generator(signal=HistoricalSignal.from_dataset("solcast2022_global")),
    ],
    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 can install the `sil` extra:

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

For complex scenarios that involve custom co-simulation actors we recommend cloning and editing this depository directly.


## 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="150" />
  <span> and </span>
  <img src="docs/_static/watttime_logo.png" width="150" />
</p>

We're working on documentation on how to include custom datasets for your simulations.


## 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:

- **Website**: We are currently working on better examples and documentation. You can find the current WiP documentation [here](https://vessim.readthedocs.io/en/latest/).
- **Imroved Software-in-the-loop (SiL) 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 making NREL's [SAM](https://sam.nrel.gov/) available as a subsystem in Vessim.


## Publications

If you use Vessim in your research, please cite our 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}
}
```

Or our journal paper on software-in-the-loop similation 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}
}
```

