User case

This guide demonstrates how to create and configure a new scenario in EBM by introducing a hypothetical future building code: TEK30. Scenario-based modeling in EBM allows users to explore alternative planning assumptions, regulatory changes, and energy performance impacts by managing separate input directories.

The TEK30 scenario showcases how to:

• Create a dedicated input directory for scenario data

• Define a new building code and its timeline

• Specify energy need across building categories

• Configure heating system shares

• Optionally adjust lighting improvements

Working with input

EBM supports scenario-based modeling by allowing users to create and manage separate input directories. This enables flexible experimentation with different assumptions and configurations.

Creating an input directory for a scenario

To create a new scenario in EBM, open your preferred terminal and run the following command:

ebm --create-input --input=user-case-tek30

The input directory will be created using the path defined by the --input option. In this case the new input files will be created as the subdirectory 📁user-case-tek30 in the current working directory.

If the directory you name does not exist, the program will attempt to create it. All input files necessary to run ebm will be created, with their default values, in the supplied path.

Tip

You can choose any valid directory name, but it is a good idea to limit to letters, numbers, and underscore. Avoid using space.

Using the input directory

Once the input directory is ready, you can run the model using:

ebm --input=user-case-tek30

The model result as defined in 📁user-case-tek30 will be written to the subdirectory 📁output.

See also

Results

User case: Add a new building code

This example demonstrates how to use EBM scenario functionality by adding a new building code. TEK30 represents a hypothetical future building code introduced as part of a user case to demonstrate how EBM handles scenario-based modeling.

To add TEK30 to ebm you have to edit a number of files in the subdirectory 📁user-case-tek30

• Add the new building code to the model in 🧾 building_code_parameters.csv

• Define energy need for TEK30 in 🧾 energy_need_original_condition.csv

• Specify heating system shares in 🧾 heating_system_initial_shares.csv

This process showcases how EBM can be extended to simulate future regulations or alternative planning assumptions.

Add the new building code

The timeline and classification of building codes used by EBM are defined in the csv file 🧾 building_code_parameters.csv in 📁user-case-tek30. To include TEK30 in your scenario, you must first define it in that file.

You can edit 🧾 building_code_parameters.csv using a plain text editor (e.g., Notepad) or spreadsheet software such as Microsoft Excel or LibreOffice Calc.

Tip

When using spreadsheet software, ensure the correct formatting is preserved when saving as CSV.

• Use comma , as the delimiter

• Use full stop . as the decimal separator

Add the following line to 🧾 building_code_parameters.csv in 📁user-case-tek30 to define TEK30 as a new building code entry:

TEK30,2040,2030,2050

The comma-separated columns in the line you added represent the following: building code, building year (in relation to S-curves), start year for the building code, and end year for the building code. Both the start and end years are inclusive.

See also

Other -> building_code under Input constraints

EBM does not allow overlapping periods in 🧾 building_code_parameters.csv. Since TEK17 currently ends in 2050, we must adjust the end year for TEK17 as well:

To avoid overlapping periods, update the TEK17 entry in 🧾 building_code_parameters.csv as follows:

TEK17,2025,2020,2029

When done correctly 🧾 building_code_parameters.csv in 📁user-case-tek30 should look like the example below.

Formatted tableRaw CSVDownload

Below is the updated content of 🧾 building_code_parameters.csv. The new TEK30 entry and the adjusted end period for TEK17 are outlined in bold.

Complete building_code_parameters.csv

building_code	building_year	period_start_year	period_end_year
PRE_TEK49	1945	0	1948
TEK49	1962	1949	1968
TEK 69	1977	1969	1986
TEK87	1991	1987	1996
TEK97	2002	1997	2006
TEK07	2012	2007	2010
TEK10	2018	2011	2019
TEK17	2025	2020	2029
TEK30	2040	2030	2050

Define energy need for TEK30

All building codes must have it’s energy need defined by 🧾 energy_need_original_condition.csv in 📁user-case-tek30. For this scenario we assume a TEK30 have a 2/3 energy need reduction for heating_rv and 1/4 reduction for heating_dhw, cooling, fans_and_pumps and electrical_equipment.

