Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rebase-energy/enerflow

⚡ Open-source Python framework for modelling sequential decision problems in the energy sector
https://github.com/rebase-energy/enerflow

energy gymnasium modelling openai-gym python sequential-decision-making-problems

Last synced: about 21 hours ago
JSON representation

⚡ Open-source Python framework for modelling sequential decision problems in the energy sector

Awesome Lists containing this project

README 

        


	enerflow



    ⚡ Open-source Python framework for modelling sequential decision problems in the energy sector






[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)

[![PyPI version](https://badge.fury.io/py/enerflow.svg)](https://badge.fury.io/py/enerflow) 

[![All Contributors](https://img.shields.io/github/all-contributors/rebase-energy/enerflow?color=ee8449&style=flat-square)](#contributors)

[![Join us on Slack](https://img.shields.io/badge/Join%20us%20on%20Slack-%2362BEAF?style=flat&logo=slack&logoColor=white)](https://join.slack.com/t/rebase-community/shared_invite/zt-1dtd0tdo6-sXuCEy~zPnvJw4uUe~tKeA) 

[![GitHub Repo stars](https://img.shields.io/github/stars/rebase-energy/enerflow?style=social)](https://github.com/rebase-energy/enerflow)



**enerflow** is an open-source Python framework that enables energy data scientists and modellers to write modular and reproducible energy models that solves sequential decision problems. It is based on both OpenAI Gym (now [Gymnasium](https://github.com/Farama-Foundation/Gymnasium)) and [Warran Powell's universal sequential decision framework](https://castle.princeton.edu/rlso/). **enerflow** lets you: 



* 🛤️ Structure your code as modular and reusable components and adopt the "model first, then solve"-mantra;

* 🌱 Forumate your problems with datasets, environments and objectives;

* 🏗️ Build agents, predictors, optimizers and simulators to solve sequential decision problems;

* 🧪 Run parametrized experiments that generate reproducible results (code, data and parameters); and

* ➿ Run sweeps for benchmarking, scenario analysis and parameter tuning.



**⬇️ [Installation](#installation)**

 | 

**📖 [Documentation](https://docs.energydatamodel.org/en/latest/)**

 | 

**🚀 [Try out now in Colab](https://colab.research.google.com/github/rebase-energy/enerflow/blob/main/enerflow/examples/heftcom2024/notebook.ipynb)**

 | 

**👋 [Join Community Slack](https://join.slack.com/t/rebase-community/shared_invite/zt-1dtd0tdo6-sXuCEy~zPnvJw4uUe~tKeA)**



## The Sequential Decision Loop

**enerflow** allows to model sequential decison problems, where state information **$S_t$** is provided, an action **$a_t=A^{\pi}(S_t)$** is taken, exogenous information **$W_{t+1}$** is revealed, whereby a new state **$S_{t+1} = S^M(S_t, a_t, W_{t+1})$** is encountered and a cost/contribution **$C(S_t,a_t,W_{t+1})$** can be calculated. The sequential decision loop then repeats until the end of the evaluation/problem time. 



![Sequential decision loop](assets/sequential-decision-loop.png)



The goal is to find an agent policy **$\pi$** that maximizes the contribution (or minimizes the cost) over the full time horizon **$t \in [0, T]$**. Mathematically formulated as: 



$$

\begin{equation*}

\begin{aligned}

\max_{\pi \in \Pi} \quad & \mathbb{E}^{\pi} \bigg[ \sum_{t=0}^T C(S_t,A^{\pi}(S_t),W_{t+1}) \bigg| S_0 \bigg] \\

\textrm{s.t.} \quad & S_{t+1} = S^M(S_t,a_t,W_{t+1})\\

\end{aligned}

\end{equation*}

$$



## Modules and Components

**enerflow** consists of a set of components that serve as building blocks to create modular and reusable energy models. One of the main dependencies is [EnergyDataModel](https://github.com/rebase-energy/EnergyDataModel) that provides functionality to represent energy systems. The table below gives a summary of the available modules and concepts.



| Module         | Components     |

| :----          | :----            |

| 🔋 `energysystem` | All energy asset and concept components defined by [EnergyDataModel](https://github.com/rebase-energy/EnergyDataModel) | 

| 📦 `spaces` | [`BaseSpace`](), [`InputSpace`](), [`OutputSpace`]() [`StateSpace`]() [`ActionSpace`]() | 

| 🧩 `problems` | [`Dataset`](), [`Environment`](), [`Objective`]() | 

| 🤖 `models` | [`Model`](), [`Simulator`](), [`Predictor`](), [`Optimizer`](), [`Agent`]() | 

| ➡️ `experiment` | [`Experiment`]()| 



Below is a diagram of the components' relation to each other and how they together enable creation of reproducible results from energy models. 



![enerflow Framework Structure](assets/enerflow-framework-structure.png)



## Framework 6-Step Approach

**enerflow** is about adopting a problem-centric, stepwise approach that follows the "model first, then solve"-mantra. The idea is to first gain a deep problem understanding before rushing to the solution. Or as Albert Einstien expressed it: 



> **"If I had an hour to solve a problem I'd spend 55 minutes thinking about the problem and five minutes thinking about solutions."**



Concretely, this means that problems are solved through the following steps: 



1. Define the considered **energy system**;

2. Define **state**, **action** and **exogenous** variables;

3. Create the **environment** and the transition function;

4. Define the **objective** (cost or contribution);

5. Create the **model** (simulator, predictor, optimizer and/or agent) to operate in environment; and

6. Run the **sequential decision loop** and evaluate performance.



Steps 1-4 are about understanding the **problem** and steps 5-6 are about creating and evaluating the **solution**. 



## Basic Usage

In **enerflow**, a reproducible experiment is represented by the following 4 components: 



* [`Dataset`]()

* [`Environment`]()

* [`Agent`]()

* [`Objective`]()



Given a defined `dataset`, `env` (environment), `agent` (model) and `obj` (objective), the sequential decision loop is given by: 



```python

# Create the env, agent and obj. Your code goes in defining these classes. 

env = Environment(dataset=dataset)

agent = Agent(dataset=dataset)

obj = Objective(dataset=dataset)



state = env.reset()

done = False

while done is not True:

    action = agent.act(state)

    state, exogeneous, done, info = env.step(action)

    cost = obj.calculate(state, action, exogeneous)



env.close()

```



For a full walkthrough go to the [documentation](https://docs.enerflow.org/en/latest/walkthrough.html#) or open in [Colab](https://colab.research.google.com/github/rebase-energy/enerflow/blob/main/enerflow/examples/walkthrough/notebook.ipynb). 



## Installation

Install the **stable** release: 

```bash

pip install enerflow

```



Install the **latest** release: 

```bash

pip install git+https://github.com/rebase-energy/enerflow

```



Install in editable mode for **development**: 

```bash

git clone https://github.com/rebase-energy/enerflow.git

cd enerflow

pip install -e . 

```



## Ways to Contribute

We welcome contributions from anyone interested in this project! Here are some ways to contribute to **enerflow**:



* Create a new environment; 

* Create a new energy model (simulator, predictor, optimizer or agent); 

* Create a new objective function; or

* Create an integration with another energy modelling framework.



If you are interested in contributing, then feel free to join our [Community Slack](https://join.slack.com/t/rebase-community/shared_invite/zt-1dtd0tdo6-sXuCEy~zPnvJw4uUe~tKeA) so that we can discuss it. 



## Contributors

This project uses [allcontributors.org](https://allcontributors.org/) to recognize all contributors, including those that don't push code. 



  

    

      Sebastian Haglund
Sebastian Haglund
💻

      dimili
dimili
💻

      Mihai Chiru
Mihai Chiru
💻

      Nelson
Nelson
🤔

    

  



## Licence

This project uses the [MIT Licence](LICENCE.md).