FLEX4FACT Building-Industry Interaction Toolbox

The Toolbox is developed by members of the "Institute of Energy Efficiency and Sustainable Building (e3D)" and the "Institute for Energy Efficient Buildings and Indoor Climate (EBC)" at "RWTH Aachen University" based on Python 3.11.0.

If you have any questions regarding the Building-Industry Interaction Toolbox feel free to contact us at:

Description

This repository was developed as part of the FLEX4FACT project (Grant Agreement No. 101058657), funded by the European Union’s Horizon Europe programme. It contains a Python-based modelling and simulation toolbox designed to support the assessment of interactions between industrial processes and building energy systems.

The toolbox provides methods for evaluating and optimizing waste heat recovery strategies, addressing both single-building and district-level energy systems. It enables analysis of internal heat gains and waste heat utilization for heating and cooling applications, supporting Demand Response strategies in energy supply.

Key features include:

Single-Building Analysis: Evaluates how production-related waste heat and internal gains can be used to reduce heating and cooling demands.
District-Level Simulation: Uses archetype-based modelling with minimal input to estimate hourly heating demand across multiple buildings and assess aggregate waste heat integration potential.

Getting started

Prerequisites

To successfully set up and use the Building-Industry Interaction Toolbox, you need the following software installed on your system:

Python: Version 3.11.0.
Make: A build automation tool used for streamlining setup and common tasks.
Poetry: A tool for managing Python dependencies and packaging the project.

We recommend installing them in the order listed if you don't have them already.

1. Install Python

Ensure you have Python version 3.11.0 installed.

Download: You can get Python from the official Python website. Choose the appropriate installer for your operating system and follow the installation instructions.
Verify Installation: After installation, open your terminal or command prompt and check the installed version by running:
```
python --version
```
Expected output: The command should display a version number equal to 3.11.0. If you see an older or newer version or receive an error, please ensure Python 3.11 is correctly installed and accessible via your system's PATH environment variable.

2. Install Make

GNU Make is a build automation tool that controls the generation of executables and other files from source files, based on rules defined in a Makefile. In this toolbox, it simplifies the setup process by automating tasks like virtual environment creation and Git initialization, using the Makefile located in the project's root directory.

