Metadata-Version: 2.4
Name: gridconnect
Version: 0.2.0
Summary: A package for connecting building-scale load profiles to distribution networks and preparing simulation-ready network models.
Author-email: Yoann Chiche <yoann.chiche@minesparis.psl.eu>
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: networkx
Requires-Dist: polars
Requires-Dist: pandas==2.3.3
Requires-Dist: geopandas
Requires-Dist: pandapower==3.2.1
Requires-Dist: numba
Requires-Dist: colorlog
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: folium
Requires-Dist: seaborn
Requires-Dist: scipy
Requires-Dist: jupyter
Requires-Dist: fastparquet
Requires-Dist: pyarrow
Requires-Dist: duckdb
Provides-Extra: maps
Requires-Dist: contextily; extra == "maps"
Dynamic: license-file

# GridConnect

[![Python](https://img.shields.io/badge/python-3.13%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![Package manager](https://img.shields.io/badge/package%20manager-uv-6E56CF?logo=uv&logoColor=white)](https://docs.astral.sh/uv/)
[![Tests](https://img.shields.io/badge/tests-pytest-0A9EDC?logo=pytest&logoColor=white)](tests/)

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/](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.

```python
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:

| Field | Description |
| --- | --- |
| `cleabs`, `building_id`, `main_usage`, `floor_area` | Building identifiers and characteristics. |
| `annual_energy_mwh`, `peak_active_power_mw`, `peak_reactive_power_mvar`, `peak_apparent_power_mva` | Building demand. |
| `district`, `mv_feeder` | Source district and target feeder. |
| `bus`, `voltage_level`, `grid_distance` | Selected bus, LV/MV assignment, and connection distance in metres. |

### `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.

```python
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`.

| Input | Format | Required content |
| --- | --- | --- |
| Building data | District Parquet files | Building identifiers, geometry, usage, and floor area. |
| Load profiles | `energy_model_<district>.parquet` | `datetime`, `building_id`, `name`, `main_usage`, `district`, and `electricity_need` (kW). |
| Building-to-bus connections | Parquet or DataFrame | The connection schema returned by `BuildingBusMatcher`. |
| District areas | Parquet | District geometry used to resolve the feeder study area. |
| ORE network geometries | Parquet | Low- and medium-voltage overhead and underground line geometries. |

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

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

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

```python
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:

```bash
uv sync --extra docs
```

Preview the documentation locally:

```bash
uv run mkdocs serve
```

Build the deployable static site with strict validation:

```bash
uv run mkdocs build --strict
```

The generated site is written to `site/`.