Summary tableFormatted tableRaw csvDownload

Open formatted table and raw csv for complete listings

Summary energy_need_original_condition.csv

building_category	building_code	purpose	kwh_m2
house	TEK30	heating_rv	15.83
house	TEK30	heating_dhw	16.76
house	TEK30	fans_and_pumps	3.61
house	TEK30	electrical_equipment	9.86
house	TEK30	cooling	0.0
…	…	…	…
storage_repairs	TEK30	heating_rv	25.27
storage_repairs	TEK30	heating_dhw	5.64
storage_repairs	TEK30	fans_and_pumps	8.5
storage_repairs	TEK30	electrical_equipment	13.22
storage_repairs	TEK30	cooling	8.16

For clarity, the table above have been sorted and kwh_m2 values rounded to two decimal places.

Specify heating system shares

The final input file that needs to be modified is 📁user-case-tek30 🧾 heating_system_initial_shares.csv. This file tells EBM what the share of each heating system is for a given building code. Since TEK30 is a new building code, it requires its own definition in this file.

Summary tableformatted tableraw csv

Summary heating_system_initial_shares.csv

building_category	building_code	heating_systems	year	heating_system_share
office	TEK30	DH	2023	0.3182453573763764
nursing_home	TEK30	DH - Bio	2023	0.0002142250969049
office	TEK30	HP Central heating - Gas	2023	7.196160696758601e-05
school	TEK30	HP Central heating - Gas	2023	7.196160696758601e-05
school	TEK30	HP Central heating - Electric boiler	2023	0.364043511904947
school	TEK30	HP Central heating - Bio	2023	0.00019362655741
kindergarten	TEK30	HP Central heating - Electric boiler	2023	0.364043511904947
…	…	…	…	…
sports	TEK30	Electric boiler	2023	0.0596845137090352
sports	TEK30	Electricity	2023	0.0706818896188211
sports	TEK30	DH	2023	0.3182453573763764
sports	TEK30	HP Central heating - Bio	2023	0.00019362655741
sports	TEK30	HP - Electricity	2023	0.1632849356867121
sports	TEK30	Electricity - Bio	2023	0.0216740945571909
sports	TEK30	Gas	2023	0.0016565044759408
sports	TEK30	HP Central heating - Electric boiler	2023	0.364043511904947
sports	TEK30	HP Central heating - Gas	2023	7.196160696758601e-05
sports	TEK30	Electric boiler - Solar	2023	0.0002493794096936

Similarly to TEK17, there is no need to add TEK30 to 🧾 area.csv in 📁user-case-tek30 as all the area in both TEKs will be built after the start year 2020.

Re-run the model

Once you have adapted 🧾 building_code_parameters.csv, 🧾 energy_need_original_condition.csv and 🧾 heating_system_initial_shares.csv to TEK30, you cat re-run the model.

ebm --input=user-case-tek30

The model results can be found in the subdirectory named 📁output.

Tip

You can have ebm open the results as they are written by using the --open option

ebm --input=user-case-tek30 --open

Extra credit

The input files 🧾 energy_need_improvements.csv, 🧾 heating_system_forecast.csv, 🧾 improvement_building_upgrade.csv and 🧾 energy_need_behaviour_factor.csv have defined default values under the column building_code that will apply to TEK30. For extra credit you may override the defaults with your own values.

energy need improvements

In EBM there is a 0.5% yearly reduction in energy need for defined the building category house defined in 🧾 energy_need_improvements.csv in 📁user-case-tek30. Since TEK30 is a new code from TEK30 one can assume that no such reduction will happen due to the fact that the reduction will already be define in the building code.

You can add a line to 🧾 energy_need_improvements.csv in 📁user-case-tek30 if you think that there is no yearly reduction lighting with TEK30.

default,TEK30,lighting,yearly_reduction,2031,0.0,2050

energy_need_original_condition

This file sets baseline lighting energy need (kWh/m²) for different building types and codes used in the EBM model.

default values

energy_need_original_condition.csv where purpose is lighting