For Windows users (recommended method):
- The easiest way to install GNU Make on Windows is using the Chocolatey package manager.
- Prerequisite: If you don't have Chocolatey installed, please follow the instructions on the official Chocolatey installation page first. Remember to run PowerShell as an Administrator when installing Chocolatey.
- Install Make: Once Chocolatey is set up, open an Administrator terminal (PowerShell or Command Prompt) and run the following command:
```
choco install make
```
- Verify installation: After installation, open a new terminal window (this ensures the system's PATH environment variable is updated) and run:
```
make --version
```
- Expected output: This command should display the installed version of GNU Make, similar to: GNU Make 4.4.1.
For macOS users:
- Make is usually included with the Xcode Command Line Tools. If you don't have them installed, you can install them by opening Terminal and running:
```
xcode-select --install
```
- Alternatively, if you use Homebrew:
```
brew install make
```
- Verify with:
```
make --version
```

3. Install Poetry

Poetry is a Python dependency and package management tool. In this toolbox it is used to declare Python libraries in the pyproject.toml, to define tool configurations, to resolve package dependencies and to install a virtual environment.

Install: Poetry can be installed using several methods:

With pipx (recommended method):
```
pipx install poetry
```

With the official installer:

curl -sSL https://install.python-poetry.org | python3 -

Verify installation: After installation, check the installed version:

  poetry --version

Expected output: The command should display the version, for example: Poetry (version 2.1.0)

For detailed installation instructions, see the Poetry documentation.

4. Install EnergyPlus

EnergyPlus is an open source building energy simulation that will be used in this toolbox to generate single building analyses. For this toolbox EnergyPlus Version 24.1.0 is required.

Initial Project Setup

To set up this toolbox locally, first clone this repository to your local repository. Then run the toolbox_setup target that is defined in the Makefile by executing make toolbox_setup in your CLI.

This command will automatically execute the following steps:

Delete the project template /.git directory and the poetry.lock file.
Initialize a /.git directory in your local repository.
Create and install a virtual environment defined in the pyproject.toml using Poetry.
Install and update pre-commit hooks.
Activate the created virtual environment.

Project Setup for Template Developers

If you are working on the toolbox code itself, run the dev_toolbox_setup target that is defined in the Makefile by executing make dev_toolbox_setup in your CLI as this will leave the original toolbox /.git directory untouched.

Toolbox Structure

The structure of this toolbox is based on the Cookiecutter Data Science template.

 ├─ configs                              <- set of .yaml configuration files used by the python package hydra
 │   │                                      for configuration management of the toolbox modules
 │   └──  main.yaml                       <- main configuration file used in this toolbox
 │
 ├─ data                                 <- data storage collects user data input and auxiliary proces data output 
 │
 ├─ docs                                 <- HTML file based documentation automatically created and
 │                                          updated by a pre-commit hook using the pdock3 python package
 ├─ logs                                 <- logging files automatically created by the python package hydra
 │
 ├─ models                               <- simulation model storage
 │
 ├─ notebooks                            <- jupyter notebooks for early code development and experimentation
 │
 ├─ notes                                <- general file storage
 │
 ├─ references                           <- additional explanatory data
 │
 ├─ reporting                            <- descriptive result documentation and visualization
 │                                          created along toolbox processes
 │
 ├─ src                                  <- python module with the main source code
 │   │
 │   ├── utils                           <- utility class and function storage
 │   │
 │   ├── modules.py                      <- python scripts with hydra configuration
 │   └── __init__.py                     <- __init__.py file
 │
 ├─ .gitignore                           <- .gitignore file
 │
 ├─ .pre-commit-config.yaml              <- definition of pre-commit hooks to be installed
 │
 ├─ Makefile                             <- set of make targets for automation of system executables such as
 │                                           `make toolbox_setup`
 │
 ├─ pyproject.toml                       <- pyproject.toml file for Poetry configuration
 │
 └── README.md                           <- top-level README for developers working with the toolbox

Toolbox developer features

This toolbox includes functional features that allow for some automation of software development processes.

Pre-commit hooks

Pre-commit is a Python package that installs git hook scripts that are listed in the pyproject.toml file and configured in the .pre-commit-config.yaml file. Git hooks get triggered at every commit and are used in this toolbox to enforce best practices in code formatting, perform simple checks on code quality and automate various code formatting tasks.

The provided pre-commit hooks include the following Python packages:

Black: Checks Python code format and automatically reformats code to conform with the Black code style.
Black-jupyter: Variant of Black designed for formatting of Jupyter notebooks.
Ruff: Checks Python code for coding standards and style guides by a rule set that includes functionalities of the following Python packages:
- flake8: Checks Python code for syntax errors, style violations and potential code quality issues.
- isort: Sorts imports.
- pydocstyle: Checks docstrings for Google's docstring convention.
Pycln: Removes unused and unnecessary imports from Python code.
trailing-whitespace: Identifies and removes trailing whitespace at the end of code lines.
end-of-file-fixer: Ensures each file ends with a new line.
mypy: Checks Python code for type related errors.
interrogate: Checks Python code for docstring documentation.

Automated HTML documentation with pdoc

This toolbox uses the Python package pdoc to automatically generate an HTML based documentation from the code base's docstrings.

The documentation process is written as the docs target into the Makefileand can be manually executed by typing make docs in your CLI. The resulting HTML files are saved to the /docs directory of the toolbox's structure.

To view the created toolbox documentation, open the index.html from the /docs/src directory in your browser.

Configuration management with Hydra

This toolbox uses the open-source configuration management tool Hydra. It offers structured and hierarchical parameter setting in .yaml files, parameter pre-setting of configuration groups in the directory structure and logging capabilities. Parameter- and multirun settings can be directly overwritten and defined from the CLI.

Configurations are defined in module specific directories such as /configs/module_name in separate files such as config:name.yaml and are set for execution in the main.yaml file in the /configs directory through entries such as defaults: - module_name: config_name.

Logging to track module execution is automated and set configurations are saved on each run to a module specific /logs/module_name/yyyy-MM-dd HH-mm-ss directory that contains the timestamp of execution for unique identification.

Single Building Analysis

The single-building analysis module evaluates two primary scenarios:

Single Building Waste Heat Demand Response Analysis: Waste heat Demand Response for building heating and cooling applications, with waste heat availability from cooling water or exhaust gas as a Demand Response signal
Single Building Internal Gains Demand Response Analysis: internal gains Demand Response utilizing production-related latent, radiant and convective internal gains as Demand Response signal

Inputs for the Single Building Analysis

To successfully run the Single Building Waste Heat Demand Response Analysis and the Single Building Internal Gains Demand Response Analysis the following inputs are required:

YAML configuration file in the corresponding configs directory (configs/single_building_waste_heat_analysis or configs/single_builidng_internal_gains_analysis). The YAML file should include paths to:
The EnergyPlus model files (IDF, IDD, EPW).
CSV file for setpoint schedule assignments to the thermal zones in the IDF file.
Waste heat potential data as an hourly timeseries over one year. The format of the waste heat availability file has to comply with the following:

Hour	Waste Heat [kWh]
1	xxx
2	xxx
...	...
8760	xxx

Information on the production equipment object names in the IDF file.
Information on optional parameters for existing thermal energy storage (TES) in LP optimization scenarios. If not specified, the LP will auto-size the storage capacity.

How to Prepare the EnergyPlus Input Files for Use in this Toolbox

Before running the analysis, you need to properly set up your EnergyPlus input files:

1. Use an Ideal Loads-Based IDF File

Select an ideal loads-based IDF file from your project.
This file should use ideal loads for every zone.
Remove any unnecessary DDY (Design Day) files from the IDF file.

2. Ensure Proper Ideal Loads Application

Verify that ideal loads are correctly assigned to all thermal zones.
Ensure that your IDF file is compatible with EnergyPlus version V26 (as specified in your IDD file).

3. Generate CSV Files for Heating and Cooling Setpoints

Create CSV files for hourly heating and cooling setpoints throughout the year.
The first day of the year should be a Sunday.
You can export setpoints from an existing EnergyPlus model using:
- Output:Variable → "Zone Thermostat Heating Setpoint Temperature"
- Output:Variable → "Zone Thermostat Cooling Setpoint Temperature"
Or create custom setpoint schedules via the script notes/idf_model_prep/setpoint_csv_creator.py.

4. Assign Thermal Zones to Setpoints

Run the script notes/idf_model_prep/create_stp_assignment_csv.py to generate a CSV file.
This CSV file will assign each thermal zone to its corresponding heating and cooling setpoint CSV files.

5. Modify the IDF File with Setpoint Schedules

Use the script notes/idf_model_prep/assign_csv_setp_idf.py to modify the IDF file.
The script will insert Schedule:File objects to reference the heating and cooling setpoint CSV files.

How to run the Single Building Waste Heat Demand Response Analysis

Before you run the script, poetry has to be set as an interpreter to use the created virtual environment.
Make sure to have all required inputs and configurations set up as described above, namely the required YAML file in the configs/single_building_waste_heat_analysis directory, the EnergyPlus model files (IDF, IDD, EPW), the CSV file for setpoint schedule assignments, and the waste heat potential data as an hourly timeseries over one year.
In configs/main.yaml assign the corresponding yaml file name to single_building_waste_heat_analysis.
Once all inputs and configurations are set up, open the script:

  src/single_building_waste_heat_analysis.py

At the beginning of the script, configure the DR_STRATEGIES list by changing the "enabled" flag to "True" or "False" and thereby define which Demand Response strategies to run.
Then, run the script src/single_building_waste_heat_analysis.py, and
find all results in the results/ directory.

Methodology

Base Case Simulation Check
- Before running new scenarios, the script checks whether a base case simulation result exists.
- If not, the base case is simulated using the provided EnergyPlus IDF model.
Demand Response Strategies

The tool implements the following waste heat utilization strategies:

Scenario ID	Technique
Baseline	No WH, no storage, no DR, fixed heating setpoints.
WHRef_heat	Direct WH use only: Use available waste heat directly for heating, no thermal storage, no setpoint adaptation.
WH1_heat	WH-dependent building-mass load shifting: Increase heating setpoint (+2 K) when WH > baseline heating demand.
WH2_heat	WH-dependent building-mass load shifting with flexible setpoint relaxation: Increase heating setpoint to a maximum of +2°C so that the additional heating power does not exceed the available waste heat, when WH > baseline heating demand.
WH3_heat	WH storage load shifting: Shift WH usage for heating by implementing an idealized TES controlled by an LP-optimization to minimize the auxiliary energy demand.
WH4_heat	Peak shaving with flexible setpoint relaxation: Identify weekly peak periods in auxiliary heating energy demand through the weekly 95% percentile of the auxiliary heating energy demand. Shave weekly peaks in auxiliary heating energy by temporary heating setpoint relaxation of -2 K.
WH5_heat	Peak shaving with flexible setpoint relaxation: Identify weekly peak periods in auxiliary heating energy demand through the weekly 95% percentile of the auxiliary heating energy demand. Shave weekly peaks in auxiliary heating energy by temporary heating setpoint relaxation. Shave the heating setpoint to a maximum of -2°C. The heating setpoint is decreased (only during peak hours) until the new heating demand can be fully met by waste heat availability, but not more than -2°C.
WHRef_cool	Direct WH use only: Use available waste heat directly for cooling, no thermal storage, no setpoint adaptation.
WH1_cool	WH-dependent building-mass load shifting: Decrease cooling setpoint (-2 K) when WH > baseline cooling demand.
WH2_cool	WH-dependent building-mass load shifting: Decrease cooling setpoint to a maximum of -2 K so that the additional cooling power does not exceed the available waste heat, when WH > baseline cooling demand.
WH3_cool	WH storage load shifting: Shift WH usage for cooling by implementing a thermal storage controlled by an LP optimization.
WH4_cool	Peak shaving: Identify weekly peak periods in auxiliary cooling energy demand through the weekly 95% percentile of the auxiliary heating energy demand. Shave weekly peaks in auxiliary cooling energy by temporary cooling setpoint relaxation (+2 K).
WH5_cool	Peak shaving with flexible setpoint relaxation: Identify weekly peak periods in auxiliary cooling energy demand through the weekly 95% percentile of the auxiliary cooling energy demand. Shave weekly peaks in auxiliary cooling energy by temporary cooling setpoint relaxation. Shave the cooling energy by increasing the cooling setpoint to a maximum of +2 K. The cooling setpoint is increased (only during peak hours) until the new cooling demand can be fully met by waste heat availability, but not more than to a maximum of +2 K.

WH = Waste Heat
Auxiliary energy = additional heating/cooling energy from sources other than WH.

Execution of EnergyPlus Simulations
- For each modified strategy, a new IDF file is created with the respective setpoint adjustments, except for WH3, where the base case simulation is used as a base for the LP-optimized Thermal Energy Storage scenario.
- EnergyPlus simulations are run for each scenario, except for WH3.
KPI Calculation and Reporting
- KPIs are generated for each strategy to evaluate the impact of waste heat usage on energy efficiency.
- The script outputs key performance indicators, including:
  - Total energy consumption (kWh)
  - Total heating and cooling energy demand (kWh)
  - Total waste heat used (kWh)
  - Percentage of waste heat integrated into the building's energy mix
  - Percentage of waste heat utilized vs. wasted
  - Comfort metrics based on ASHRAE 55-2004 (hours outside thermal comfort range)

Expected Output Files

Simulation Results:
- EnergyPlus output files are stored in models/single_building_scenario_storage/eplus_output_files/
Modified IDF Files:
- Adjusted IDF models for each Demand Response scenario are saved in models/single_building_scenario_storage/idf_scenarios/
KPI Reports:
- Consolidated CSV files summarizing KPIs for all Waste Heat Demand Response scenarios, including:
  - Total energy consumption
  - Total heating and cooling energy
  - Total waste heat used
  - Percentage of waste heat in the total energy mix (overall, heating, and cooling)
  - Time not comfortable (based on ASHRAE 55-2004)
  - Surface heat storage energy (kWh)
- Example output files:
```
FACTORY_waste_heat_results.csv                # Absolute KPIs for waste heat scenarios
FACTORY_waste_heat_results_changes.csv        # % changes vs. base case for waste heat scenarios
```
Timeseries Waste Heat Analysis Data:
- CSV files containing hourly timeseries data over one year for:
  - Cooling demand
  - Heating demand
  - Waste heat availability
- Example output files:
```
FACTORY_wh_analysis_data.csv          # Base case
FACTORY_WH1_heat_wh_analysis_data.csv
```
Visualization Plots:
- HTML/PDF files containing comparative visualizations for waste heat heating scenarios, generated by the plotting scripts in utils/plotting/, including:
  - Time series plots (plot_timeseries_single_building.py) showing heating demand, waste heat availability, and waste heat utilization over the full year and selected representative weeks
  - Bar charts (plot_bar_charts_single_building.py) comparing energy KPIs across different heating scenarios
  - Peak shaving visualization (plot_peakshaving_single_building.py) showing setpoint adjustments and heating demand reductions during peak periods
  - TES operation plots (plot_tes_operation_single_building.py) for WH3_heat scenario, illustrating thermal energy storage charging/discharging cycles
- Plots are stored in the results/ directory
- You can configure the plots via the script src/utils/plotting/plot_config.py.

How to run the Single Building Internal Gains Demand Response Analysis

Before you run the script, poetry has to be set as an interpreter to use the created virtual environment.
Make sure to have all required inputs and configurations set up as described above, namely the required YAML file in the configs/single_building_internal_gains_analysis directory, the EnergyPlus model files (IDF, IDD, EPW), the CSV file for setpoint schedule assignments, and the production equipment object names in the IDF file.
In configs/main.yaml assign the corresponding yaml file name to single_building_internal_gains_analysis.
Once all inputs and configurations are set up, open the script:

  src/single_building_internal_gains_analysis.py

At the beginning of the script, configure the DR_STRATEGIES list by changing the "enabled" flag to "True" or "False" and thereby define which Demand Response strategies to run.
Then, run the script src/single_building_internal_gains_analysis.py, and
find all results in the results/ directory.

Methodology

Base Case Simulation Check
- Before running new scenarios, the script checks whether a base case simulation result exists.
- If not, the base case is simulated using the provided EnergyPlus IDF model.
Demand Response Strategies The script modifies heating and cooling setpoints based on production-related internal gains availability using the following strategies:

Scenario ID	Technique
Baseline	No WH, no storage, no DR, fixed heating setpoints.
IG1	IG-dependent building mass load shifting/setpoint increase: Increase heating setpoint (+2°C) when production IG ≥ 0.
IG2	IG-dependent setpoint relaxation: Increase cooling setpoint (+2°C) when production IG ≥ 0.
IG3	IG-dependent setpoint relaxation: Decrease heating setpoint (-2°C) when production IG ≥ 0.

IG = Production-related internal gains

Execution of EnergyPlus Simulations
- For each modified strategy, a new IDF file is created with the respective setpoint adjustments.
- EnergyPlus simulations are run for each scenario.
KPI Calculation and Reporting
- KPIs are generated for each strategy to evaluate the impact of internal gains on energy efficiency.
- The script outputs key performance indicators, including:
  - Total energy consumption (kWh)
  - Total heating and cooling energy demand (kWh)
  - Peak heating and cooling demand (kW)
  - Surface heat storage energy (kWh)
  - Comfort metrics based on ASHRAE 55-2004 (hours outside thermal comfort range)

Expected Output Files

Simulation Results:
- EnergyPlus output files are stored in models/single_building_scenario_storage/eplus_output_files/
Modified IDF Files:
- Adjusted IDF models for each Demand Response scenario are saved in models/single_building_scenario_storage/idf_scenarios/
KPI Reports:
- Consolidated CSV files summarizing KPIs for all Internal Gains Demand Response scenarios, including:
  - Total energy consumption
  - Total heating and cooling energy
  - Peak heating and cooling demand
  - Time not comfortable (based on ASHRAE 55-2004)
  - Surface heat storage energy
- Example output files:
```
FACTORY_internal_gains_results.csv            # Absolute KPIs for internal gains scenarios
FACTORY_internal_gains_results_changes.csv    # % changes vs. base case for internal gains scenarios
```
Timeseries Internal Gains Analysis Data:
- CSV files containing hourly timeseries data over one year for:
  - Total surface heat storage energy
  - Cooling and heating needs
  - Total production internal gains
- Example output files:
```
FACTORY_ig_analysis_data.csv          # Base case
FACTORY_IG1_ig_analysis_data.csv
FACTORY_IG2_ig_analysis_data.csv
FACTORY_IG3_ig_analysis_data.csv
```
Visualization Plots:
- HTML/PDF files containing comparative visualizations for internal gains scenarios, generated by the plotting scripts in utils/plotting/, including:
  - Time series plots (plot_timeseries_single_building.py) showing heating/cooling demand, internal gains availability, and surface heat storage over the full year and selected representative weeks
  - Bar charts (plot_bar_charts_single_building.py) comparing energy KPIs across different internal gains scenarios
- Plots are stored in the results/ directory
- You can configure the plots via the script src/utils/plotting/plot_config.py.

District Buildings Analysis

The district building analysis in this tool identifies surrounding buildings by location and performs rapid, archetype-based energy simulations using minimal data. This process generates hourly, full-year heat demand timeseries. These are aggregated to represent the overall district building heat demand, which is utilized for assessing waste heat utilization potential.

The district building analysis involves three main processes, which can be executed independently:

Building identification and initialization.
Building energy simulation and heat demand timeseries aggregation.
Aggregated building energy demand analysis and waste heat potential analysis.

1) Building Identification and Initialization

