gridconnect 0.2.0__tar.gz → 0.2.2__tar.gz

gridconnect-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 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 → gridconnect-0.2.2}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: gridconnect
-Version: 0.2.0
+Version: 0.2.2
 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>
+License-Expression: MIT
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -105,7 +106,7 @@ data. Default paths are configurable through `BuildingBusMatchConfig` and
 | 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). |
+| Load profiles | `energy_model_static_<district>.parquet` and `energy_model_hourly_<district>.parquet` (`building_eload` >= 0.6.0), or a single legacy `energy_model_<district>.parquet` | Static: `building_id`, `name`, `main_usage`, `district`, `total_electricity_need`, and `floor_area`. Hourly: `building_id`, `datetime`, and `electricity_need` (kW). A legacy file holds all of these columns. |
 | 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. |

{gridconnect-0.2.0 → gridconnect-0.2.2}/README.md

@@ -77,7 +77,7 @@ data. Default paths are configurable through `BuildingBusMatchConfig` and
 | 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). |
+| Load profiles | `energy_model_static_<district>.parquet` and `energy_model_hourly_<district>.parquet` (`building_eload` >= 0.6.0), or a single legacy `energy_model_<district>.parquet` | Static: `building_id`, `name`, `main_usage`, `district`, `total_electricity_need`, and `floor_area`. Hourly: `building_id`, `datetime`, and `electricity_need` (kW). A legacy file holds all of these columns. |
 | 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. |

gridconnect-0.2.2/gridconnect/io/__init__.py

@@ -0,0 +1,6 @@
+"""Input and output conversion helpers for GridConnect datasets.
+
+The package provides conversion of serialized-geometry CSV input to GeoParquet
+for the building-to-bus matching workflow, and reading of per-district building
+energy profiles in both ``building_eload`` output layouts.
+"""

gridconnect-0.2.2/gridconnect/io/profiles.py

