emflow 0.0.3.post1

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

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

emflow 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) and Warran Powell's universal sequential decision framework. emflow 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  |  📖 Documentation  |  🚀 Try out now in Colab  |  👋 Join Slack Community

The Sequential Decision Loop

emflow 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.

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

emflow 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 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
📦 spaces	BaseSpace, InputSpace, StateSpace, OutputSpace,ActionSpace
🧩 problems	Dataset, Environment, Objective
🤖 models	Model, Simulator, Predictor, Optimizer, Agent
➡️ experiments	Experiment, Benchmark, Scenario

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

Framework 6-Step Approach

emflow 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 emflow, 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:

# First your code to define dataset, env, agent and obj, here. 
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 or open in Colab.

Installation

We recommend installing using a virtual environment like venv, poetry or uv.

Install the stable release:

pip install emflow

Install the latest release:

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

Install in editable mode for development:

git clone https://github.com/rebase-energy/EnergyDataModel.git
git clone https://github.com/rebase-energy/emflow.git
cd emflow
pip install -e .[dev]
pip install -e ../EnergyDataModel[dev]

Ways to Contribute

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

• 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 Slack Community so that we can discuss it.

Contributors

This project uses allcontributors.org to recognize all contributors, including those that don't push code.

Sebastian Haglund 💻

dimili 💻

Mihai Chiru 💻

Nelson 🤔

Licence

This project uses the MIT Licence.

Acknowledgement

The authors of this project would like to thank the Swedish Energy Agency for their financial support under the E2B2 program (project number P2022-00903)