Skip to main content

​
Overview

The Grid2Op integration provides a backend implementation that allows Grid2Op environments to use PyPowSyBl as their power flow solver. This enables Grid2Op agents to leverage the robust simulation capabilities of PowSyBl for training and evaluation.

​
Backend

​
Backend Class

The main class for Grid2Op integration. 
from pypowsybl.grid2op import Backend
from pypowsybl.network import Network

# Create a backend from an existing network
network = Network.load("path/to/network.xiidm")
backend = Backend(network)
​
network
Network
required
The PyPowSyBl network to use for the backend
​
consider_open_branch_reactive_flow
bool
default:"False"
Whether to consider reactive flow in open branches
​
check_isolated_and_disconnected_injections
bool
default:"True"
Whether to check for isolated and disconnected injections during validation
​
buses_per_voltage_level
int
default:"2"
Number of buses per voltage level in the bus-breaker topology
​
connect_all_elements_to_first_bus
bool
default:"True"
Whether to connect all elements to the first bus initially

​
Methods

​
network

Get the underlying PyPowSyBl network. 
network = backend.network
​
network
Network
The PyPowSyBl network object

​
get_string_value

Retrieve string values from the backend (e.g., element names). 
from pypowsybl.grid2op import StringValueType

load_names = backend.get_string_value(StringValueType.LOAD_NAME)
generator_names = backend.get_string_value(StringValueType.GENERATOR_NAME)
​
value_type
StringValueType
required
The type of string value to retrieve
​
values
numpy.ndarray
Array of string values

​
get_integer_value

Retrieve integer values from the backend (e.g., bus numbers, topology vector). 
from pypowsybl.grid2op import IntegerValueType

topo_vect = backend.get_integer_value(IntegerValueType.TOPO_VECT)
load_buses = backend.get_integer_value(IntegerValueType.LOAD_VOLTAGE_LEVEL_NUM)
​
value_type
IntegerValueType
required
The type of integer value to retrieve
​
values
numpy.ndarray
Array of integer values

​
get_double_value

Retrieve double/float values from the backend (e.g., power flows, voltages). 
from pypowsybl.grid2op import DoubleValueType

load_p = backend.get_double_value(DoubleValueType.LOAD_P)
load_q = backend.get_double_value(DoubleValueType.LOAD_Q)
gen_v = backend.get_double_value(DoubleValueType.GENERATOR_V)
​
value_type
DoubleValueType
required
The type of double value to retrieve
​
values
numpy.ndarray
Array of float values

​
update_double_value

Update double/float values in the backend (e.g., injection setpoints). 
from pypowsybl.grid2op import UpdateDoubleValueType
import numpy as np

# Update load active power
values = np.array([100.0, 150.0, 200.0])
changed = np.array([1, 1, 0])  # Flags indicating which values changed
backend.update_double_value(UpdateDoubleValueType.UPDATE_LOAD_P, values, changed)
​
value_type
UpdateDoubleValueType
required
The type of value to update
​
value
numpy.ndarray
required
Array of new values
​
changed
numpy.ndarray
required
Binary array indicating which elements have changed (1 for changed, 0 for unchanged)

​
update_integer_value

Update integer values in the backend (e.g., bus connections). 
from pypowsybl.grid2op import UpdateIntegerValueType
import numpy as np

# Update generator bus connections
bus_ids = np.array([1, 2, 1])
changed = np.array([1, 1, 0])
backend.update_integer_value(UpdateIntegerValueType.UPDATE_GENERATOR_BUS, bus_ids, changed)
​
value_type
UpdateIntegerValueType
required
The type of value to update
​
value
numpy.ndarray
required
Array of new values
​
changed
numpy.ndarray
required
Binary array indicating which elements have changed (1 for changed, 0 for unchanged)

​
check_isolated_and_disconnected_injections

Check if there are any isolated or disconnected injections in the network. 
is_valid = backend.check_isolated_and_disconnected_injections()
​
is_valid
bool
True if the network has no isolated or disconnected injections, False otherwise

​
run_pf

Run a power flow calculation on the network. 
from pypowsybl.loadflow import Parameters

# Run AC power flow
results = backend.run_pf(dc=False)

# Run DC power flow
results = backend.run_pf(dc=True)

# Run with custom parameters
params = Parameters()
results = backend.run_pf(dc=False, parameters=params)
​
dc
bool
default:"False"
Whether to run DC power flow (True) or AC power flow (False)
​
parameters
Parameters
Optional load flow parameters to customize the calculation
​
results
List[ComponentResult]
List of component results, one per connected component in the network

​
close

Close the backend and free associated resources. 
backend.close()

​
Context Manager Support

The Backend supports Python’s context manager protocol for automatic resource management: 
from pypowsybl.grid2op import Backend
from pypowsybl.network import Network

network = Network.load("path/to/network.xiidm")

with Backend(network) as backend:
    # Use the backend
    results = backend.run_pf()
    # Backend is automatically closed when exiting the context

​
Enumerations

​
StringValueType

Enumeration of string value types that can be retrieved from the backend.
ValueDescription
VOLTAGE_LEVEL_NAMENames of voltage levels
LOAD_NAMENames of loads
GENERATOR_NAMENames of generators
SHUNT_NAMENames of shunt compensators
BRANCH_NAMENames of branches (lines and transformers)

