BuildingModel

Description: BuildingModel is a district-level building energy simulation tool designed to leverage the availability of large scale open datasets on building geometry, census-derived dwelling characteristics and energy performance diagnosis. The methodology proposed combines GIS data processing with statistical inference techniques to obtain a description of each building's envelop geometry (including adjacency), thermal performances (envelop and systems) and occupation. This description is then used as the input of a physical model calculating solar gains, losses through boundaries and ventilation, heating system consumption and occupant-related energy usage.

• Technology stack: Python 3, Polars, GeoPandas
• Status: Beta (1.0). The complete toolchain is functional, but validation and fine-tuning of the models are still ongoing.

Screenshot: Example of results that can be obtained from a BuildingModel run with the GeoPandas integration allowing easy interactive plotting in Jupyter Notebooks

Documentation: The complete documentation for buildingmodel (methodology and API) is available at DOCS

Limitations

BuildingModel has been developed and tested only in the French context, for which GIS, census and energy diagnosis data is available. However, the generic character of the methodology should make it suitable for other countries as long as similar datasets can be obtained. In addition, BuildingModel currently deals only with residential buildings, due to limitations on the availability of data for other building usages.

Dependencies

BuildingModel requires Python 3.10 or later (tested on 3.13) and depends mainly on Polars, GeoPandas and pvlib. The canonical dependency list is in pyproject.toml; the reference conda environment is ci/conda_env.yml. Reference datasets (BDTOPO, census, DPE, gas network, climate) are fetched by the companion package buildingdata, installed automatically.

Installation

pip install buildingmodel

Detailed installation instructions available at INSTALL.

Usage

In its most basic form, BuildingModel is used by building a Simulation around a GIS file and calling run_all :

from importlib.resources import files
from pathlib import Path

from buildingmodel.main import Parameters, Simulation

# Sample GIS and EPW data bundled with the package
data = Path(str(files('buildingmodel') / 'data'))

sim = Simulation(
    building_data=data / 'gis' / 'testing' / 'bdtopo_iris_461290000.parquet',
    climate_data=None,   # pick from climate_folder, else fetch ERA5
    parameters=Parameters(climate_folder=data / 'climate'),
)
sim.run_all()

sim.buildings    # one row per building, with needs, consumption and energy label
sim.boundaries   # one row per wall / roof / floor
sim.dwellings    # one row per dwelling

The results are Polars DataFrames (sim.building_geometries holds the footprints as a GeoDataFrame). More advanced uses and result processing are available as jupyter notebook examples in the documentation.

How to test the software

From the root folder of BuildingModel, run :

pytest

Known issues

• Current occupant-related energy usage models are very crude and subject significant future changes.
• Energy consumption of heating systems relies on a constant efficiency model, except for electric heat pumps which use a climate-dependent seasonal COP. Other technology-specific models are still to come.
• Peak consumption estimates are provided by building but cannot be summed directly to obtain the total peak consumption of the district as the peaks may not be all synchronous.
• Consumption of cooling systems is not modelled

Getting help

If you have questions, concerns, bug reports, etc, please file an issue in this repository's Issue Tracker.

Getting involved

BuildingModel is looking for users to provide feedback and bug reports on the initial set of functionalities as well as developers to contribute to the next versions, with a focus on validation of models, cooling need simulation, adaptation to other countries' datasets and building usages.

Instructions on how to contribute are available at CONTRIBUTING.

Open source licensing info

1. LICENCE

Credits and references

BuildingModel physical models are directly derived from the work of Antoine Rogeau in Vers une approche intégrée d’aide à la planification énergétique territoriale : application à la rénovation énergétique des bâtiments

Funding :

Main contributors :

• Antoine Rogeau
• Robin Girard -- gitHub LinkedIn google Scholar
• Seddik Yassine Abdelouadoud