building_category	building_code	purpose	kwh_m2
house	default	lighting	8.2
apartment_block	default	lighting	8.2
retail	default	lighting	50.2
office	default	lighting	22.55
kindergarten	default	lighting	18.79
school	default	lighting	19.35
university	default	lighting	22.55
hospital	default	lighting	42.05
nursing_home	default	lighting	42.05
hotel	default	lighting	42.05
sports	default	lighting	18.58
culture	default	lighting	20.67
storage_repairs	default	lighting	16.91

By default, all building codes have the same energy need for lighting per square metre. As an illustration on how one can redefine energy need we will modify the file 🧾 energy_need_original_condition.csv in 📁user-case-tek30.

If you open the file 🧾 energy_need_original_condition.csv in 📁user-case-tek30 with a spreadsheet application or text editor, you’ll see that all building categories with lighting as their purpose use the building code “default.” This default value acts as a catch-all, telling EBM to apply the specified kWh/m² value for lighting unless a more specific definition is provided.

Example energy_need_original_condition.csv

building_category	building_code	purpose	kwh_m2
apartment_block	default	lighting	8.2
house	default	lighting	8.2
house	TEK17	lighting	5.0
house	TEK10	lighting	6.2

In this example:

• All apartment_block buildings, regardless of code, use 8.2 kWh/m² for lighting.

• House buildings also default to 8.2 kWh/m², except:

  • Houses with TEK10 use 6.2 kWh/m²

  • Houses with TEK17 use 5.0 kWh/m²

Defining explicit lighting for TEK30

While the default values for lighting defined by 🧾 energy_need_original_condition.csv in 📁user-case-tek30 are handy for editing, you might want to set explicit values for TEK30 so that you can define specific values. Let’s imagine that the energy need for lighting with TEK30 is half of what earlier building code standards required.

Excerpt TEK30 lighting energy_need_original_condition.csv

building_category	building_code	purpose	kwh_m2
house	TEK30	lighting	4.1
apartment_block	TEK30	lighting	4.1
retail	TEK30	lighting	25.1
office	TEK30	lighting	11.27
kindergarten	TEK30	lighting	9.4
school	TEK30	lighting	8.2
university	TEK30	lighting	11.26
hospital	TEK30	lighting	21.03
nursing_home	TEK30	lighting	21.03
hotel	TEK30	lighting	21.0
sports	TEK30	lighting	9.29
culture	TEK30	lighting	10.34
storage_repairs	TEK30	lighting	8.45

Defining common lighting for TEK17 and TEK30

To simplify energy need definitions across building codes, you can combine TEK17 and TEK30 using the + symbol. This approach allows you to assign a shared lighting energy value to multiple building codes for the same building category.

You can also combine building categories in the same way. This is especially useful when several categories or codes share identical lighting requirements, helping reduce duplication and streamline your definitions.

The example below demonstrates how to group both building codes and building categories that share the same lighting energy need values.

Excerpt TEK30+TEK17 lighting energy_need_original_condition.csv

building_category	building_code	purpose	kwh_m2
apartment_block+house	TEK17+TEK30	lighting	4.1
retail	TEK17+TEK30	lighting	25.1
office	TEK17+TEK30	lighting	11.27
kindergarten	TEK17+TEK30	lighting	9.4
school	TEK17+TEK30	lighting	8.2
university	TEK17+TEK30	lighting	11.26
hospital+nursing_home+hotel	TEK17+TEK30	lighting	11.01
sports	TEK17+TEK30	lighting	9.29
culture	TEK17+TEK30	lighting	10.34
storage_repairs	TEK17+TEK30	lighting	8.45

energy need behaviour factor

In 🧾 energy_need_behaviour_factor.csv in 📁user-case-tek30 there is a specific value set for behaviour factor for TEK07, TEK10 and TEK17. It is sensible to add the new building code TEK30 to the file building_code column:

This row:

house,TEK07+TEK10+TEK17,lighting,0.85,2020,2050

Becomes:

house,TEK07+TEK10+TEK17+TEK30,lighting,0.85,2020,2050

Last Updated on 2025-11-06

Version: 1.0.1.