Metadata-Version: 2.4
Name: building_eload
Version: 0.8.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: tqdm
Requires-Dist: fastcluster
Requires-Dist: colorlog
Requires-Dist: buildingmodel>=1.0.2
Requires-Dist: buildingdata[era5]>=0.2.0
Requires-Dist: heatpumpmodel>=0.1.0
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()
```

### 3) Dynamic simulation with the heat-pump model (opt-in)

The conversion of hourly heating *demand* into heating *electricity* happens in
a single place, `building_eload.models.heating_system`. Leaving
`DynamicSimulation.heating_system` at `None` keeps the published
constant-efficiency (static-COP) behaviour; assigning a converter swaps the
model without touching anything else:

```python
from building_eload.models import heat_pump as hp
from building_eload.models.heat_pump_system import HeatPumpHeatingSystem

# Defaults: air-to-water, medium-temperature radiators with weather
# compensation, inverter, monovalent with an electric-resistance backup --
# the reference configuration of Rogeau et al. (2024). Applied to the
# buildings whose `heating_system` is "electric heat pump"; every other
# building keeps the published conversion.
sim.heating_system = HeatPumpHeatingSystem(
    hp.HeatPumpConfig(
        system=hp.System.A_W,
        mode=hp.Mode.M,
        emitter=hp.Emitter.FH,        # floor heating; the biggest SCOP lever
        technology=hp.Technology.INVERTER,
    )
)
sim.run()
```

The hourly results then carry `heat_pump_electricity_need` and
`heating_backup_electricity_need` alongside the usual
`heating_electricity_need` (their sum), plus `heat_pump_heat_delivered`.
Air-source configurations require the weather frame's `humidity` column and
fail loudly without it, rather than silently disabling the defrost derate.

## Running Simulations

The former `building_eload.scripts` entry points were removed in 0.8.0; use
the public API instead (the tutorials in `doc/tutorials/` walk through each
step):

- `building_eload.core.static_simulation.StaticSimulation` — static annual
  calibration
- `building_eload.core.dynamic_simulation.DynamicSimulation` — dynamic hourly
  simulation
- `building_eload.core.validation.Validation` — validation against measured
  consumption
- `building_eload.core.clustering.cluster_districts` — representative-district
  selection
- EPW climate generation lives in the `buildingdata` package
  (`buildingdata.prefetch_era5` for the bulk ERA5 download,
  `buildingdata.get_era5_climate` for per-point EPW files)

For an end-to-end orchestrated pipeline, see the Snakemake workflow in the
`building_eload_paper` repository.
