README.md

Hello there 👋

Welcome to our ToOp (engine) repository at Elia Group.

A short intro - what is ToOp about?

ToOp is short for Topology Optimization and describes the approach to reduce grid congestion by topological actions. Topological actions are non-costly actions that can be applied to the grid to "steer" the electricity flow. Our goal is to propose (potentially) new topology strategies to the operators with the goal to lower redispatch costs and carbon emissions.

This repository builds the engine behind the topology optimization product ToOp at Elia Group. ToOp provides tools to perform topology optimization on operational grid data through an importer, a DC optimization stage, and AC validation. It also includes the GPU-based DC load flow solver. At the current stage it considers transmission line switching, busbar splitting, busbar reassignments, and grouped PST tap optimization.

About this repository

This repo builds the engine behind the topology optimization project ToOp at Elia Group. The standard workflow first normalizes a raw grid into a processed grid folder containing the backend grid snapshot, masks, loadflow parameters, topology metadata, and an initial contingency definition. The DC preprocessing stage then adds static_information.hdf5, action_set.json, action_set_diffs.hdf5, and the final nminus1_definition.json used by the solver, optimizer, and postprocessing. Note that this does NOT provide a GUI or system integration code, you are expected to interact with the module through either python or kafka commands. You can check the paper for a high level academic introduction. Please check out our full documentation.

Getting Started

If you want to get started with the engine, we highly recommend checking out our example notebooks.

Prerequisites

We use uv for dependency management. You can follow their installation guide:

1. Install on Linux/Mac via curl -LsSf https://astral.sh/uv/install.sh | sh
2. or if you have pipx via pipx install uv.

If you want to contribute to this repository, follow the guide on our Contributing page.

Installation (without contributing)

You need to install our software via source by cloning this repository

  git clone https://github.com/eliagroup/ToOp.git
  cd ToOp

and installing dependencies

  uv sync --all-groups

If you plan to run this software on GPU-accelerated hardware, you may additionally install jax with CUDA support by running

  uv pip install jax[cuda12]

Note: We currently do not publish our package on PyPI. If you use uv for your own project and want to use ToOp, you can add it as a local dependency to your pyproject.toml, pointing to the cloned repository.

Usage

In order to understand the functionalities of this repo, please have a look at our examples in notebooks/. There you can find several Jupyter notebooks that explain how to use the engine. For example, you can import a grid file, build the preprocessing artifacts, and compute the DC loadflow using our GPU-based loadflow solver. Or you can load an example grid and minimise the branch overload by running the topology optimizer.

You can also build the documentation and open it on your web browser by running

uv run mkdocs serve

---

Useful resources

The following resources may be helpful to grasp the key concepts:

• Quickstart: Grasp the basics and follow along examples. The first one takes you through a DC loadflow computation using the DC Solver package.
• Usage: Learn about the two different ways to use this software, either via python or kafka.
• Topology Optimizer: Understand the key concepts behind the topology optimizer.
• Presentation@LF Energy 2025
• Presentation@LF Energy 2024

Note: This project does not provide a GUI or system integration code. You are expected to interact with the module through either python or kafka commands. This might come in the future if there is an interest from the community.

High-level architecture

The topology optimizer takes as an input operational grid files (e.g. UCT, CGMES) which are imported by open-source libraries (PowSyBl, pandapower) and normalized into a processed grid folder. The importer stage writes the backend grid snapshot together with masks, loadflow parameters, and topology metadata; the DC preprocessing stage adds static_information.hdf5, action_set.json, and the final contingency definition. The pre-processed files are then optimized in a GPU-native set-up (optimizer + GPU-based load flow solver). The optimal results are stored as a pareto-front, so a set of all solutions that are "Pareto optimal". This means that no other solution exists that improves at least one objective without worsening another one. These results are then validated and filtered using an AC power flow. In the end the results are displayed in a frontend where an end user can review and evaluate the proposed actions. The proposed topological actions can then be exported to other systems.

Description the GPU-based DC load Flow solver

The GPU-based DC Load Flow solver serves the purpose of computing a large number of similar DC load flows in an accelerated fashion. Currently the solver supports the following batch dimensions, i.e. the workload must not change in anything other than these dimensions: • Branch topology (assignment of branches to busbar A or B) • Injection topology (assignment of injections to busbar A or B) • Branch outages

Under the hood, it is using PTDF/(G)LODF/BSDF approaches to achieve this.

Roadmap

Next to some smaller improvements, current work focuses on broadening controllable asset support, improving preprocessing fidelity, and hardening the end-to-end optimization workflow. We will work on sharing a more high-level roadmap in the future.

Let us work together

We strongly believe that through joint development, collaboration and integration into other tools, we can jointly build an open-source topology optimizer that is fast, provides accurate recommendations and can be used by different TSOs to reduce grid congestion. Topology optimization works best when holistically applied to the grid and the different operational constraints from different TSOs are considered. This is why we invite you to share your feedback, constraints and your approaches so that we can jointly improve ToOp.

In addition, we also see the opportunity that ToOp can be combined with other open-source tools. If you have ideas, reach out to us. We invite you to test it, ask questions and provide feedback to us. And if you like it, we invite you to contribute to the development. We are looking forward to hearing from you.

Finding help

If you require help with using this package, your first point of contact is ToOp@eliagroup.eu.

Contributing

Please have a look at our CONTRIBUTING.md.

---

License

Distributed under MPL 2.0. See LICENSE.

Citation

If you use our work in scientific research, please cite our paper on load flow solving or our paper on the optimizer architecture, depending what parts of the repository you use.

---

Contact

Team – ToOp

---

Acknowledgments

We credit the authors of JAX.

@software{jax2018github,
  author = {James Bradbury and Roy Frostig and Peter Hawkins and Matthew James Johnson and Chris Leary and Dougal Maclaurin and George Necula and Adam Paszke and Jake Vander{P}las and Skye Wanderman-{M}ilne and Qiao Zhang},
  title = {{JAX}: composable transformations of {P}ython+{N}um{P}y programs},
  url = {http://github.com/jax-ml/jax},
  version = {0.3.13},
  year = {2018},
}