Metadata-Version: 2.4
Name: buildingmodel
Version: 1.3.0
Summary: District-level energy simulation of buildings
Author-email: Yassine Abdelouadoud <yassine.abdelouadoud@gmail.com>
Maintainer-email: Yassine Abdelouadoud <yassine.abdelouadoud@gmail.com>
License: The MIT License (MIT)
        =====================
        
        - Copyright © `2021` `Antoine Rogeau`
        - Copyright © `2021` `Robin Girard`
        - Copyright © `2021` `Seddik Yassine Abdelouadoud`
        
        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.8
Description-Content-Type: text/markdown
License-File: LICENCE.md
License-File: LICENSE
Requires-Dist: geopandas
Requires-Dist: numpy
Requires-Dist: polars
Requires-Dist: pyarrow
Requires-Dist: topojson
Requires-Dist: simplification
Requires-Dist: pvlib
Requires-Dist: metalog
Requires-Dist: numexpr
Requires-Dist: environs
Requires-Dist: tqdm
Requires-Dist: xarray
Requires-Dist: pyyaml
Requires-Dist: buildingdata[era5]>=0.6.0
Requires-Dist: heatpumpmodel>=0.2.1
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: bandit; extra == "dev"
Requires-Dist: pip-audit; extra == "dev"
Requires-Dist: Cython; extra == "dev"
Dynamic: license-file

# 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

![](./doc/source/images/energy_by_floor_surface.png)

**Documentation**:
The complete documentation for buildingmodel (methodology and API) is available at [DOCS](https://energytransition.gitlab.io/buildingmodel/)

## 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](./pyproject.toml); the reference conda environment is
[ci/conda_env.yml](./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](INSTALL.md).

## Usage

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

```python
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](CONTRIBUTING.md).


## Open source licensing info
1. [LICENCE](LICENCE.md)

----

## 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](https://www.theses.fr/2020UPSLM014)

### Funding :

### Main contributors : 
- Antoine Rogeau
- [Robin Girard](https://www.minesparis.psl.eu/Services/Annuaire/robin-girard) -- [gitHub](https://github.com/robingirard) [LinkedIn](https://www.linkedin.com/in/robin-girard-a88baa4/) [google Scholar](https://scholar.google.fr/citations?user=cEYGStIAAAAJ&hl=fr)
- Seddik Yassine Abdelouadoud
