Metadata-Version: 2.4
Name: building_eload
Version: 0.4.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: tables
Requires-Dist: blosc2
Requires-Dist: cython
Requires-Dist: environs
Requires-Dist: metalog
Requires-Dist: pvlib
Requires-Dist: ladybug-core
Requires-Dist: colorlog
Requires-Dist: requests
Requires-Dist: py7zr
Requires-Dist: contextily
Requires-Dist: folium
Requires-Dist: pyproj
Requires-Dist: ipykernel
Requires-Dist: buildingmodel
Requires-Dist: buildingdata[era5]
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# Building_eload

**Version:** `0.4.0`

![Python Version](https://img.shields.io/badge/python-3.12-blue)
![Conda](https://img.shields.io/badge/conda-supported-green)
![Status](https://img.shields.io/badge/status-active-brightgreen)

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>

## 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`

## 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 botyh simulation process 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
```