@@ -0,0 +1,116 @@
+"""Locate and read per-district building energy profiles.
+
+``building_eload`` >= 0.6.0 writes each district's output as separate
+``energy_model_static_<district>.parquet`` (one row per building) and
+``energy_model_hourly_<district>.parquet`` (one row per building and hour)
+files. Earlier versions wrote a single denormalized
+``energy_model_<district>.parquet`` file. Both layouts are supported; the split
+layout takes precedence when both are present.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import polars as pl
+
+STATIC_COLUMNS = (
+    "building_id",
+    "name",
+    "main_usage",
+    "district",
+    "total_electricity_need",
+    "floor_area",
+)
+HOURLY_COLUMNS = ("building_id", "datetime", "electricity_need")
+
+logger = logging.getLogger(__name__)
+
+
+def static_profile_path(profile_dir: str | Path, district: str) -> Path:
+    """Return the split-layout static profile path of one district."""
+    return Path(profile_dir) / f"energy_model_static_{district}.parquet"
+
+
+def hourly_profile_path(profile_dir: str | Path, district: str) -> Path:
+    """Return the split-layout hourly profile path of one district."""
+    return Path(profile_dir) / f"energy_model_hourly_{district}.parquet"
+
+
+def legacy_profile_path(profile_dir: str | Path, district: str) -> Path:
+    """Return the single-file (pre-0.6.0) profile path of one district."""
+    return Path(profile_dir) / f"energy_model_{district}.parquet"
+
+
+def has_district_profiles(profile_dir: str | Path, district: str) -> bool:
+    """Return whether a directory holds profiles of one district in any layout."""
+    return (
+        static_profile_path(profile_dir, district).exists()
+        and hourly_profile_path(profile_dir, district).exists()
+    ) or legacy_profile_path(profile_dir, district).exists()
+
+
+def scan_district_profiles(
+    profile_dir: str | Path, district: str
+) -> pl.LazyFrame | None:
+    """Lazily read one district's hourly profiles with per-building attributes.
+
+    Args:
+        profile_dir: Directory containing district profile files.
+        district: District identifier.
+
+    Returns:
+        Lazy frame with at least the ``HOURLY_COLUMNS`` and ``STATIC_COLUMNS``
+        columns, or ``None`` when no profile file exists for the district.
+        ``electricity_need`` is passed through in kW.
+
+    Raises:
+        ValueError: If a split-layout file lacks a required column.
+    """
+    static_file = static_profile_path(profile_dir, district)
+    hourly_file = hourly_profile_path(profile_dir, district)
+    if static_file.exists() and hourly_file.exists():
+        return _scan_split_profiles(static_file, hourly_file)
+
+    legacy_file = legacy_profile_path(profile_dir, district)
+    if legacy_file.exists():
+        return pl.scan_parquet(legacy_file)
+
+    if static_file.exists() or hourly_file.exists():
+        logger.warning(
+            "Incomplete split profiles for district %s in '%s': both '%s' and "
+            "'%s' are required.",
+            district,
+            profile_dir,
+            static_file.name,
+            hourly_file.name,
+        )
+    return None
+
+
+def _scan_split_profiles(static_file: Path, hourly_file: Path) -> pl.LazyFrame:
+    """Join split-layout hourly rows to their static building attributes."""
+    static = pl.scan_parquet(static_file)
+    hourly = pl.scan_parquet(hourly_file)
+    for frame, columns, file in (
+        (static, STATIC_COLUMNS, static_file),
+        (hourly, HOURLY_COLUMNS, hourly_file),
+    ):
+        missing = sorted(set(columns).difference(frame.collect_schema().names()))
+        if missing:
+            raise ValueError(
+                f"'{file}' is missing required column(s): {', '.join(missing)}."
+            )
+
+    # Keep the join one-to-many even if several rows share a building_id.
+    static = static.select(STATIC_COLUMNS).unique(
+        subset="building_id", keep="first", maintain_order=True
+    )
+    return (
+        hourly.select(HOURLY_COLUMNS)
+        .join(static, on="building_id", how="inner")
+        # building_eload stores district as Categorical; downstream merges
+        # compare it against plain strings.
+        .with_columns(pl.col("district").cast(pl.String))
+    )

{gridconnect-0.2.0 → gridconnect-0.2.2}/gridconnect/matching/data.py

@@ -18,10 +18,13 @@ except ImportError:  # pragma: no cover - optional runtime dependency
 import geopandas as gpd
 import numpy as np
 import pandas as pd
+import polars as pl
 from shapely import wkb
 from shapely.geometry import Point
 from tqdm import tqdm
 
+from gridconnect.io.profiles import scan_district_profiles
+
 KW_TO_MW = 1000.0
 REACTIVE_POWER_FACTOR = 0.3
 
@@ -284,13 +287,6 @@ class MatchingDataLoader:
     def _load_energy_profiles(self) -> pd.DataFrame:
         """Load and aggregate building energy profiles."""
         aggregated_frames: list[pd.DataFrame] = []
-        columns = [
-            "name",
-            "building_id",
-            "total_electricity_need",
-            "electricity_need",
-            "floor_area",
-        ]
         for district_id in tqdm(
             self.district_ids,
             desc="Loading energy profiles",
@@ -298,24 +294,32 @@ class MatchingDataLoader:
             colour="green",
             disable=not logger.isEnabledFor(logging.DEBUG),
         ):
-            file_path = self.profiles_dir / f"energy_model_{district_id}.parquet"
-            if not file_path.exists():
+            profiles = scan_district_profiles(self.profiles_dir, district_id)
+            if profiles is None:
                 logger.warning(
-                    "Energy profile file not found: '%s' (district %s).",
+                    "Energy profile file(s) not found in '%s' (district %s).",
+                    self.profiles_dir,
                     district_id,
-                    file_path,
                 )
                 continue
-            district_df = pd.read_parquet(file_path, columns=columns)
-            if district_df.empty:
-                continue
-            aggregated = district_df.groupby(
-                ["name", "building_id"], as_index=False
-            ).agg(
-                annual_energy_mwh=("total_electricity_need", "first"),
-                peak_active_power_mw=("electricity_need", "max"),
-                floor_area=("floor_area", "first"),
+            aggregated = (
+                profiles.with_columns(
+                    pl.col(
+                        "total_electricity_need", "electricity_need", "floor_area"
+                    ).cast(pl.Float64)
+                )
+                .group_by(["name", "building_id"])
+                .agg(
+                    annual_energy_mwh=pl.col("total_electricity_need").first(),
+                    peak_active_power_mw=pl.col("electricity_need").max(),
+                    floor_area=pl.col("floor_area").first(),
+                )
+                .sort(["name", "building_id"])
+                .collect()
+                .to_pandas()
             )
+            if aggregated.empty:
+                continue
             aggregated["annual_energy_mwh"] /= KW_TO_MW
             aggregated["peak_active_power_mw"] /= KW_TO_MW
             aggregated["peak_reactive_power_mvar"] = (
@@ -418,7 +422,12 @@ class MatchingDataLoader:
                 crs=self.metric_crs,
             )
 
-        df["geometry"] = df["geometry"].apply(lambda geom: wkb.loads(bytes(geom)))
+        # DuckDB guarantees no row order without ORDER BY, and bus ids below are
+        # positional: sort on row content so ids are stable across runs.
+        df["geometry"] = df["geometry"].map(bytes)
+        sort_columns = ["geometry"] + (["TENSION"] if "TENSION" in df.columns else [])
+        df = df.sort_values(sort_columns, kind="mergesort").reset_index(drop=True)
+        df["geometry"] = df["geometry"].apply(wkb.loads)
         df["geometry"] = df["geometry"].apply(
             lambda geom: (
                 Point(geom.coords[-1])

{gridconnect-0.2.0 → gridconnect-0.2.2}/gridconnect/network/loads.py

@@ -17,6 +17,7 @@ import polars as pl
 from tqdm import tqdm
 
 from gridconnect.api.building_bus_matcher import CONNECTIONS_COLUMNS
+from gridconnect.io.profiles import has_district_profiles, scan_district_profiles
 from gridconnect.results.loads import LoadProfiles
 
 CONNECTION_MATCH_KEYS = (
@@ -313,15 +314,16 @@ class NetworkLoadBuilder:
             unit="district",
             disable=not VERBOSE,
         ):
-            file = profile_dir / f"energy_model_{district}.parquet"
-            if not file.exists():
-                file = (
-                    profile_dir
-                    / f"{self.network.name}"
-                    / f"energy_model_{district}.parquet"
+            district_dir = profile_dir
+            if not has_district_profiles(district_dir, district):
+                district_dir = profile_dir / f"{self.network.name}"
+            profiles = scan_district_profiles(district_dir, district)
+            if profiles is None:
+                logger.warning(
+                    "Profile file(s) not found for district %s in '%s'.",
+                    district,
+                    district_dir,
                 )
-            if not file.exists():
-                logger.warning("Profile file not found: %s.", file)
                 continue
 
             district_buildings = (
@@ -332,12 +334,12 @@ class NetworkLoadBuilder:
                 .drop_duplicates()
                 .rename(columns={"cleabs": "name"})
             )
-            dfs.append(self._import_profile(file, district_buildings))
+            dfs.append(self._import_profile(profiles, district_buildings))
 
         if not dfs:
             return pd.DataFrame(columns=LOAD_COLUMNS)
         logger.debug("Concatenating profile(s) read from files.")
-        return pl.concat(dfs).to_pandas()
+        return pl.concat(dfs, how="vertical_relaxed").to_pandas()
 
     def _load_profiles_from_frame(
         self,
@@ -379,36 +381,32 @@ class NetworkLoadBuilder:
         )
         return filtered
 
-    def _import_profile(self, file, building_pairs):
-        """Read one parquet file and filter on exact (name, building_id) pairs."""
-        try:
-            if building_pairs.empty:
-                return pd.DataFrame(columns=LOAD_COLUMNS)
-
-            building_pairs = (
-                pl.from_pandas(building_pairs)
-                .lazy()
-                .with_columns(pl.col("building_id").cast(pl.Int64))
-            )
+    def _import_profile(
+        self, profiles: pl.LazyFrame, building_pairs: pd.DataFrame
+    ) -> pl.DataFrame:
+        """Filter one district's profiles on exact (name, building_id) pairs."""
+        if building_pairs.empty:
+            return pl.DataFrame(schema=LOAD_COLUMNS)
 
