Skip to main content

ASSUME: Agent-Based Electricity Markets Simulation Toolbox

Lint Status Code Coverage DOI REUSE status

DOI

Try examples in Colab

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 predefined agent representations for both the demand and generation sides that can be used as plug-and-play modules, simplifying the implementation of learning strategies. This setup enables research into new market designs and dynamics in energy markets.

If you have any questions - get in contact on matrix: https://matrix.to/#/#assume-framework:matrix.org
Log into your existing matrix account or create a new one. Paste the URL in the search field.

What can the software do?

The main motivation of ASSUME is to overcome the limitations of fixed, rule-based behaviors in existing ABMs. For this, it leverages advancements in artificial intelligence, particularly deep reinforcement learning (DRL), enabling agents to adapt their behavior dynamically in response to market conditions. This approach is practical for modeling interactions among competing market participants and observing emergent patterns from these interactions. To support market design analysis in transforming electricity systems, we developed the ASSUME framework - a flexible and modular agent-based modeling tool for electricity market research. ASSUME enables researchers to customize components such as agent representations, market configurations, and bidding strategies, utilizing pre-built modules for standard operations. With the setup in ASSUME, researchers can simulate strategic interactions in electricity markets under a wide range of scenarios, from comparing market designs and modeling congestion management to analyzing the behavior of learning storage operators and renewable producers. The framework supports studies on bidding under uncertainty, regulatory interventions, and multi-agent dynamics, making it ideal for exploring emergent behavior and testing new market mechanisms. ASSUME has been utilized in research studies addressing diverse questions in electricity market design and operation. It has explored the role of complex bids, demonstrated the effects of industrial demand-side flexibility for congestion management, and advanced the explainability of emergent strategies in learning agents.

Who is it made for?

The framework is versatile enough to be employed in smaller-scale projects, such as master's theses, while also robust enough for complex doctoral research or investigations conducted by industry professionals. This accessibility and scalability make ASSUME suitable for many users, from early-career researchers to experienced professionals.

Documentation

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]'

The learning extra depends on a generic torch and leaves the choice of build to you. On Linux, the default wheel from PyPI is the CUDA build, which pulls in several GB of nvidia-* packages. If you do not have a GPU, install the CPU-only build first, then the extra (pip keeps the already installed torch):

pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install 'assume-framework[learning]'

If you want to make use of your GPU with CUDA cores, install PyTorch with GPU support as described here.

We also include network-based market clearing algorithms such as for the re-dispatch, zonal clearing with NTCs and nodal market clearing, which all require 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

The Timescale Database and Grafana Dashboard are used to store and represent simulation results.

If you want to use the supported TimescaleDB 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
  1. 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

TensorBoard is used to visualize and monitor the learning progress during reinforcement learning training.

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 tutorial notebooks and preconfigured example simulations in the examples folder. The former are helpful if you would like to get an impression of how ASSUME works, as they present different functionalities of ASSUME condensed in specific notebooks, and the latter provides various example simulations ranging from 8 power plant examples to the representations of Germany for one year.

The Tutorial Notebooks

You can run the tutorials locally using the notebooks here or use Google Colab. The tutorials begin with the basics of ASSUME, e.g., introducing a new unit, while the later tutorials cover more advanced use cases.

We particularly recommend these tutorials; more can be found at the linked pages:

How to configure a new unit in ASSUME?

Open Learning Tutorial in Colab

How to change and adapt reinforcement learning algorithms in ASSUME?

Open Learning Tutorial in Colab

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

  • Power plant unit: Open Learning Tutorial in Colab

  • Storage unit: Open Learning Tutorial in Colab

Preconfigured Examples

To explore the provided example simulations here, follow these steps:

  1. Clone the repository and navigate to its directory:
git clone https://github.com/assume-framework/assume.git
cd assume
  1. 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

The Contribution Guidelines explain how to set up your development environment and contribute to the project.

Creating Documentation

See the Contribution Guidelines on how to build the docs for ASSUME.

Contributors and Funding

The project is developed by a collaborative team of researchers from INATECH at the University of Freiburg, WIN at Karlsruhe Institute of Technology, Fraunhofer Institute for Systems and Innovation Research (ISI), 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.

Citing ASSUME

If you use ASSUME in your research, we would appreciate it if you cite the following paper:

Please use the following BibTeX to cite our work:

@article{ASSUME,
  title = {{ASSUME: An agent-based simulation framework for exploring electricity market dynamics with reinforcement learning}},
  author = {Harder, Nick and Miskiw, Kim K and Khanra, Manish and Maurer, Florian and Patil, Parag and Qussous, Ramiz and Weinhardt, Christof and Klobasa, Marian and Ragwitz, Mario and Weidlich, Anke},
  journal = {SoftwareX},
  volume = {30},
  pages = {102176},
  year = {2025},
  issn = {2352-7110},
  doi = {10.1016/j.softx.2025.102176},
  url = {https://www.sciencedirect.com/science/article/pii/S2352711025001438},
  keywords = {Electricity markets, Python, Reinforcement learning, Agent-based modeling}
}

If you want to cite a specific version of ASSUME, all releases are archived on Zenodo with version-specific DOIs:

DOI

License

Copyright 2022-2026 ASSUME developers.

ASSUME is licensed under the MIT License. This permissive license allows use, modification and redistribution, including in proprietary software, as long as the copyright and license notice are kept. It is approved by the Open Source Initiative.

Metadata

Release files for assume-framework 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for assume-framework 0.7.0
File Size Uploaded Provenance Actions
assume_framework-0.7.0.tar.gz 7.9 MB With provenance Details for assume_framework-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for assume-framework 0.7.0
File Interpreter ABI Platform Actions
assume_framework-0.7.0-py3-none-any.whl Python 3 none any Details for assume_framework-0.7.0-py3-none-any.whl

Total release size: 8.2 MB

Release files / assume_framework-0.7.0.tar.gz

Download URL assume_framework-0.7.0.tar.gz
Size 7.9 MB
Tags Source
SHA-256 checksum
How to use checksums
d687406aeb0a32a1dd037cce671e8bd0b8f91c4ed47ed0a42546693abc5d6da7
BLAKE2b-256 checksum
How to use checksums
4fa4f10342da1965f92eddb6573f841b50ce84fbb982ab5a2051bd7373ba55cd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / assume_framework-0.7.0-py3-none-any.whl

Download URL assume_framework-0.7.0-py3-none-any.whl
Size 346.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a5935663648cf957906f87b963008ea1be2c04c5634b4a1889c92595799fe447
BLAKE2b-256 checksum
How to use checksums
e9a913be252e77dc6ced45f22a51fd4be750d749b08691c9d7c75d0ae26b8ac3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for assume-framework 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for assume_framework-0.7.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page