building-eload 0.5.0__tar.gz

building_eload-0.5.0/LICENCE.md

@@ -0,0 +1,27 @@
+The MIT License (MIT)
+=====================
+
+- Copyright © `2025` `Yoann Chiche`
+- Copyright © `2025` `Seddik Yassine Abdelouadoud`
+- Copyright © `2025` `Anna Cocchi`
+
+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.

building_eload-0.5.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: building_eload
+Version: 0.5.0
+Summary: District-level energy hourly simulation of buildings
+Author-email: Yoann Chiche <yoann.chiche@minesparis.psl.eu>, Yassine Abdelouadoud <yassine.abdelouadoud@gmail.com>, Anna Cocchi <anna.cocchi@minesparis.psl.eu>
+Maintainer-email: Yoann Chiche <yoann.chiche@minesparis.psl.eu>, Yassine Abdelouadoud <yassine.abdelouadoud@gmail.com>
+License: The MIT License (MIT)
+        =====================
+        
+        - Copyright © `2025` `Yoann Chiche`
+        - Copyright © `2025` `Seddik Yassine Abdelouadoud`
+        - Copyright © `2025` `Anna Cocchi`
+        
+        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.
+        
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: <4.0.0,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENCE.md
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: polars
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: seaborn
+Requires-Dist: scikit-learn
+Requires-Dist: geopandas
+Requires-Dist: shapely
+Requires-Dist: xarray
+Requires-Dist: netcdf4
+Requires-Dist: tqdm
+Requires-Dist: fastcluster
+Requires-Dist: ladybug-core
+Requires-Dist: colorlog
+Requires-Dist: requests
+Requires-Dist: py7zr
+Requires-Dist: pyproj
+Requires-Dist: buildingmodel
+Requires-Dist: buildingdata[era5]>=0.2.0
+Provides-Extra: maps
+Requires-Dist: contextily; extra == "maps"
+Requires-Dist: folium; extra == "maps"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: ipykernel; extra == "dev"
+Dynamic: license-file
+
+# Building_eload
+
+**Version:** `0.4.0`
+
+![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
+![PyPI](https://img.shields.io/pypi/v/building_eload)
+![Pipeline](https://git.persee.minesparis.psl.eu/planeterr/building_eload/badges/main/pipeline.svg)
+
+District-level building energy simulation at hourly resolution.
+
+This model was first presented in the research article : <https://doi.org/10.1016/j.enbuild.2026.117409>
+
+`building_eload` is developed as a **library**, released on PyPI. The Snakemake
+workflow reproducing the paper's results lives in a separate repository
+(`building_eload_paper`), pinned to the published `0.4.x` releases of this
+package.
+
+## Overview
+
+`building_eload` runs a two-stage pipeline:
+
+1. Static simulation: annual building-level energy estimates and calibration.
+2. Dynamic simulation: hourly electricity load profiles from static outputs.
+
+Main dependency:
+
+- `buildingmodel` (for static building physics simulation)
+
+## Installation
+
+```bash
+git clone https://git.persee.minesparis.psl.eu/planeterr/building_eload.git
+cd building_eload
+pip install -e .
+```
+
+If needed by your workflow, also install `buildingmodel` in editable mode.
+
+## Data Paths Exposed by the Package
+
+Defined in `building_eload/__init__.py`:
+
+- `data_path["data"]`
+- `data_path["bdtopo"]`
+- `data_path["elmas"]`
+- `data_path["simulation"]`
+- `data_path["activity_calendar"]`
+- `data_path["validation"]`
+- `data_path["climate"]`
+- `data_path["representative_districts"]`
+- `plot_path`
+- `download_link`
+
+## Data Layout
+
+The `data/` directory is **not tracked in git** (multi-GB). All paths in
+`data_path` resolve relative to the repository root:
+
+```
+data/
+├── activity_calendar/          # occupant activity calendars (10-min time step)
+├── bdtopo/                     # BDTOPO building footprints (downloaded per region)
+├── calibration/                # static-model calibration outputs
+├── climate/                    # ERA5-derived weather files (see scripts/climate)
+├── elecdom/                    # Elecdom appliance panel data
+├── elmas/                      # ELMAS dataset
+├── representative_districts/   # clustering outputs (medoid districts)
+├── simulation/                 # static + dynamic simulation results
+└── validation/                 # ORE / Enedis / RTE measured consumption
+```
+
+Download sources are listed in `building_eload.download_link` (BDTOPO regions,
+district list, occupant diaries, ORE annual consumption, ELMAS); helpers live
+in `building_eload.utils.data_download`. Reference data (districts, BDTOPO
+fallback) is otherwise fetched through the `buildingdata` package. The unit
+test suite runs without `data/`; the integration tests
+(`StaticSimulation`/`DynamicSimulation`/validation runs) require it.
+
+## Current Core API
+
+### Static simulation (`building_eload.core.static_simulation`)
+
+Main classes:
+
+- `StaticParameters`
+- `StaticSimulation`
+- `StaticResults`
+- `BuildingModelResults`
+- `StaticProcessor`
+
+Primary methods used by users:
+
+- `StaticSimulation.run()`
+- `StaticSimulation.run_energy_demand()`
+- `StaticResults.save_results(save_dict: Optional[dict[str, bool]] = None)`
+
+### Dynamic simulation (`building_eload.core.dynamic_simulation`)
+
+Main classes:
+
+- `DynamicParameters`
+- `DynamicSimulation`
+
+Primary methods used by users:
+
+- `DynamicSimulation.from_files(district_id, parameters)`
+- `DynamicSimulation.from_static_results(static_results, parameters)`
+- `DynamicSimulation.run()`
+- `DynamicSimulation.save_results()`
+- `DynamicSimulation.plot_results(...)`
+
+## Minimal Usage
+
+Tutorials for both simulation processes are available in : `/doc/tutorials`
+
+### 1) Static simulation
+
+```python
+import numpy as np
+from building_eload.core.static_simulation import StaticParameters, StaticSimulation
+
+
+district_id = "262320000"
+eu = np.arange(0.7, 1.3, 0.05).round(2)
+hs = np.arange(16.0, 22.5, 0.5).round(1)
+energy_use_parameters = [
+    {"actual_heating_set_point": hs[i], "energy_use_factor": eu[i]}
+    for i in range(len(hs))
+]
+
+params = StaticParameters(
+    n_inference=10,
+    calibration_year=2023,
+    climate_year=None,
+    energy_use_parameters=energy_use_parameters,
+)
+
+sim = StaticSimulation(district_id=district_id, parameters=params)
+results = sim.run()
+results.save_results()
+```
+
+### 2) Dynamic simulation
+
+```python
+from building_eload.core.dynamic_simulation import DynamicParameters, DynamicSimulation
+
+
+district_id = "262320000"
+params = DynamicParameters(
+    year=2023,
+    run_non_residential=True,
+    run_again=True,
+)
+
+sim = DynamicSimulation.from_files(district_id=district_id, parameters=params)
+sim.run()
+sim.save_results()
+```
+
+## Script Entry Points (Current)
+
+- Static simulation:
+
+```bash
+python -m building_eload.scripts.simulation.static.run
+```
+
+- Parallel static simulation:
+
+```bash
+python -m building_eload.scripts.simulation.static.run_parallel
+```
+
+- Dynamic simulation:
+
+```bash
+python -m building_eload.scripts.simulation.dynamic.run
+```
+
+- Parallel dynamic simulation:
+
+```bash
+python -m building_eload.scripts.simulation.dynamic.run_parallel
+```
+
+- Validation:
+
+```bash
+python -m building_eload.scripts.validation.run
+```
+
+- Climate preprocessing:
+
+```bash
+python -m building_eload.scripts.climate.generate_climates
+```

building_eload-0.5.0/README.md

@@ -0,0 +1,197 @@
+# Building_eload
+
+**Version:** `0.4.0`
+
+![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
+![PyPI](https://img.shields.io/pypi/v/building_eload)
+![Pipeline](https://git.persee.minesparis.psl.eu/planeterr/building_eload/badges/main/pipeline.svg)
+
+District-level building energy simulation at hourly resolution.
+
+This model was first presented in the research article : <https://doi.org/10.1016/j.enbuild.2026.117409>
+
+`building_eload` is developed as a **library**, released on PyPI. The Snakemake
+workflow reproducing the paper's results lives in a separate repository
+(`building_eload_paper`), pinned to the published `0.4.x` releases of this
+package.
+
+## Overview
+
+`building_eload` runs a two-stage pipeline:
+
+1. Static simulation: annual building-level energy estimates and calibration.
+2. Dynamic simulation: hourly electricity load profiles from static outputs.
+
+Main dependency:
+
+- `buildingmodel` (for static building physics simulation)
+
+## Installation
+
+```bash
+git clone https://git.persee.minesparis.psl.eu/planeterr/building_eload.git
+cd building_eload
+pip install -e .
+```
+
+If needed by your workflow, also install `buildingmodel` in editable mode.
+
+## Data Paths Exposed by the Package
+
+Defined in `building_eload/__init__.py`:
+
+- `data_path["data"]`
+- `data_path["bdtopo"]`
+- `data_path["elmas"]`
+- `data_path["simulation"]`
+- `data_path["activity_calendar"]`
+- `data_path["validation"]`
+- `data_path["climate"]`
+- `data_path["representative_districts"]`
+- `plot_path`
+- `download_link`
+
+## Data Layout
+
+The `data/` directory is **not tracked in git** (multi-GB). All paths in
+`data_path` resolve relative to the repository root:
+
+```
+data/
+├── activity_calendar/          # occupant activity calendars (10-min time step)
+├── bdtopo/                     # BDTOPO building footprints (downloaded per region)
+├── calibration/                # static-model calibration outputs
+├── climate/                    # ERA5-derived weather files (see scripts/climate)
+├── elecdom/                    # Elecdom appliance panel data
+├── elmas/                      # ELMAS dataset
+├── representative_districts/   # clustering outputs (medoid districts)
+├── simulation/                 # static + dynamic simulation results
+└── validation/                 # ORE / Enedis / RTE measured consumption
+```
+
+Download sources are listed in `building_eload.download_link` (BDTOPO regions,
+district list, occupant diaries, ORE annual consumption, ELMAS); helpers live
+in `building_eload.utils.data_download`. Reference data (districts, BDTOPO
+fallback) is otherwise fetched through the `buildingdata` package. The unit
+test suite runs without `data/`; the integration tests
+(`StaticSimulation`/`DynamicSimulation`/validation runs) require it.
+
+## Current Core API
+
+### Static simulation (`building_eload.core.static_simulation`)
+
+Main classes:
+
+- `StaticParameters`
+- `StaticSimulation`
+- `StaticResults`
+- `BuildingModelResults`
+- `StaticProcessor`
+
+Primary methods used by users:
+
+- `StaticSimulation.run()`
+- `StaticSimulation.run_energy_demand()`
+- `StaticResults.save_results(save_dict: Optional[dict[str, bool]] = None)`
+
+### Dynamic simulation (`building_eload.core.dynamic_simulation`)
+
+Main classes:
+
+- `DynamicParameters`
+- `DynamicSimulation`
+
+Primary methods used by users:
+
+- `DynamicSimulation.from_files(district_id, parameters)`
+- `DynamicSimulation.from_static_results(static_results, parameters)`
+- `DynamicSimulation.run()`
+- `DynamicSimulation.save_results()`
+- `DynamicSimulation.plot_results(...)`
+
+## Minimal Usage
+
+Tutorials for both simulation processes are available in : `/doc/tutorials`
+
+### 1) Static simulation
+
+```python
+import numpy as np
+from building_eload.core.static_simulation import StaticParameters, StaticSimulation
+
+
+district_id = "262320000"
+eu = np.arange(0.7, 1.3, 0.05).round(2)
+hs = np.arange(16.0, 22.5, 0.5).round(1)
+energy_use_parameters = [
+    {"actual_heating_set_point": hs[i], "energy_use_factor": eu[i]}
+    for i in range(len(hs))
+]
+
+params = StaticParameters(
+    n_inference=10,
+    calibration_year=2023,
+    climate_year=None,
+    energy_use_parameters=energy_use_parameters,
+)
+
+sim = StaticSimulation(district_id=district_id, parameters=params)
+results = sim.run()
+results.save_results()
+```
+
+### 2) Dynamic simulation
+
+```python
+from building_eload.core.dynamic_simulation import DynamicParameters, DynamicSimulation
+
+
+district_id = "262320000"
+params = DynamicParameters(
+    year=2023,
+    run_non_residential=True,
+    run_again=True,
+)
+
+sim = DynamicSimulation.from_files(district_id=district_id, parameters=params)
+sim.run()
+sim.save_results()
+```
+
+## Script Entry Points (Current)
+
+- Static simulation:
+
+```bash
+python -m building_eload.scripts.simulation.static.run
+```
+
+- Parallel static simulation:
+
+```bash
+python -m building_eload.scripts.simulation.static.run_parallel
+```
+
+- Dynamic simulation:
+
+```bash
+python -m building_eload.scripts.simulation.dynamic.run
+```
+
+- Parallel dynamic simulation:
+
+```bash
+python -m building_eload.scripts.simulation.dynamic.run_parallel
+```
+
+- Validation:
+
+```bash
+python -m building_eload.scripts.validation.run
+```
+
+- Climate preprocessing:
+
+```bash
+python -m building_eload.scripts.climate.generate_climates
+```

building_eload-0.5.0/building_eload/__init__.py

@@ -0,0 +1,31 @@
+from pathlib import Path
+
+# Utilisation de Path(__file__).parents[1] pour naviguer vers le bon répertoire parent
+data_path = {
+    "data": Path(__file__).parents[1] / "data",
+    "bdtopo": Path(__file__).parents[1] / "data" / "bdtopo",
+    "elmas": Path(__file__).parents[1] / "data" / "elmas",
+    "simulation": Path(__file__).parents[1] / "data" / "simulation",
+    "activity_calendar": Path(__file__).parents[1] / "data" / "activity_calendar",
+    "validation": Path(__file__).parents[1] / "data" / "validation",
+    "climate": Path(__file__).parents[1] / "data" / "climate",
+    "representative_districts": Path(__file__).parents[1] / "data" / "representative_districts",
+}
+
+plot_path = Path(__file__).parents[1] / "plot"
+
+# NOTE: the former ``download_link`` dict and ``utils.data_download`` helpers
+# (``download_and_extract``/``flatten_folder``) were removed in 0.5.0. Reference
+# dataset acquisition now belongs entirely to the ``buildingdata`` package,
+# which owns the GCS-cached download+schema contract for every dataset this
+# model consumes:
+#   - ELMAS non-residential load curves -> ``buildingdata.get_elmas(table=...)``
+#     (wired into ``models.non_residential.NonResidentialModel``)
+#   - occupant activity diaries          -> ``buildingdata.get_occupant_diaries()``
+#   - ORE per-IRIS annual consumption     -> ``buildingdata.get_ore()``
+#   - Enedis measured conso-inf36         -> ``buildingdata.get_enedis_national()`` /
+#                                            ``buildingdata.get_enedis_regional()``
+#   - IRIS districts / BDTOPO / census / DPE -> already via ``buildingdata``.
+# The old Google-Drive links silently saved Google's "file too large to scan"
+# HTML interstitial instead of the archive; moving to ``buildingdata`` closes
+# that bug. See the buildingdata CHANGELOG (0.2.0) and its doc/pending_uploads.md.

building_eload-0.5.0/building_eload/core/building_loader.py

@@ -0,0 +1,127 @@
+# building_loader.py
+
+import logging
+import warnings
+from pathlib import Path
+from typing import Optional
+
+import buildingdata
+import geopandas as gpd
+from shapely import geometry
+
+from building_eload import data_path
+
+logger = logging.getLogger(__name__)
+
+
+
+class BuildingLoader:
+    """Load buildings from a district and filter them based on intersection with the district geometry."""
+
+    INTERSECTION_THRESHOLD = 0.5
+    BUILDING_LAYER_NAME = "batiment"
+    GIS_ENGINE = "pyogrio"
+    BUILDING_FILE_PREFIX = "BDTOPO_R"
+    BUILDING_FILE_SUFFIX = ".gpkg"
+    DEFAULT_DISTRICT_DATA_FILE = None
+    DEFAULT_BUILDING_FOOTPRINT_FOLDER = Path(data_path["bdtopo"])
+
+    def __init__(self, district_id: str, district_data_file: str = None, building_footprint_folder: str = None):
+
+        self.district_id = str(district_id)
+        self.district_data_file = (
+            Path(district_data_file) if district_data_file is not None else self.DEFAULT_DISTRICT_DATA_FILE
+        )
+        self.building_footprint_folder = Path(
+            building_footprint_folder or self.DEFAULT_BUILDING_FOOTPRINT_FOLDER
+        )
+        logger.debug(f"{self.logger_header} District data file: {self.district_data_file}.")
+        logger.debug(f"{self.logger_header} Building footprint folder: {self.building_footprint_folder}.")
+
+    @property
+    def logger_header(self):
+        if self.district_id is None:
+            return "[BuildingLoader]"
+        return f"[District {self.district_id}]"
+
+    # -------------------------------------------------------
+    # Main function
+    # -------------------------------------------------------
+
+    def load_buildings(self) -> Optional[gpd.GeoDataFrame]:
+        """Load buildings for a specific district."""
+        logger.info(f"{self.logger_header} Loading buildings.")
+
+        district_data = self._load_district(self.district_id)
+        if district_data.empty:
+            logger.warning(f"{self.logger_header} District {self.district_id} not found in district file.")
+            return None
+        district_geometry = self._get_district_geometry(district_data)
+        buildings = self._load_buildings_in_district_bounds(district_geometry, district_data)
+        filtered_buildings = self._filter_buildings_on_bounds(buildings, district_geometry)
+        filtered_buildings["district"] = self.district_id
+
+        
+        logger.info(f"{self.logger_header} Loaded {len(filtered_buildings)} buildings.")
+
+        return filtered_buildings
+
+    # -------------------------------------------------------
+    # Utilis
+    # -------------------------------------------------------
+
+    def _load_district(self, district_id: str) -> gpd.GeoDataFrame:
+        district_id = str(district_id)
+        if self.district_data_file is not None:
+            districts = gpd.read_parquet(self.district_data_file)
+        else:
+            districts = buildingdata.get_districts()
+
+        district_codes = districts["district"].astype(str).str.zfill(len(district_id))
+        return districts[district_codes == district_id]
+
+    @staticmethod
+    def _get_district_geometry(district_data: gpd.GeoDataFrame) -> geometry.Polygon:
+        return district_data["geometry"].iloc[0]
+
+    def _load_buildings_in_district_bounds(
+        self, district_geometry: geometry.Polygon, district_data: gpd.GeoDataFrame
+    ) -> gpd.GeoDataFrame:
+        bounds = district_geometry.convex_hull.bounds
+        building_path = self._get_building_path(district_data)
+
+        if not building_path.exists():
+            logger.debug(
+                f"{self.logger_header} Local BDTOPO file {building_path} not found; "
+                "loading buildings through buildingdata."
+            )
+            return buildingdata.get_bdtopo(self.district_id)
+
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore")
+            logger.debug(f"{self.logger_header} Loading buildings from {building_path}.")
+            return gpd.read_file(
+                building_path,
+                layer=self.BUILDING_LAYER_NAME,
+                engine=self.GIS_ENGINE,
+                bbox=bounds,
+            )
+
+    def _filter_buildings_on_bounds(
+        self, buildings: gpd.GeoDataFrame, district_geometry: geometry.Polygon
+    ) -> gpd.GeoDataFrame:
+        buildings["intersection_share"] = (
+            buildings["geometry"].intersection(district_geometry).area / buildings["geometry"].area
+        )
+        filtered_buildings = buildings.loc[
+            buildings.intersection_share >= self.INTERSECTION_THRESHOLD
+        ].copy()
+        filtered_buildings.drop(columns=["intersection_share"], inplace=True)
+        return filtered_buildings
+
+    def _get_building_path(self, district_data: gpd.GeoDataFrame) -> Path:
+        region_id = int(district_data["region"].iloc[0])
+        return (
+            self.building_footprint_folder
+            / f"{self.BUILDING_FILE_PREFIX}{region_id}{self.BUILDING_FILE_SUFFIX}"
+        )