GridConnect

GridConnect connects simulated building electricity demand to representative distribution networks and prepares pandapower networks for electrical studies.

Full reference documentation: https://pages.persee.minesparis.psl.eu/planeterr/gridconnect/.

Main APIs

BuildingBusMatcher

BuildingBusMatcher assigns simulated buildings to the low- or medium-voltage buses of a named pandapower feeder. It uses building, demand-profile, district, and ORE line-geometry datasets, and returns a feeder-specific connection table.

from gridconnect.api.building_bus_matcher import BuildingBusMatcher
from gridconnect.matching.config import BuildingBusMatchConfig

matcher = BuildingBusMatcher(network, BuildingBusMatchConfig(...))
connections = matcher.run()

connections is a pandas/GeoPandas DataFrame with this stable schema:

NetworkManager

NetworkManager is the stateful API for populating a pandapower network with loads, evaluating constraints, and applying corrective actions. Load creation, load shifting, reinforcement, and reconfiguration modify the managed network.

from gridconnect.api.manager import NetworkManager

manager = NetworkManager.from_network(network)
load_profiles = manager.create_loads(
    connections=connections,
    profiles=profiles,
)
constraints = manager.run_power_flow()

Key operations:

• create_loads(...) imports one network load per valid building connection.
• run_power_flow(...) runs AC power flow and returns constraint results. If some steps fail, valid results are retained for converged steps, converged is False, and failed_time_steps identifies the unavailable profile rows.
• run_power_proxy(...) screens constraints using the power-proxy method.
• run_load_shift(process) applies a selected mv, trafo, line, bus, or voltage_risk load-shifting process.
• run_reinforcement(...) reinforces constrained lines and/or transformers.
• run_reconfiguration(...) screens all profile rows with the power proxy and validates selected rows with AC power flow before iterating load shifting and reinforcement. After every network change, it re-screens all active profiles, selects fresh critical rows (or highest-power fallback rows), and validates them with AC power flow. If AC validation fails, it retains the fresh full-profile proxy constraints. It returns constraints before and after the process plus accumulated changes.

Input data

GridConnect expects a named pandapower distribution network plus the following data. Default paths are configurable through BuildingBusMatchConfig and NetworkManager.

For in-memory load creation, pass both DataFrames together:

manager.create_loads(connections=connections, profiles=profiles)

For file-based loading, provide a connection Parquet file and a directory of district profile files:

manager.create_loads(
    building_bus_file="path/to/building_bus_match.parquet",
    load_profiles_dir="path/to/load_profiles",
)

Output data

The matching workflow produces a building-to-bus connection table. The network workflow adds loads to the supplied pandapower network and returns typed result containers containing:

• Time-indexed load profiles and maximum load powers.
• Line-current, transformer-power, and bus-voltage constraint results.
• Load-shift events and line/transformer reinforcement records.
• Network snapshots and before/after reconfiguration comparisons.

Power values are represented in MW, Mvar, or MVA as named; line current is in kA, voltage is per unit, and matching distance is in metres.

Build the full documentation

Install the documentation dependencies from the repository root:

uv sync --extra docs

Preview the documentation locally:

uv run mkdocs serve

Build the deployable static site with strict validation:

uv run mkdocs build --strict

The generated site is written to site/.