gridconnect 0.2.0__tar.gz

gridconnect-0.2.0/LICENSE

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+=====================
+
+- Copyright © `2026` `Yoann CHICHE`
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

gridconnect-0.2.0/PKG-INFO

@@ -0,0 +1,163 @@
+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/`.

gridconnect-0.2.0/README.md

@@ -0,0 +1,135 @@
+# 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/`.

gridconnect-0.2.0/gridconnect/analysis/__init__.py

@@ -0,0 +1,6 @@
+"""Analysis processes for evaluating and relieving network constraints.
+
+This package exposes AC power-flow, approximate power-proxy, reinforcement,
+load-shifting, and reconfiguration workflows. They operate on pandapower
+networks; powers use MW, Mvar, and MVA as named by their fields.
+"""