{"id":13724081,"url":"https://github.com/dos-group/vessim","last_synced_at":"2025-12-27T20:10:56.891Z","repository":{"id":176865683,"uuid":"603417933","full_name":"dos-group/vessim","owner":"dos-group","description":"A co-simulation testbed for carbon-aware applications and systems 🍃","archived":false,"fork":false,"pushed_at":"2024-06-07T14:44:39.000Z","size":43871,"stargazers_count":39,"open_issues_count":11,"forks_count":3,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-06-11T17:26:58.142Z","etag":null,"topics":["carbon-aware","co-simulation","energy-system","simulation","software-in-the-loop","testbed"],"latest_commit_sha":null,"homepage":"https://vessim.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dos-group.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-18T12:59:09.000Z","updated_at":"2024-06-13T04:18:14.269Z","dependencies_parsed_at":null,"dependency_job_id":"f00e242d-a02c-4577-b290-01938007c565","html_url":"https://github.com/dos-group/vessim","commit_stats":{"total_commits":839,"total_committers":11,"mean_commits":76.27272727272727,"dds":0.7616209773539928,"last_synced_commit":"7be55b5e21ed195292e2831158f6f13a92021086"},"previous_names":["dos-group/vessim"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dos-group%2Fvessim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dos-group%2Fvessim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dos-group%2Fvessim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dos-group%2Fvessim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dos-group","download_url":"https://codeload.github.com/dos-group/vessim/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":206874905,"owners_count":14636831,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["carbon-aware","co-simulation","energy-system","simulation","software-in-the-loop","testbed"],"created_at":"2024-08-03T01:01:49.796Z","updated_at":"2025-12-27T20:10:56.883Z","avatar_url":"https://github.com/dos-group.png","language":"Python","readme":"# 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/lint-and-unit-test.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 **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\u003cp float=\"left\"\u003e\n  \u003cimg src=\"docs/_static/solcast_logo.png\" width=\"120\" /\u003e\n  \u003cspan\u003e and \u003c/span\u003e\n  \u003cimg src=\"docs/_static/watttime_logo.png\" width=\"120\" /\u003e\n\u003c/p\u003e\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","funding_links":[],"categories":["Dev / Tooling","Energy Systems","Uncategorized"],"sub_categories":["General purpose","Grid Management and Microgrid","Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdos-group%2Fvessim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdos-group%2Fvessim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdos-group%2Fvessim/lists"}