This module is the first step in the district building analysis workflow. It automates the identification of buildings within a specified geographical area and initializes their fundamental parameters. The process leverages open-source geo-information, primarily OpenStreetMap (OSM), to retrieve building footprints. For each identified building, it calculates key geometric and geographic properties such as its centroid coordinates, ground elevation (altitude), projected area, and standard timezone offset. These derived properties are then combined with user-defined default values (e.g., for building category, archetype, construction year) to create a comprehensive dataset. The primary outputs are a GeoJSON file containing the building geometries and a CSV file detailing the initialized parameters for each building, which serves as a crucial input for subsequent building energy simulation steps.

To execute this module, run the script from this directory:

 src/district_building_params_initialization.py

User Inputs

The primary input for this module is provided through its Hydra configuration file located in
configs/district_building_params_initialization/YOUR_CONFIG_NAME.yaml. No direct file inputs are needed by the user to run the script, as it fetches required geo-data from online APIs based on the configuration.

Key information required in the configuration includes:

Area of Interest: Defined by latitude, longitude, and a search radius.
Default Building Characteristics: Pre-defined values for building type, age, etc., which are used when specific data cannot be derived from OSM.

The module's behavior is controlled by a YAML configuration file. Below is a description of the key sections and
parameters, focusing on those essential for users to customize. The configuration is typically structured as follows:

Key Configuration Parameters:

paths:
- target_dir_geo: Specifies the directory where the output GeoJSON file with building footprints will be saved.
- target_dir_building_params: Specifies the directory where the output CSV file with initialized building parameters will be saved.
Note: These paths are usually pre-configured and might not require user modification unless a custom output structure is desired.
location (Essential for User Setup):
- latitude: (Float) The WGS84 latitude of the center point for your area of interest.
- longitude: (Float) The WGS84 longitude of the center point for your area of interest.
- radius: (Integer) The search radius in meters around the latitude and longitude point within which building data will be queried from OpenStreetMap.
default_values (Important for Initialization): These values are used to populate building characteristics when such information is not available from the OSM data for a specific building.
- category: (String) Default building usage category ("residential" or "non-residential").
- archetype: (String) Default building typology ("single_family_house", "terraced_house", "multi_family_house", "apartment_block", "office", "trade", "education", "health", "hotels_and_restaurants" or "other_non_residential_buildings").
- refurbishment: (String) Default assumed refurbishment status ("standard" or "retrofit").
- year_of_construction: (String or Integer) Default construction year.
- number_of_floors: (Integer) Default number of floors above ground.
- floor_height: (Float) Default average height per floor in meters.
Note: The values for category and archetype should align with the building archetypes listed in the tabula_building_stock.csv database in the data/district_buildings/building_stock directory.