​
IntegerValueType

Enumeration of integer value types that can be retrieved from the backend.
ValueDescription
LOAD_VOLTAGE_LEVEL_NUMVoltage level numbers for loads
GENERATOR_VOLTAGE_LEVEL_NUMVoltage level numbers for generators
SHUNT_VOLTAGE_LEVEL_NUMVoltage level numbers for shunts
BRANCH_VOLTAGE_LEVEL_NUM_1Voltage level numbers for branch side 1
BRANCH_VOLTAGE_LEVEL_NUM_2Voltage level numbers for branch side 2
SHUNT_LOCAL_BUSLocal bus numbers for shunts
TOPO_VECTTopology vector (bus connections for all elements)

​
DoubleValueType

Enumeration of double value types that can be retrieved from the backend.
ValueDescription
LOAD_PLoad active power (MW)
LOAD_QLoad reactive power (MVar)
LOAD_VLoad voltage magnitude (kV)
LOAD_ANGLELoad voltage angle (degrees)
GENERATOR_PGenerator active power (MW)
GENERATOR_QGenerator reactive power (MVar)
GENERATOR_VGenerator voltage magnitude (kV)
GENERATOR_ANGLEGenerator voltage angle (degrees)
SHUNT_PShunt active power (MW)
SHUNT_QShunt reactive power (MVar)
SHUNT_VShunt voltage magnitude (kV)
SHUNT_ANGLEShunt voltage angle (degrees)
BRANCH_P1Branch active power at side 1 (MW)
BRANCH_P2Branch active power at side 2 (MW)
BRANCH_Q1Branch reactive power at side 1 (MVar)
BRANCH_Q2Branch reactive power at side 2 (MVar)
BRANCH_V1Branch voltage magnitude at side 1 (kV)
BRANCH_V2Branch voltage magnitude at side 2 (kV)
BRANCH_ANGLE1Branch voltage angle at side 1 (degrees)
BRANCH_ANGLE2Branch voltage angle at side 2 (degrees)
BRANCH_I1Branch current at side 1 (A)
BRANCH_I2Branch current at side 2 (A)
BRANCH_PERMANENT_LIMIT_ABranch permanent current limit (A)

​
UpdateDoubleValueType

Enumeration of double value types that can be updated in the backend.
ValueDescription
UPDATE_LOAD_PUpdate load active power setpoint
UPDATE_LOAD_QUpdate load reactive power setpoint
UPDATE_GENERATOR_PUpdate generator active power setpoint
UPDATE_GENERATOR_VUpdate generator voltage setpoint

​
UpdateIntegerValueType

Enumeration of integer value types that can be updated in the backend.
ValueDescription
UPDATE_LOAD_BUSUpdate load bus connection
UPDATE_GENERATOR_BUSUpdate generator bus connection
UPDATE_SHUNT_BUSUpdate shunt bus connection
UPDATE_BRANCH_BUS1Update branch side 1 bus connection
UPDATE_BRANCH_BUS2Update branch side 2 bus connection

​
Example Usage

​
Complete Grid2Op Integration

from pypowsybl.network import Network
from pypowsybl.grid2op import Backend, DoubleValueType, UpdateDoubleValueType
import numpy as np

# Load a network
network = Network.load("ieee14.xiidm")

# Create Grid2Op backend
with Backend(network, buses_per_voltage_level=2) as backend:
    # Get current state
    load_p = backend.get_double_value(DoubleValueType.LOAD_P)
    gen_p = backend.get_double_value(DoubleValueType.GENERATOR_P)
    
    print(f"Initial loads: {load_p}")
    print(f"Initial generation: {gen_p}")
    
    # Modify loads
    new_loads = load_p * 1.1  # Increase by 10%
    changed = np.ones(len(new_loads), dtype=int)
    backend.update_double_value(UpdateDoubleValueType.UPDATE_LOAD_P, new_loads, changed)
    
    # Run power flow
    results = backend.run_pf(dc=False)
    
    for result in results:
        print(f"Component {result.connected_component_num}: {result.status}")
        print(f"Iterations: {result.iteration_count}")
    
    # Get updated state
    branch_p1 = backend.get_double_value(DoubleValueType.BRANCH_P1)
    print(f"Branch flows: {branch_p1}")

​
Topology Manipulation

from pypowsybl.grid2op import (
    Backend, IntegerValueType, UpdateIntegerValueType
)
import numpy as np

with Backend(network) as backend:
    # Get current topology
    topo_vect = backend.get_integer_value(IntegerValueType.TOPO_VECT)
    print(f"Current topology: {topo_vect}")
    
    # Switch generator to different bus
    gen_buses = np.array([2, 1, 1])  # Move first generator to bus 2
    changed = np.array([1, 0, 0])  # Only first generator changed
    backend.update_integer_value(
        UpdateIntegerValueType.UPDATE_GENERATOR_BUS, 
        gen_buses, 
        changed
    )
    
    # Validate the topology
    is_valid = backend.check_isolated_and_disconnected_injections()
    if is_valid:
        print("Topology is valid")
        results = backend.run_pf()
    else:
        print("Invalid topology: isolated or disconnected injections")

Build docs developers (and LLMs) love

Get started for freeTalk to us