Skip to content
eliagroupPublic

About

Open Source Topology Optimization engine by Elia Group. Includes GPU‑based DC load flow solving, DC optimization, AC validation, and tools to explore congestion‑reducing topological actions.

Topics

Resources

Contributing

Security policy

Stars

76 stars

Watchers

2 watching

Forks

Latest commit

 

History

344 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Elia Group ToOp topology optimizer

Topology optimization for power grids, on the GPU

The interactive tour: ToOp's genetic search filling its repertoire of topologies, scored on the GPU
Take the interactive tour

CI OpenSSF Scorecard Quality Gate Status Coverage Duplicated Lines (%) License: MPL 2.0 Python 3.14

What is ToOp? | Quick examples | How it works | Installation | Documentation

What is ToOp?

Electricity does not take the route we pick for it. It spreads over every line it can reach, simply following the laws of physics. On busy days some of these lines end up carrying more power than they safely can – grid operators call this congestion. The usual fix is redispatch: asking one power plant to produce less and another, somewhere else, to produce more. It works, but it is expensive, and it often means starting up plants that emit more CO₂.

ToOp, short for topology optimization, looks for a cheaper and cleaner way out. Rather than changing who produces the electricity, it changes the layout of the grid itself – for example by switching off a line, or by splitting a substation so that it behaves like two separate junctions. Much like closing a street or opening a new junction in a city, these topological actions gently steer the power away from the lines that are full, and they cost next to nothing to carry out. ToOp searches through the many possible combinations and suggests the most promising ones to the operators in the control room, who always have the final say.

Our goal: help grid operators relieve congestion with clever switching instead of costly redispatch – saving money and CO₂ along the way.

This repository holds the engine behind ToOp at Elia Group. It reads operational grid data through an importer, searches for good topologies in a fast DC optimization stage, and double-checks the best candidates with a full AC validation. It also contains the GPU-based DC load flow solver that makes the search fast. Today ToOp considers transmission line switching, busbar splitting, busbar reassignment and linear tap optimization of phase-shifting transformers (PSTs); for grids imported with PowSyBl, it can also optimize groups of PSTs together.

Topological actions: line switching, busbar splitting and busbar reassignment

Curious how it all fits together? The interactive tour walks you through a whole run – from the grid file to the proposals shown to the operator – with a small animated sketch for every component.

▶ Take the interactive tour

Contents

Quick examples

A batched DC load flow in a few lines. Write the IEEE 57-bus test grid to a folder, preprocess it for the GPU solver and compute the flow on every branch:

from pathlib import Path

import jax
from fsspec.implementations.dirfs import DirFileSystem
from toop_engine_dc_solver.example_grids import case57_data_powsybl
from toop_engine_dc_solver.preprocess.convert_to_jax import load_grid, run_initial_loadflow

jax.config.update("jax_enable_x64", True)

folder = Path("data/case57")
case57_data_powsybl(folder)  # write the example grid
stats, static_information, network_data = load_grid(DirFileSystem(str(folder)))

static_information, metrics = run_initial_loadflow(static_information)
print(static_information.dynamic_information.unsplit_flow.shape)  # (timesteps, branches) -> (1, 82)

The whole pipeline: import, optimize, validate. The example notebooks walk you through it step by step and are the best place to continue:

Notebook What it shows
example1_dc_loadflow_example the DC load flow above, with more detail
example2_small_grid_toop optimizing a small node-breaker grid and looking at the changed substation
example3_e2e_pipeline the whole pipeline on any PyPowSyBl-compatible grid file
example4_data_contracts the same journey with the packages called directly, so every hand-over is visible
example5_e2e_ac_validation the whole pipeline called by hand, AC-validated end to end

To see how the stages of a run fit together, take the interactive tour:

▶ Take the interactive tour

How it works

A ToOp run passes through three stages, each a worker that can run on its own:

  1. Importer – reads a UCTE or CGMES grid, builds the masks and the N-1 definition, and prepares everything the GPU needs.
  2. DC-Optimizer – a genetic, quality-diversity search on the GPU; every candidate topology is scored with a batched DC load flow.
  3. AC-Validator – picks the most promising candidates and checks them with a full AC contingency analysis before they reach the operator.

For a visual, step-by-step tour of this pipeline – what every component does and which package implements it – take the interactive tour (or open docs/tour/index.html locally in your browser). The C4 architecture model lives in docs/architecture.

▶ Take the interactive tour

ToOp ships no GUI or system integration: you drive it from Python or through Kafka commands.

Installation

ToOp is not published on PyPI yet. Clone the repository and install it with uv:

git clone https://github.com/eliagroup/ToOp.git
cd ToOp
uv sync --all-groups

To run on an NVIDIA GPU, add JAX with CUDA support:

uv pip install "jax[cuda12]"

If you would like to contribute, we recommend the VS Code devcontainer, so everyone develops in the same environment. The contribution guide walks you through the setup.

Documentation and further reading

The full documentation lives at eliagroup.github.io/ToOp. To read it locally, run uv run zensical serve.

  • Quickstart – the basics, with examples to follow along
  • Usage – the two ways to use ToOp: from Python or through Kafka
  • Topology optimizer – the ideas behind the optimizer
  • DC solver – the GPU load flow solver and the batch dimensions it supports
  • Talks at LF Energy: 2025 and 2024

Working together

We believe topology optimization works best when it is developed jointly and applied to the grid as a whole, taking into account the operational constraints of different TSOs. So please try ToOp, ask questions, share your feedback and your constraints – and if you like it, contribute. We would also love to hear your ideas for combining ToOp with other open-source tools.

  • Contributing: have a look at our contribution guide.
  • Roadmap: current work broadens the supported controllable assets, improves preprocessing fidelity and hardens the end-to-end workflow. A more high-level roadmap will follow.
  • Contact: do not hesitate to reach out if you are interested in the project or need help with the setup. Your first point of contact is ToOp@eliagroup.eu.

Citing ToOp

If you use our work in scientific research, please cite our paper on load flow solving. The paper on the optimizer architecture will follow soon.

ToOp builds on JAX, and we gladly credit its authors:

@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},
}

License

Distributed under MPL 2.0. See LICENSE.

About

Open Source Topology Optimization engine by Elia Group. Includes GPU‑based DC load flow solving, DC optimization, AC validation, and tools to explore congestion‑reducing topological actions.

Topics

Resources

Contributing

Security policy

Stars

76 stars

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages