Building_eload

Version: 0.4.0

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

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

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

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:

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.

Script Entry Points (Current)

• Static simulation:

python -m building_eload.scripts.simulation.static.run

• Parallel static simulation:

python -m building_eload.scripts.simulation.static.run_parallel

• Dynamic simulation:

python -m building_eload.scripts.simulation.dynamic.run

• Parallel dynamic simulation:

python -m building_eload.scripts.simulation.dynamic.run_parallel

• Validation:

python -m building_eload.scripts.validation.run

• Climate preprocessing:

python -m building_eload.scripts.climate.generate_climates