Expected Output

Upon successful execution, the module generates two primary output files in the directories specified under the paths configuration:

Geodata GeoJSON File (district_buildings.geojson):

Content: This file contains a FeatureCollection where each Feature represents an identified building.
Geometry: The geometry of each building footprint is provided as a Polygon, with coordinates reprojected to a suitable Coordinate Reference System (CRS) for the identified region.
Properties: Each feature includes properties such as:
- building_id: A unique identifier assigned by the script (e.g., "B001").
- osm_id: The original OpenStreetMap way ID.
- centroid_latitude: Latitude of the building's centroid (WGS84).
- centroid_longitude: Longitude of the building's centroid (WGS84).
- altitude_m: Estimated ground elevation at the centroid in meters.
- area_m2: Calculated area of the building footprint in square meters, based on the projected CRS.
- crs: The EPSG code of the projected CRS used for the geometry and area calculation.
- osm_tags: Original tags associated with the building from OSM.

Building Parameters CSV File (building_params.csv):

Content: This CSV file provides a tabular summary of initialized parameters for each building. It is a critical input for subsequent building energy simulation modules.
Columns:
- building_id: Unique identifier for the building, matching the GeoJSON.
- country: The country where the building is located, determined via reverse geocoding ("Germany", "Italy", "Norway" or "Spain").
- latitude: Latitude of the building's centroid (WGS84 decimal degrees).
- longitude: Longitude of the building's centroid (WGS84 decimal degrees).
- altitude: Estimated ground elevation at the centroid in meters above sea level. NaN if not determinable.
- time_zone: Standard UTC offset in hours for the building's location (ignoring Daylight Saving Time).
- category: Building usage category, taken from default_values if not available from OSM.
- archetype: Building typology, taken from default_values.
- refurbishment: Assumed refurbishment status, taken from default_values.
- year_of_construction: Construction year, taken from default_values if not available from OSM.
- number_of_floors: Number of floors above ground, taken from default_values.
- floor_height: Average height per floor in meters, taken from default_values.
- building_foot_print: Calculated area of the building footprint in square meters (m²). This corresponds to area_m2 in the GeoJSON.
- osm_way_id: The original OpenStreetMap way ID for traceability.

2) Building energy simulation and heat demand timeseries aggregation

This crucial stage of the district analysis focuses on estimating the energy demand of the identified buildings. Based on the available data and desired level of detail, the toolbox offers two distinct methodologies for simulating building energy performance: a simplified Degree Day based Calculation and a more detailed Reduced Order Model (ROM) Calculation. Both approaches aim to generate hourly, full-year heat demand timeseries for each building, which are then typically aggregated to understand the collective demand of the district.

2a) Degree Day Calculation

This module calculates the hourly heat demand for each building identified in the previous step using a degree-day based method. This is a simplified steady-state approach that estimates heating energy based on the outdoor air temperature and building-specific base and setpoint temperatures. The module retrieves thermal properties for buildings from a predefined building stock database, matching them based on country, category, archetype, and construction year.

The output consists of time series data for each building and, if enabled, aggregated load profiles for the entire district or specific building groups.

To execute this module, run the script from this directory:

 src/degree_day_calculation.py

User Inputs

The module requires several input files, which are specified in its Hydra configuration file located in configs/degree_day_calculation/YOUR_CONFIG_NAME.yaml.

Weather Data CSV File:

Specified by: paths.source_dir and subpaths.weather in the configuration file.
Content: Time series of hourly weather data for the location of interest. Must include a column for outdoor dry-bulb temperature.
Key Column: The name of the outdoor temperature column is specified by columns.outdoor_temperature in the configuration file.

Building Stock CSV File (data/district_building/building_stock/tabula_building_stock.csv):

Specified by: paths.source_dir and subpaths.building_stock in the configuration file.
Content: A database of building archetypes and their thermal properties. This file provides parameters like specific heat load, full load hours, base temperature, and room temperature setpoints for different building types, construction year ranges, and countries.
Key Columns for Matching: country, category, archetype, year_of_construction_low, year_of_construction_up.
Key Columns for Parameters: specific_heat_load, full_load_hours, base_temperature, room_temperature_setpoint.

Building Parameters CSV File:

Specified by: paths.source_dir and subpaths.building_params in the configuration file.
Content: This is typically the output CSV (building_params.csv) from the "Building Identification and Initialization" module. It contains the list of buildings in the district with their initialized parameters.
Key Columns Used: building_id, country, category, archetype, year_of_construction, building_foot_print, number_of_floors.

Key Configuration Parameters:

paths:
- source_dir: Base directory where input data subdirectories are located.
- target_dir: Base directory where output files will be saved.
subpaths:
- weather: Relative path from source_dir to the weather data CSV file.
- building_stock: Relative path from source_dir to the building stock CSV file.
- building_params: Relative path from source_dir to the building parameters CSV file.
columns:
- outdoor_temperature: (String) Specifies the exact column name in the weather CSV file that contains the outdoor temperature data in Degree Celsius.
calculation (Peak Load Optimization):
- use_peak_optimization: (Boolean) If True, the module attempts to adjust the room temperature setpoint (T_set) for each building to make the calculated peak heat load from the degree-day model match a target peak load. The target peak load is derived from the building's annual specific heat demand and its full load hours obtained from the building_stock data. This feature is only active if valid full_load_hours are available for the building archetype.
- peak_tolerance: (Float) The maximum allowed relative difference between the calculated peak load and the target peak load for the optimization to be considered successful (e.g., 0.10 means ±10%).
- max_iterations: (Integer) The maximum number of iterations the optimization algorithm will perform to find a suitable T_set.
- temperature_step: (Float) The amount (in °C) by which T_set is adjusted in each iteration step during optimization.
variation (Load Profile Variation):
- use_load_variation: (Boolean) If True, a random time shift is applied to the calculated hourly heat load profile of each building. This introduces some diversity in the timing of peak loads across the district making aggregated results more realistic.
- max_shift_hours: (Integer) The maximum number of hours (positive or negative) by which a building's load profile can be shifted. The actual shift for each building is chosen randomly between -max_shift_hours and +max_shift_hours. A value of 0 effectively disables the shift.
aggregation (District Load Aggregation):
- use_load_aggregation: (Boolean) If True, the individual building heat load profiles are aggregated.
- method: (String) Defines how aggregation is performed if use_load_aggregation is true:
  - "simple": All individual building heat loads are summed up into a single district total heat load profile.
  - "by_category": Buildings are grouped by their category ("residential" or "non-residential" from the building_params file), and a separate aggregated load profile is generated for each category.
  - "by_archetype": Buildings are grouped by their archetype ("single_family_house", "terraced_house", "multi_family_house", "apartment_block", "office", "trade", "education", "health", "hotels_and_restaurants" or "other_non_residential_buildings" from the building_params file), and a separate aggregated load profile is generated for each archetype.

