Please cite us if you use this library:
Check our new documentation in GitHub Pages: pybuildingenergy docs.
Where to find our works:
- pysimhub .
- relife project - Under development ...
The new EPBD recast provides an update on building performance assessment through a methodology that must take into account various aspects such as the thermal characteristics of the building, the use of energy from renewable sources, building automation and control systems, ventilation, cooling, energy recovery, etc.
The methodology should represent the actual operating conditions, allow for the use of measured energy for accuracy and comparability purposes, and be based on hourly or sub-hourly intervals that take into account the variable conditions significantly impacting the operation and performance of the system, as well as internal conditions.
pyBuildingEnergy aims to provide an assessment of building performance both in terms of energy and comfort. In this initial release, it is possible to assess the energy performance of the building using ISO 52016-1:2018. Additional modules will be added for a more comprehensive evaluation of performance, assessing ventilation, renewable energies, systems, etc.
The actual calculation methods for the assessment of building performance are the following:
- the (sensible) energy need for heating and cooling, based on hourly or monthly calculations;
- the latent energy need for (de-)humidification, based on hourly or monthly calculations;
- the internal temperature, based on hourly calculations;
- the sensible heating and cooling load, based on hourly calculations;
- the moisture and latent heat load for (de-)humidification, based on hourly calculations;
- the design sensible heating or cooling load and design latent heat load using an hourly calculation interval;
- the conditions of the supply air to provide the necessary humidification and dehumidification.
The calculation methods can be used for residential or non-residential buildings, or a part of it, referred to as "the building" or the "assessed object".
ISO 52016-1:2018 also contains specifications for the assessment of thermal zones in the building or in the part of a building. The calculations are performed per thermal zone. In the calculations, the thermal zones can be assumed to be thermally coupled or not. ISO 52016-1:2018 is applicable to buildings at the design stage, to new buildings after construction and to existing buildings in the use phase.
--
The tool can use weather data coming from 2 main sources:
- PVGIS API (link) - PHOTOVOLTAIC GEOGRAPHICAL INFORMATION SYSTEM
.epwfile from Ladybug Tools EPWMap
More details in the example folder.
- Calculation of volume and energy need for domestic hot water according to EN 12831-3.
- Assessment of DHW system design heat load with EN 12831-3 storage switch points, time lag, effective reheating power and supply-curve sizing.
For the audit trail between the standard, code and outputs, open DHW EN 12831-3 Implementation Audit.
EmissionSystemCalculator evaluates space-heating and water-based space-cooling
emission effects before generation. It can be used to account for emitter and
control effects, equivalent internal-temperature changes, embedded emitter
losses, emission auxiliary electricity and annual emission expenditure factors.
For an audit trail between the standard, code and output files, open Emission EN 15316-2 Implementation Audit.
DistributionSystemCalculator evaluates water-based distribution systems for
space heating, space cooling and DHW. It calculates pipe thermal losses,
recoverable distribution losses, pump auxiliary electricity, recoverable pump
heat and recovered pump heat in the fluid before the generator calculation.
For the audit trail, open Distribution EN 15316-3 Implementation Audit.
StorageSystemCalculator evaluates single-volume Method B storage systems for
space heating and DHW. It calculates storage standing losses from product
standby-loss data or a direct heat-loss coefficient, storage charging pump
auxiliary electricity, recoverable storage losses and heat recovered in the
medium before the generator calculation.
For the audit trail, open Storage EN 15316-5 Implementation Audit.
HeatPumpSystemCalculator evaluates heat-pump generation for:
- space heating,
- domestic hot water (DHW),
- and an optional simplified reversible space-cooling branch with an EER map.
The heating and DHW calculation follows the detailed EN 15316-4-2 bin-method structure: outdoor/source temperature bins, product heating capacity and COP maps, source/sink temperature operating points, runtime/capacity checks, auxiliary energy, optional simplified storage losses, backup energy and SPF outputs. The runnable examples use the EN 16798 cooling modules by default; the older heat-pump EER cooling branch is still available with --calculation-path heat-pump-cooling.
For a clause-by-clause audit trail between the standard, the implementation and the output files, open Heat Pump EN 15316-4-2 Implementation Audit.
HeatPumpPerformanceDataCalculator normalizes heat-pump rating data from EN
14511-style capacity/COP/EER points and calculates EN 14825 part-load
inspection values. The examples use this path by default and apply the EN 14825
water-based part-load correction to heating/DHW COP and EN 16798-13 cooling EER.
For the audit trail between the standards, code and outputs, open EN 14511 / EN 14825 Product Performance Implementation Audit.
The heat-pump examples now treat space cooling with the cooling-side EN 16798 standards:
CoolingSystemCalculatorimplements EN 16798-9 operating conditions and the handoff of cooling requests to storage or generation.CoolingStorageSystemCalculatorimplements EN 16798-15 chilled-water storage heat gains and pump auxiliary energy.CoolingGenerationSystemCalculatorimplements EN 16798-13 compression cooling generation using cooling capacity/EER product maps or nominal EER fallback data.
For the audit trail between the standards, code and outputs, open Cooling EN 16798 Implementation Audit.
For the whole end-to-end workflow that interconnects EN ISO 52016, EN 12831-3, EN 15316, EN 16798, EN 14511 and EN 14825 in the Athens and Bolzano examples, open Heat-Pump Example Simulation Workflow Audit.
import pandas as pd
import pybuildingenergy as pybui
heating_map = pd.DataFrame({
"source_temperature_C": [-7, -7, 2, 2, 7, 7],
"sink_temperature_C": [35, 55, 35, 55, 35, 55],
"capacity_kW": [5.0, 4.0, 6.0, 5.0, 7.0, 6.0],
"cop": [3.2, 2.4, 3.8, 2.8, 4.2, 3.2],
})
cooling_map = pd.DataFrame({
"source_temperature_C": [25, 25, 35, 35],
"sink_temperature_C": [7, 18, 7, 18],
"capacity_kW": [5.0, 6.0, 4.0, 5.0],
"eer": [3.0, 3.6, 2.5, 3.1],
})
loads = pd.DataFrame({
"T_ext": [-5, 0, 5, 25],
"Q_H_kWh": [4.0, 3.0, 1.0, 0.0],
"Q_C_kWh": [0.0, 0.0, 0.0, 2.0],
"Q_W_kWh": [0.5, 0.5, 0.5, 0.5],
})
calc = pybui.HeatPumpSystemCalculator({
"heating_performance_map": heating_map,
"dhw_performance_map": heating_map,
"cooling_performance_map": cooling_map,
"source_type": "air",
"demand_unit": "kWh",
"dhw_target_temperature_C": 55,
"dhw_sink_temperature_C": 55,
"external_auxiliary_power_W": 100,
})
result = calc.run_timeseries(loads)
print(result.summary["SPF_HW_gen"])
print(result.summary["SEER_C_gen"])The runnable examples are:
python -m pip install -r requirements.txt
python examples/heat_pump_15316_4_2_example.py --scenario athens
python examples/heat_pump_15316_4_2_example.py --scenario bolzanoThere is also a Bolzano convenience wrapper:
python examples/heat_pump_15316_4_2_bolzano_example.pyThe Athens scenario uses an Athens PVGIS weather location, a Greece DHW calendar, the EN 12831-3 Annex B Table B.2 single-family dwelling hourly DHW profile and a 26 C cooling setpoint. The Bolzano scenario uses Bolzano coordinates, an Italy DHW calendar, the same residential Annex B hourly DHW profile, a tighter solar-exposed envelope and an air-to-water heat-pump map sized for a 120 m2 useful-floor-area residential building. In both cases the example geometry is a two-floor building with a 60 m2 footprint; roof and ground-slab areas are therefore 60 m2, while net_floor_area remains 120 m2.
Each scenario runs ISO52016 for the example building, applies EN 15316-2 emission effects, EN 15316-3 distribution effects, EN 15316-5 heating/DHW storage effects and the EN 16798 cooling-side modules by default, calculates an hourly DHW profile and the EN 12831-3 DHW design sizing, runs the generator calculations and writes:
examples/outputs/heat_pump_15316_4_2_<scenario>/iso52016_loads_with_dhw.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/dhw_12831_3_design_timeseries.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/dhw_12831_3_design_summary.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/building_geometry_summary.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/emission_15316_2_hourly_results.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/emission_15316_2_summary.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/distribution_15316_3_hourly_results.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/distribution_15316_3_summary.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/storage_15316_5_hourly_results.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/storage_15316_5_summary.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/cooling_16798_9_hourly_results.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/cooling_16798_9_summary.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/cooling_storage_16798_15_hourly_results.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/cooling_storage_16798_15_summary.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/cooling_generation_16798_13_hourly_results.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/cooling_generation_16798_13_summary.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/performance_14511_14825_rating_points.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/performance_14511_14825_heating_map.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/performance_14511_14825_cooling_map.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/performance_14511_14825_summary.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/heat_pump_hourly_allocated_results.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/heat_pump_bin_results.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/heat_pump_summary.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/combined_generation_summary.csvexamples/outputs/heat_pump_15316_4_2_<scenario>/inspection_index.html
Open inspection_index.html in a browser to inspect the visual outputs. The page links to:
- a user-facing overview of annual loads, final electricity, monthly trends, seasonal performance and useful-area intensities;
- a workflow handoff plot that shows how heating, cooling and DHW loads move through the implemented standards;
- sanity-check plots for geometry, peak loads versus active capacity, backup shares and unmet loads;
- EN 12831-3 DHW design-day needs, storage switch curves, residual storage and effective reheating power;
- the existing ISO52016 building report generated with
Graphs_and_report; - the whole simulation workflow audit trail;
- daily input time series for heating, cooling, DHW and temperatures;
- EN 15316-2 emission time series and monthly aggregate plots;
- EN 15316-3 distribution time series and monthly aggregate plots;
- EN 15316-5 storage time series and monthly aggregate plots;
- EN 16798-9 cooling operating-condition time series;
- EN 16798-15 cooling storage time series and aggregate plots;
- EN 16798-13 cooling generation time series and bin plots;
- EN 14511 / EN 14825 rating and part-load performance plots;
- allocated heat-pump electricity time series;
- monthly demand, electricity, SPF and SEER summaries;
- bin-method energy balance plots;
- bin COP/EER, capacity and runtime plots;
- an annual energy-flow Sankey diagram.
The default calculation path is the full chain:
python examples/heat_pump_15316_4_2_example.py --scenario athens --calculation-path full
python examples/heat_pump_15316_4_2_example.py --scenario bolzano --calculation-path fullTo keep the full subsystem chain but use the previous synthetic product maps without EN 14825 part-load correction, use:
python examples/heat_pump_15316_4_2_example.py --scenario athens --calculation-path full --performance-data-method simpleTo combine the direct ISO52016/DHW path with the new EN 14511/EN 14825 product performance stage, use:
python examples/heat_pump_15316_4_2_example.py --scenario athens --calculation-path simple --performance-data-method en14511-14825By default, the full path also runs EN 12831-3 DHW system sizing and passes the selected DHW storage volume and design flow into EN 15316-5 and EN 15316-3. To keep the earlier fixed DHW storage/distribution assumptions, use:
python examples/heat_pump_15316_4_2_example.py --scenario athens --dhw-design-method simpleThe EN 12831-3 sizing target can be changed with --dhw-sizing-mode check,
--dhw-sizing-mode size_storage, --dhw-sizing-mode size_power or
--dhw-sizing-mode auto.
To run the previous detailed path with EN 15316-2 and EN 15316-3 but without EN 15316-5 storage, use:
python examples/heat_pump_15316_4_2_example.py --scenario athens --calculation-path emission-distribution
python examples/heat_pump_15316_4_2_example.py --scenario bolzano --calculation-path emission-distributionTo run only EN 15316-5 storage between direct ISO52016/DHW loads and the heat pump, use:
python examples/heat_pump_15316_4_2_example.py --scenario athens --calculation-path storage-only
python examples/heat_pump_15316_4_2_example.py --scenario bolzano --calculation-path storage-onlyTo bypass only the EN 16798-15 cooling storage module while retaining EN 15316-2, EN 15316-3, EN 15316-5 and EN 16798-13, use:
python examples/heat_pump_15316_4_2_example.py --scenario athens --calculation-path no-cooling-storage
python examples/heat_pump_15316_4_2_example.py --scenario bolzano --calculation-path no-cooling-storageTo retain the earlier reversible heat-pump cooling branch instead of EN 16798-13, use:
python examples/heat_pump_15316_4_2_example.py --scenario athens --calculation-path heat-pump-cooling
python examples/heat_pump_15316_4_2_example.py --scenario bolzano --calculation-path heat-pump-coolingTo run EN 15316-2 emission effects but bypass EN 15316-3 distribution and EN 15316-5 storage, use:
python examples/heat_pump_15316_4_2_example.py --scenario athens --calculation-path emission-only
python examples/heat_pump_15316_4_2_example.py --scenario bolzano --calculation-path emission-onlyTo reproduce the earlier simple calculation without EN 15316-2, EN 15316-3, EN 15316-5 or EN 16798 effects, use:
python examples/heat_pump_15316_4_2_example.py --scenario athens --calculation-path simple
python examples/heat_pump_15316_4_2_example.py --scenario bolzano --calculation-path simpleSimple mode writes to examples/outputs/heat_pump_15316_4_2_<scenario>_simple
unless --output-dir is specified.
By default the script uses PVGIS weather for the selected scenario, so it needs internet access. To run with a local EPW file instead:
python examples/heat_pump_15316_4_2_example.py --scenario athens --weather-source epw --path-weather-file path/to/weather.epwThe script checks that the ISO52016 run produces both heating and cooling demand and that DHW demand is non-zero before running the heat-pump calculation.
The EN 15316 series covers the calculation method for system energy requirements and system efficiencies. This family of standards is an integral part of the EPB set and covers:
- EN 12831-3: Domestic hot-water energy needs and DHW design heat-load/sizing
- EN 15316-1: General and expression of energy performance (Modules M3-1, M3-4, M3-9, M8-1, M8-4)
- EN 15316-2: Emission systems (heating and cooling)
- EN 15316-3: Distribution systems (DHW, heating, cooling)
- EN 15316-4-X: Heat generation systems:
- 4-1: Combustion boilers
- 4-2: Heat pumps
- 4-3: Solar thermal and photovoltaic systems
- 4-4: Cogeneration systems
- 4-5: District heating
- 4-7: Biomass
- EN 15316-5: Storage systems
- EN 16798-9: Cooling systems, operating conditions and M4-1/M4-4 handoff
- EN 16798-13: Cooling generation, compression systems
- EN 16798-15: Cooling storage
- EN 16798-13 non-compression cooling generators, such as absorption, adsorption, desiccant or evaporative cooling
- EN 14511-1: Heat-pump and chiller rating terms, including COP and EER definitions
- EN 14511-2: Rating and application-condition temperature points for air-to-water heat pumps and chillers
- EN 14825: Part-load capacity-ratio and degradation-coefficient correction for heating COP and cooling EER
For space heating, applicable standards include EN 15316-1, EN 15316-2-1, EN 15316-2-3 and the appropriate parts of EN 15316-4 depending on the system type, including losses and control aspects.
EN ISO 52016 defines that:
The calculation now allows the definition of several thermal and non-thermal zones adjacent to the considered zone.
External Adjacent - Unheated Zone: It is possible to define an unheated adjacent zone in contact with the considered thermal zone.
The length of the separating wall may be entirely or partially connected to the considered zone.
The calculation involves:
- Determining the internal temperature of the non-thermal zone.
- Evaluating the heat exchange with the thermal zone.
External Adjacent - Heated Zone: In this case, the wall between the two zones is considered adiabatic (no heat exchange). Adjusted Coefficient: To account for the different temperatures between zones (e.g., thermal and non-thermal), an adjusted coefficient is calculated.
The standard defines various assumptions specified in section 6.5.3 - Assumptions and specific conditions.
In general, it aims to simplify the zoning approach by reducing the number of zones to a minimum (ISO EN 52016-2:2018).
It also emphasizes that:
A multi-zone calculation with interactions between the zones requires significant and often arbitrary input data (on transmission properties and air flow direction and size).
It can also lead to other technical and procedural complications that add uncertainties to the results.
A further complication can be the involvement of different heating, cooling and ventilation systems for different zones, which adds to the complexity and arbitrariness of the input and modelling.
Key Remark: Therefore, the benefits of calculations with thermally coupled zones can be smaller than the drawbacks.
Compute the ventilation heat transfer coefficient [W·K⁻¹] of the thermal zone either:
- from natural ventilation (ISO 16798-7:2017, single-sided airing via windows, wind/stack), or
- from occupancy-driven flow (simplified volumetric rate per floor area).
For more detail refers to natural ventilation.
Due to the need to have profiles of occupancy and consumption of buildings for some uses, tables of profiles useful for evaluating, occupancy, lights, heating, cooling, internal gains have been implemented. These tables are provided by ANNEX A of ISO EN 16798-1. In the tool they are available here: Table
A sensible, balanced-airflow air-handling-unit model based on EN 16798-5-1 can
be configured as a mechanical_supply ventilation component. It computes heat
recovery, bypass and frost behaviour, capacity-limited heating/cooling coils
and fan electricity per timestep, and couples into the ISO 52016-1 zone
balance as a supply-air stream. Existing configurations are unchanged unless
the component is configured.
"building_parameters": {
"ventilation": {
"components": [
{ # envelope leakage: no profile, always active
"name": "infiltration",
"ventilation_type": "constant_ach",
"air_changes_per_hour": 0.15,
},
{ # balanced AHU with sensible heat recovery
"name": "ahu",
"ventilation_type": "mechanical_supply",
"supply_flow_m3_h": 3600.0,
"sensible_heat_recovery_efficiency": 0.784,
"supply_temperature_setpoint_c": 18.0,
"heating_coil_max_power_w": 15000.0,
"supply_fan_specific_power_w_per_m3_s": 750.0,
"extract_fan_specific_power_w_per_m3_s": 750.0,
"profile": "ventilation_profile", # flow fraction in [0, 1]
},
],
},
},For the implemented / simplified / not-included scope, all configuration keys and the hourly diagnostic columns, open Ventilation AHU EN 16798-5-1 Implementation Audit.
The data provided before being used for the simulation are processed and evaluated to be considered fit for the simulation. This process includes a series of checks that allow to identify any potential errors. For more details refers to Input Quality check.
The library is developed with the intent of demonstrating specific elements of calculation procedures in the relevant standards. It is not intended to replace the regulations but to complement them, as the latter are essential for understanding the calculation. This library is meant to be used for demonstration and testing purposes and is therefore provided as open source, without protection against misuse or inappropriate use.
The information and views set out in this document are those of the authors and do not necessarily reflect the official opinion of the European Union.
Install the latest version of the library:
pip install pybuildingenergy- For building inputs refer to Building Inputs
- For heating system inputs (EN 15316-1) refer to Heating System Input
New examples will follow soon...
Bug reports / Questions
If you encounter a bug, please create an issue detailing it. Provide steps to reproduce and a code snippet if possible.
Code contributions
We welcome and appreciate contributions! Every contribution, no matter how small, makes a difference.
- Free software: BSD 3-Clause License
- Documentation: pyBuildingEnergy Docs
This work was carried out within European projects:
- Infinite - EU Horizon 2020 (grant agreement No. 958397)
- Moderate - Horizon Europe (grant agreement No. 101069834)
- BREEZE - Building Renovation Efforts for Zero Emission Buildings, co-funded by the European Union LIFE programme (grant agreement No. 101215197)
The DHW calculation was developed with data and methods from the EPB Center spreadsheet.
- EPB Center - Energy Performance of Buildings Directive (EPBD)
- REHVA Journal - EN ISO 52000 family of standards
- European Commission - Energy Performance of Buildings Directive
- Directive (EU) 2024/1275 - Official Journal of the EU, May 8, 2024
- EN ISO 52010-1:2018 - External climatic conditions
- EN ISO 52016-1:2018 - Energy needs for heating and cooling
- EN ISO 52016-2:2018 - Explanation and justification of ISO 52016-1 and ISO 52017-1
- EN 12831-3:2017 - DHW systems heat load and characterization
- EN 14511-1:2022 - Air conditioners, liquid chilling packages and heat pumps: terms and definitions
- EN 14511-2:2022 - Air conditioners, liquid chilling packages and heat pumps: test conditions
- EN 14825:2022 - Seasonal performance and part-load conditions for air conditioners, chillers and heat pumps
- EN 15316-1:2018 - System energy requirements and efficiencies
- EN 15316-2:2017 - Space emission systems
- EN 15316-3:2017 - Distribution systems
- EN 15316-4-2:2008 - Heat-pump generation systems
- EN 15316-5:2017 - Storage systems
- EN 16798-9:2017 - Cooling systems
- EN 16798-13:2017 - Cooling generation
- EN 16798-15:2017 - Cooling storage
- EN 16798-7 & 16798-1 - Ventilation standards
