ASSUME: Agent-Based Electricity Markets Simulation Toolbox

ASSUME is an open-source toolbox for agent-based simulations of European electricity markets, with a primary focus on the German market setup. Developed as an open-source model, its primary objectives are to ensure usability and customizability for a wide range of users and use cases in the energy system modeling community.

Introduction

A unique feature of the ASSUME toolbox is its integration of Deep Reinforcement Learning methods into the behavioral strategies of market agents. The model offers various predefined agent representations for both the demand and generation sides, which can be used as plug-and-play modules, simplifying the reinforcement of learning strategies. This setup enables research into new market designs and dynamics in energy markets.

Documentation

• User Documentation
• Installation Guide

Installation

You can install ASSUME using pip. Choose the appropriate installation method based on your needs:

Using pip

To install the core package:

pip install assume-framework

To install with reinforcement learning capabilities:

pip install 'assume-framework[learning]'

Please keep in mind, that the above installation method will install pytorch package without CUDA support. If you want to make use of your GPU with CUDA cores, please install pytorch with GPU support separately as described here.

We also include network-based market clearing algorithms such as for the re-dispatch or nodal market clearing, which requires the PyPSA library. To install the package with these capabilities, use:

pip install 'assume-framework[network]'

To install with all capabilities:

pip install 'assume-framework[all]'

Timescale Database and Grafana Dashboards

If you want to benefit from a supported database and integrated Grafana dashboards for scenario analysis, you can use the provided Docker Compose file.

Follow these steps:

1. Clone the repository and navigate to its directory:

git clone https://github.com/assume-framework/assume.git
cd assume

2. Start the database and Grafana using the following command:

docker-compose up -d

This will launch a container for TimescaleDB and Grafana with preconfigured dashboards for analysis. You can access the Grafana dashboards at http://localhost:3000.

Using TensorBoard to display Learning Metrics

When running an example with learning capabilities, you can start TensorBoard to observe the learning process. Use the following shell command to start TensorBoard:

tensorboard --logdir tensorboard

You can then head to http://localhost:6006/ to view and evaluate the training progress.

Please note that TensorBoard should ideally be shut down via Ctrl + C every time you want to start a new simulation run in the same folder structure and want to overwrite existing results, as failing to do so may lead to conflicts deleting old logs.

Trying out ASSUME and the provided Examples

To ease your way into ASSUME we provided some examples and tutorials. The former are helpful if you would like to get an impression of how ASSUME works and the latter introduce you into the development of ASSUME.

The Tutorials

The tutorials work completely detached from your own machine on google colab. They provide code snippets and task that show you, how you can work with the software package one your own. We have two tutorials prepared, one for introducing a new unit and one for getting reinforcement learning ready on ASSUME.

How to configure a new unit in ASSUME?

How to use reinforcement learning for new market participants in ASSUME?

How to change and adapt reinforcement learning algorithms in ASSUME?

The Examples

To explore the provided examples, follow these steps:

1. Clone the repository and navigate to its directory:

git clone https://github.com/assume-framework/assume.git
cd assume

2. Quick Start:

There are three ways to run a simulation:

• Local:

python examples/examples.py

• Using the provided Docker setup:

If you have installed Docker and set up the Docker Compose file previously, you can select 'timescale' in examples.py before running the simulation. This will save the simulation results in a Timescale database, and you can access the Dashboard at http://localhost:3000.

• Using the CLI to run simulations:

assume -s example_01b -db "postgresql://assume:assume@localhost:5432/assume"

For additional CLI options, run assume -h.

Development

If you're contributing to the development of ASSUME, follow these steps:

1. Clone the repository and navigate to its directory:

git clone https://github.com/assume-framework/assume.git
cd assume

2. Install the package in editable mode:

pip install -e ".[all]"

3. Install pre-commit:

pip install pre-commit
pre-commit install

To run pre-commit checks directly, use:

pre-commit run --all-files

4. Install also testing capabilities:

pip install -e ".[testing]"

Release

To release a new version, increase the version in pyproject.toml and create a git tag of the release commit and release notes in GitHub.
To push to PyPi run:

rm -r dist
python -m build .
twine upload --repository pypi dist/*

See also: https://twine.readthedocs.io/en/stable/index.html#using-twine

Creating Documentation

First, create an environment that includes the documentation dependencies:

conda env create -f environment_docs.yaml

To generate or update the automatically created docs in docs/source/assume*, run:

sphinx-apidoc -o docs/source -Fa assume

To create and serve the documentation locally, use:

cd docs/source && python -m sphinx . ../build && cd ../.. && python -m http.server --directory docs/build

Contributors and Funding

The project is developed by a collaborative team of researchers from INATECH at the University of Freiburg, IISM at Karlsruhe Institute of Technology, Fraunhofer Institute for Systems and Innovation Research, Fraunhofer Institution for Energy Infrastructures and Geothermal Energy, and FH Aachen - University of Applied Sciences. Each contributor brings valuable expertise in electricity market modeling, deep reinforcement learning, demand side flexibility, and infrastructure modeling.

ASSUME is funded by the Federal Ministry for Economic Affairs and Climate Action (BMWK). We are grateful for their support in making this project possible.

License

Copyright 2022-2025 ASSUME developers.

ASSUME is licensed under the GNU Affero General Public License v3.0. This license is a strong copyleft license that requires that any derivative work be licensed under the same terms as the original work. It is approved by the Open Source Initiative.