Expected Output

Upon successful execution, the module saves its results in the directory specified by paths.target_dir.

Individual Building Results (CSV files):

Naming Convention: {building_id}_results.csv (e.g., B001_results.csv).
Content: A heat load time series CSV file for each processed building.
Columns:
- index: Datetime stamps matching the weather data input.
- outdoor_temperature: Outdoor temperature in Degree Celsius (°C) from the input weather file.
- degree_days: Calculated heating degree days (°C · timestep) for each timestep.
- heat_load: Calculated average heat load in Kilowatts (kW) for each timestep. This profile may be time-shifted if use_load_variation is enabled.

Aggregated Load Profile(s) (CSV files) (if aggregation.use_load_aggregation is True):

If aggregation.method is "simple":
- Filename: aggregated_total.csv
- Columns:
  - index: Datetime stamps matching the weather data input.
  - outdoor_temperature: Outdoor temperature in Degree Celsius (°C).
  - heat_load: Total aggregated district heat load in Kilowatts (kW).
If aggregation.method is "by_category":
- Naming Convention: aggregated_category_{category_name}.csv (e.g., aggregated_category_residential.csv).
- Columns (for each file):
  - index: Datetime stamps matching the weather data input.
  - outdoor_temperature: Outdoor temperature in Degree Celsius (°C).
  - heat_load: Total aggregated heat load for that specific category in Kilowatts (kW).
If aggregation.method is "by_archetype":
- Naming Convention: aggregated_archetype_{archetype_name}.csv (e.g., aggregated_archetype_single_family_house.csv).
- Columns (for each file):
  - index: Datetime stamps matching the weather data input.
  - outdoor_temperature: Outdoor temperature in Degree Celsius (°C).
  - heat_load: Total aggregated heat load for that specific archetype in Kilowatts (kW).

2b) Reduced Order Model (ROM) Calculation

This module calculates the hourly heat and cooling demand for each building using a dynamic Reduced Order Model (ROM). The implemented ROM is a 5R1C (5 resistances, 1 capacitance) thermal network model based on DIN EN ISO 13790. This approach provides a more detailed simulation than the degree-day based method by considering the building's thermal mass, solar gains, internal gains, and ventilation more explicitly.

The output consists of detailed time series data for each building including heating and cooling loads and internal temperatures and, if enabled, aggregated load profiles for the entire district or specific building groups.

To execute this module, run the script from this directory:

	src/rom_calculation.py

User Inputs

The module requires a comprehensive set of input files, which are specified in its Hydra configuration file located in configs/rom_calculation/YOUR_CONFIG_NAME.yaml.

Weather Data CSV File:

Specified by: paths.source_dir and subpaths.weather.
Content: Time series of hourly weather data for the location of interest. Must include columns for outdoor dry-bulb temperature, direct normal solar radiation, and diffuse horizontal solar radiation.
Key Columns: Specified by columns.outdoor_temperature, columns.direct_normal_radiation, and columns.diffuse_horizontal_radiation.

Archetype Component Definitions JSON File:

Specified by: paths.source_dir and subpaths.archetype_component_definitions.
Content: Defines the layers and materials for different building envelope components (e.g., "OuterWall_standard_1_SFH", "Window_retrofit_1_MFH") for various building archetypes, construction periods, and refurbishment states. Includes references to material IDs.

Note: The country specific JSON databases are located in the data/district_building/archetypes directory. The data structure and content is primarily derived from TEASER data for Germany, which is based on TABULA data. This dataset has been extended to include data for Italy, Norway, and Spain.

Archetype Component Fractions JSON File:

Specified by: paths.source_dir and subpaths.archetype_component_fractions.
Content: Specifies the fractional area of each building envelope component (e.g., "OuterWall1", "Window1") relative to the building's total net leased area, for different archetypes and construction year ranges.

Note: The country specific JSON databases, located in the data/district_building/archetypes directory. The content is derived from TABULA data.

Material Templates JSON File:

Specified by: paths.source_dir and subpaths.materials.
Content: A database of material properties (density, thermal conductivity, specific heat capacity, solar absorptance) keyed by material ID.

Note: The material templates JSON database is located in the data/district_building/materials directory. The content is derived from TABULA data and was primarily sourced from the MASEA databasis.

Usage Zone Conditions JSON File:

Specified by: paths.source_dir and subpaths.usage_zone_conditions.
Content: Defines typical usage patterns for different zone types (e.g., "Living", "Office"). Includes profiles for occupancy, internal gains (persons, machines, lighting), ventilation rates, and heating/cooling setpoint temperatures.

Note: The JSON databases are located in the data/district_building/usage_conditions directory. The data structure and content is primarily derived from TEASER data.

Usage Zone Fractions JSON File:

Specified by: paths.source_dir and subpaths.usage_zone_fractions.
Content: Specifies the fraction of the building's total area that each usage zone type (e.g., "Living", "Single office") occupies, for different building archetypes.

