Metadata-Version: 2.1
Name: assume-framework
Version: 0.1.0
Summary: ASSUME - Agent-Based Electricity Markets Simulation Toolbox
Home-page: https://assume.readthedocs.io
License: LICENSE
Keywords: agent based simulation,energy market,reinforcement learning,market simulation,simulation
Author: ASSUME Developers
Author-email: contact@assume-project.de
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: learning
Provides-Extra: optimize
Provides-Extra: test
Requires-Dist: black (>=23.3.0,<24.0.0) ; extra == "test"
Requires-Dist: glpk (>=0.4.7,<0.5.0) ; extra == "optimize" or extra == "test"
Requires-Dist: isort (>=5.12.0,<6.0.0) ; extra == "test"
Requires-Dist: mango-agents (>=1.1.1,<2.0.0)
Requires-Dist: matplotlib (>=3.7.2,<4.0.0) ; extra == "test"
Requires-Dist: mypy (>=1.1.1,<2.0.0)
Requires-Dist: nest-asyncio (>=1.5.6,<2.0.0)
Requires-Dist: paho-mqtt (>=1.5.1,<2.0.0)
Requires-Dist: pandas (>=2.0.0,<3.0.0)
Requires-Dist: psycopg2-binary (>=2.9.5,<3.0.0)
Requires-Dist: pyomo (>=6.6.1,<7.0.0) ; extra == "optimize" or extra == "test"
Requires-Dist: pytest (>=7.2.2,<8.0.0) ; extra == "test"
Requires-Dist: pytest-asyncio (>=0.21.1,<0.22.0) ; extra == "test"
Requires-Dist: pytest-cov (>=4.1.0,<5.0.0) ; extra == "test"
Requires-Dist: python-dateutil (>=2.8.2,<3.0.0)
Requires-Dist: pyyaml (>=6.0,<7.0)
Requires-Dist: sqlalchemy (>=2.0.9,<3.0.0)
Requires-Dist: torch (>=2.0.1,<3.0.0) ; extra == "learning"
Requires-Dist: tqdm (>=4.64.1,<5.0.0)
Project-URL: Repository, https://github.com/assume-framework/assume
Description-Content-Type: text/markdown

# ASSUME
![pytest, black, isort](https://github.com/assume-framework/assume/actions/workflows/lint-pytest.yml/badge.svg)
[![codecov](https://codecov.io/gh/assume-framework/assume/branch/main/graph/badge.svg?token=CZ4FO7P57H)](https://codecov.io/gh/assume-framework/assume)

**ASSUME** is an open-source tool-box for an agent-based simulation
of the European electricity and later on energy markets with a main
focus on the German market setup. As a newly developed open-source
model its priority is to ensure usability and customisability
for a variety of users and use cases in the energy system modelling community.

The unique feature of the ASSUME toolbox is the integration of **deep reinforcement
learning** methods into the behavioural strategies of market agents.
The model comes with different predefined agent representations for the demand and
generation side that can be used as plug-and-play modules,
which facilitate reinforcement of learning strategies.
This setup enables a research of new market designs and dynamics in the energy markets.

The project is developed by [developers](https://assume.readthedocs.io/en/latest/developers.html) from INATECH at University of Freiburg, IISM at KIT, Fraunhofer ISI, FH Aachen.
The project ASSUME is funded by the Federal Ministry for Economic
Affairs and Climate Action (BMWK).

Documentation
=============

[Documentation](https://assume.readthedocs.io/en/latest/)

[Installation](https://assume.readthedocs.io/en/latest/installation.html)


Installation
============


Using pip
---------

The project is available on [PyPi](https://pypi.org/) and can be simply installed:

```
pip install assume-framework
```

if you want to install it with testin capabilities run:

```
pip install assume-framework[test]
```


Using conda
-----------

First clone the repository:

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

Next, navigate to the cloned directory:

```
cd $where you cloned the repo$
```

Now, create a conda environment:

```
conda env create -f environment.yml
```

Afterwards, activate the environment:
```
conda activate assume-framework
```

Quick Start
-----------
There are 3 ways to run a simulation. <br>
1.) local (without database and grafana) <br>
2.) with docker (with database and grafana) <br>
3.) use CLI to run simulations

1. To run an exemplar simulation without database and grafana, run the following command:

```
python examples/examples.py
```

2. If you have docker installed, you can run the following two commands

Note: you have to select 'timescale' in examples.py
```
    docker compose up -d
    python examples/examples.py
```
This will start a container for timescaledb and grafana with preconfigured grafana dashboard.
Afterwards you can access the Dashboard on `http://localhost:3000`

3. You can also use the cli to run simulations:

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

If you need help using the CLI run `assume -h`


Please note that if you have python running on windows that you need to alter the same_process binary in world to True (to be changed).


Development
-----------

install pre-commit

```
pip install pre-commit
pre-commit install
```

to run pre-commit directly, you can use

```
pre-commit run --all-files
```


Create Documentation
--------------------

First, create an environment which includes the docs dependencies:

```
conda env create -f environment_docs.yml
```

To create the documentation 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, run

```bash
make -C docs html && python -m http.server --directory docs/build/html
```

Use Learning Capabilities
---------------------------------
If you want to use the reinforcement learning strategies of Assume please make sure to install torch on top of the requirements listed in the requirements.txt. If you Ressources do not have a GPU available use the CPU only version of torch, which can be installed like this:

pip install "torch>=2.0.1+cpu" -f https://download.pytorch.org/whl/torch_stable.html


Licence
=======

Copyright 2022-2023 [ASSUME developers](https://assume.readthedocs.io/en/latest/developers.html)

ASSUME is licensed under the [GNU Affero General Public License v3.0](./LICENSE)