-            df = (
-                pl.scan_parquet(file)
-                .with_columns(pl.col("building_id").cast(pl.Int64))
-                .join(building_pairs, on=["name", "building_id"], how="inner")
-                .select(LOAD_COLUMNS)
-                .collect()
-            ).with_columns(
-                electricity_need=pl.col("electricity_need") / KW_TO_MW,
-            )
+        building_pairs = (
+            pl.from_pandas(building_pairs)
+            .lazy()
+            .with_columns(pl.col("building_id").cast(pl.Int64))
+        )
 
-            unique_buildings = len(df["building_id"].unique())
+        df = (
+            profiles.with_columns(pl.col("building_id").cast(pl.Int64))
+            .join(building_pairs, on=["name", "building_id"], how="inner")
+            .select(LOAD_COLUMNS)
+            .collect()
+        ).with_columns(
+            electricity_need=pl.col("electricity_need").cast(pl.Float64) / KW_TO_MW,
+        )
 
-            logger.debug(f"Loaded {unique_buildings} profile(s) from '{file.name}'.")
-            return df
+        unique_buildings = len(df["building_id"].unique())
 
-        except FileNotFoundError as e:
-            logger.error(f"Error importing profiles from '{file.name}': {e}.")
-            return pd.DataFrame(columns=LOAD_COLUMNS)
+        logger.debug(f"Loaded {unique_buildings} profile(s).")
+        return df
 
     def format_profiles(
         self,

{gridconnect-0.2.0 → gridconnect-0.2.2}/gridconnect.egg-info/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: gridconnect
-Version: 0.2.0
+Version: 0.2.2
 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>
+License-Expression: MIT
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -105,7 +106,7 @@ data. Default paths are configurable through `BuildingBusMatchConfig` and
 | 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). |