Note: The JSON databases are located in the data/district_building/usage_conditions directory. The data content is primarily derived from SIA 2024 data.

Building Stock CSV File:

Specified by: paths.source_dir and subpaths.building_stock.
Content: Same as used for the module described in section 2a) Degree Day Calculation. Primarily used for the fallback degree-day calculation if the ROM fails.

Building Parameters CSV File:

Specified by: paths.source_dir and subpaths.building_params.
Content: This is typically the output CSV (building_params.csv) from the "Building Identification and Initialization" module. It provides essential metadata for each building (location, archetype, year, area, etc.) required to initialize the Building object.

Key Configuration Parameters:

paths:
- source_dir: Base directory for all input files.
- target_dir: Base directory where output files will be saved.
subpaths: Defines relative paths from source_dir to each specific input file.
columns: Specifies the exact column names in the weather CSV file for:
- outdoor_temperature: (String) Outdoor air temperature in Degree Celsius (°C).
- direct_normal_radiation: (String) Direct Normal Irradiation (DNI) in W/m².
- diffuse_horizontal_radiation: (String) Diffuse Horizontal Irradiation (DHI) in W/m².
calculation:
- use_simplified_capacity: (Boolean)
  - If False (default), the thermal capacity (C_m) and effective mass area (A_m) of each zone are calculated using a detailed method based on the properties of its constituent material layers following ISO 13786.
  - If True, a simplified method is used where C_m and A_m are determined based on the building_class and floor area as per Table 12, EN ISO 13790 or similar standards like EN ISO 52016-1.
- building_class: (Integer, 0-4) If use_simplified_capacity is True, specifies the building weight class (0 for very light, 2 for medium, 3 for heavy and 4 for very heavy).
- initial_mass_temperature: (Float) The starting temperature in Degree Celsius (°C) for the thermal mass node (T_m) in the 5R1C model at the beginning of the simulation.
- degree_day_calculation (Fallback Parameters): This subsection contains parameters for the degree-day calculation used as a fallback if archetype data is not sufficient to perform the ROM calculation. This is especially the case for non-residential buildings.
  - These parameters (use_peak_optimization, peak_tolerance, max_iterations, temperature_step) function identically to those described in section 2a) Degree Day Calculation. Please refer to that section for details.
variation (Load Profile Variation):
- These parameters (use_load_variation, max_shift_hours) control the random time shifting of individual building load profiles. They function identically to those described in section 2a) Degree Day Calculation. Please refer to that section for details.
aggregation (District Load Aggregation):
- These parameters (use_load_aggregation, method) control how individual building load profiles are aggregated. They function identically to those described in section 2a) Degree Day Calculation. Please refer to that section for details.

Expected Output

Upon successful execution, the module saves its results in the directory specified by paths.target_dir.

Individual Building Results (CSV files):

Naming Convention: {building_id}_{method}_results.csv (e.g., B001_rom_results.csv or B002_degree_day_fallback_results.csv). The {method} part indicates whether the ROM or the fallback degree-day calculation was used.
Content: A load time series CSV file for each processed building.
Columns (for ROM Method):
- index : Datetime stamps matching the weather data input.
- outdoor_temperature: Outdoor temperature in Degree Celsius (°C).
- heat_load: Calculated heating demand in Kilowatts (kW).
- cooling_load: Calculated cooling demand (power, representing heat removed) in Kilowatts (kW).
- operative_temperature: Calculated operative temperature of the building zone(s) in Degree Celsius (°C).
- mass_temperature: Calculated temperature of the building thermal mass node in Degree Celsius (°C).
- air_temperature: Calculated indoor air temperature in Degree Celsius (°C).
- surface_temperature: Calculated average internal surface temperature in Celsius Degree (°C).
Columns (for Degree-Day Fallback Method):
- index: Datetime stamps matching the weather data input.
- outdoor_temperature: Outdoor temperature in Celsius Degree (°C).
- heat_load: Calculated heating demand in kilowatts (kW).
- cooling_load: Set to 0.0 as the fallback degree-day method doesn't calculate cooling.
- operative_temperature, mass_temperature, air_temperature, surface_temperature: Filled with NaN as these are not calculated by the fallback method.
Note: Load profiles may be time-shifted if variation.use_load_variation is enabled.

Aggregated Load Profile(s) (CSV files) (if aggregation.use_load_aggregation is True):

The structure and naming convention of these files (aggregated_total.csv, aggregated_category_{name}.csv, aggregated_archetype_{name}.csv) are identical to those described in the section 2a) Degree Day Calculation, but will contain aggregated heat_load and cooling_load (if applicable from ROM results). Please refer to that section for details.

3) Aggregated building energy demand analysis and waste heat potential analysis

This module assesses the potential for utilizing available industrial process heat to meet the aggregated district heating demand calculated in the previous simulation steps (either Degree Day or Reduced Order Model). It takes time series data for both the district's heat demand and the industrial process heat supply, aligns them temporally, and then performs a comparative analysis.

The outputs consists of detailed KPIs and plots for visualization, enabling an assessment of the waste heat utilization potential.

To execute this module, run the script from this directory:

    src/district_building_analysis.py

User Inputs

The module requires the following input files, which are specified in its Hydra configuration file located in configs/district_building_analysis/YOUR_CONFIG_NAME.yaml.

Aggregated District Heat Demand CSV File(s):

Specified by: paths.source_dir and files.pattern (for multiple files) or files.source_file (for a single file).
Content: Time series data of aggregated district heat demand. This is typically the output from the "Building energy simulation and heat demand timeseries aggregation" step (either Degree Day or ROM).
Key Column: The actual column name for heat load is implicitly assumed to be "heat_load" by the script when processing district data and must be present in the referenced CSV files.

Industrial Process Heat Timeseries CSV File:

Specified by: paths.industrial_process_heat_source_dir and files.industrial_process_heat_file.
Content: Time series data of available industrial process heat.
Key Column: The name of the column containing the industrial process heat data is specified by columns.industrial_process_heat_column.

Key Configuration Parameters:

paths:
- source_dir: (String) Directory containing the aggregated district heat demand CSV file(s).
- target_dir: (String) Directory where the output KPI CSV files and plot SVG files will be saved.
- industrial_process_heat_source_dir: (String) Directory containing the industrial process heat timeseries CSV file.
files:
- pattern: (String, Optional) If specified, the module processes all files in paths.source_dir that match this glob pattern (e.g., "aggregated_*.csv"). This allows analyzing multiple aggregated demand profiles (like total, by category or by archetype) in one run.
- source_file: (String, Optional) If pattern is not used, this specifies a single aggregated district heat demand CSV file to process from paths.source_dir.
- industrial_process_heat_file: (String) The filename of the CSV containing the industrial process heat timeseries, located in paths.industrial_process_heat_source_dir.
columns:
- industrial_process_heat_column: (String) The exact name of the column in the industrial_process_heat_file that contains the heat supply data (e.g., "Waste Heat [kWh]").

Expected Output

Upon successful execution, the module generates KPI data in CSV format and visualizations as SVG files. These are saved in a subdirectory within paths.target_dir named by experiment_id and a "plots" subfolder for image files. For each district heat demand file processed (if using pattern), a set of outputs is generated, identified by an identifier derived from the input filename (e.g., "total" from "aggregated_total.csv").

KPI CSV Files:

kpi_cumulative_energy_district_heat_{identifier}.csv: Contains annual energy-related KPIs:
- Metric: Name of the KPI (e.g., "Heat Load", "Industrial Process Heat", "Deficit/Surplus", "Coverage Percentage", "Required Heat Factor").
- Value: Calculated value for the metric.
- Unit: Unit of the metric (e.g., "kWh", "%", "-").
kpi_cumulative_peak_district_heat_{identifier}.csv: Contains annual peak power-related KPIs:
- Metric: Name of the KPI (e.g., "Peak Heat Load", "Industrial Process Heat at Peak", "Peak Deficit/Surplus", "Peak Coverage Percentage", "Peak Required Heat Factor").
- Value: Calculated value for the metric.
- Unit: Unit of the metric (e.g., "kW", "%", "-").
kpi_monthly_district_heat_{identifier}.csv: Contains monthly KPIs, including both energy and peak metrics broken down by month. Columns include:
- Heat Load - kWh, industrial_process Heat - kWh, Deficit/Surplus - kWh, Coverage Percentage - %, Required Heat Factor
- Peak Heat Load - kW, industrial_process Heat at Peak - kW, Peak Deficit/Surplus - kW, Peak Coverage Percentage - %, Peak Required Heat Factor

Plot SVG Files (Illustrative examples):

Time Series Comparison Plots:
- district_heat_comparison_{identifier}_full_year.svg: Shows the aligned district heat demand and industrial process heat supply over the full analysis period.
- district_heat_comparison_{identifier}_winter_week.svg: A focused view for a representative winter week.
- district_heat_comparison_{identifier}_summer_week.svg: A focused view for a representative summer week.
KPI Bar Plots:
- district_heat_kpi_{identifier}_energy_kpi.svg: Bar chart of the cumulative energy KPIs.
- district_heat_kpi_{identifier}_peak_kpi.svg: Bar chart of the cumulative peak power KPIs.
- district_heat_kpi_{identifier}_monthly_{kpi_metric_name}.svg: Separate bar charts for each monthly KPI metric (e.g., district_heat_kpi_total_monthly_Heat_Load_-_kWh.svg).

Scripts in the notes directory

Main Directory (`notes/`)

folder_cleaner.py - Cleans directories by removing temporary files and __pycache__ folders
mos_file_conversion.py - Converts Modelica simulation files between different formats

DR_scenario_helpers/

aux_peak_analysis.py - Analyzes peak loads and identifies periods with high auxiliary power consumption
storage_capacity_calculator.py - Calculates thermal storage capacities and charging/discharging power for hot water storage systems

idf_model_prep/

assign_csv_setp_idf.py - Assigns CSV-based setpoints to IDF model files
create_stp_assigment_csv.py - Creates CSV files for setpoint assignments in building models
setpoint_csv_creator.py - Generates CSV files with setpoints for building simulations

visualize_cluster_results/

visualize_all_results.py - Visualizes clustering results and creates comparison charts

Acknowledgements

This work has been supported by the FLEX4FACT project, funded by the European Union under the Horizon Europe research and innovation programme, under the grant agreement number 101058657. Views and opinions expressed are, however, those of the author(s) only and do not necessarily reflect those of the European Union. Neither the European Union nor the granting authority can be held responsible for them.

Name		Name	Last commit message	Last commit date
configs		configs
data		data
logs		logs
models		models
notebooks		notebooks
notes		notes
references		references
results		results
src		src
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation

FLEX4FACT Building-Industry Interaction Toolbox

Description

Getting started

Prerequisites

1. Install Python

2. Install Make

3. Install Poetry

4. Install EnergyPlus

Initial Project Setup

Project Setup for Template Developers

Toolbox Structure

Toolbox developer features

Pre-commit hooks

Automated HTML documentation with pdoc

Configuration management with Hydra

Single Building Analysis

Inputs for the Single Building Analysis

How to Prepare the EnergyPlus Input Files for Use in this Toolbox

1. Use an Ideal Loads-Based IDF File

2. Ensure Proper Ideal Loads Application

3. Generate CSV Files for Heating and Cooling Setpoints

4. Assign Thermal Zones to Setpoints

5. Modify the IDF File with Setpoint Schedules

How to run the Single Building Waste Heat Demand Response Analysis

Methodology

Expected Output Files

How to run the Single Building Internal Gains Demand Response Analysis

Methodology

Expected Output Files

District Buildings Analysis

1) Building Identification and Initialization

User Inputs

Expected Output

2) Building energy simulation and heat demand timeseries aggregation

2a) Degree Day Calculation

User Inputs

Expected Output

2b) Reduced Order Model (ROM) Calculation

User Inputs

Expected Output

3) Aggregated building energy demand analysis and waste heat potential analysis

User Inputs

Expected Output

Scripts in the notes directory

Main Directory (notes/)

DR_scenario_helpers/

idf_model_prep/

visualize_cluster_results/

Acknowledgements

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Main Directory (`notes/`)