building-eload 0.4.0

District-level energy hourly simulation of buildings

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

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

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

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()

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