Metadata-Version: 2.4
Name: building_eload
Version: 0.6.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>=1.0.1
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
```