+| Load profiles | `energy_model_static_<district>.parquet` and `energy_model_hourly_<district>.parquet` (`building_eload` >= 0.6.0), or a single legacy `energy_model_<district>.parquet` | Static: `building_id`, `name`, `main_usage`, `district`, `total_electricity_need`, and `floor_area`. Hourly: `building_id`, `datetime`, and `electricity_need` (kW). A legacy file holds all of these columns. |
 | 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. |

{gridconnect-0.2.0 → gridconnect-0.2.2}/gridconnect.egg-info/SOURCES.txt

@@ -17,6 +17,7 @@ gridconnect/api/building_bus_matcher.py
 gridconnect/api/manager.py
 gridconnect/io/__init__.py
 gridconnect/io/conversion.py
+gridconnect/io/profiles.py
 gridconnect/matching/__init__.py
 gridconnect/matching/area.py
 gridconnect/matching/buses.py

{gridconnect-0.2.0 → gridconnect-0.2.2}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=68", "wheel"]
+requires = ["setuptools>=77", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools.packages.find]
@@ -8,7 +8,7 @@ include = ["gridconnect*"]
 [project]
 name = "gridconnect"
 
-version = "0.2.0"
+version = "0.2.2"
 description = "A package for connecting building-scale load profiles to distribution networks and preparing simulation-ready network models."
 
 authors = [
@@ -17,6 +17,8 @@ authors = [
 
 readme = "README.md"
 requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
 
 dependencies = [
     "networkx",

gridconnect-0.2.0/LICENSE

@@ -1,25 +0,0 @@
-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/gridconnect/io/__init__.py

@@ -1,5 +0,0 @@
-"""Input and output conversion helpers for GridConnect datasets.
-
-The package currently provides conversion of serialized-geometry CSV input to
-GeoParquet for the building-to-bus matching workflow.
-"""