Setting-up your first model (tutorial)

This is a step-by-step guide on how to set up your first model using the EBM model.

1. How to run the program from the command line?

For the commands to be excuted locally or in an IDE, it must be launched as a module rather than a program.

Example:

ebm heating-systems

should be excuted like:

python -m ebm heating-systems

2. Additional arguments

ebm <--switch> <step> <output filename>

The parameters listed above are optional. The default choice for the step parameter is energy-use, and the default output filename is output/ebm_output.xlsx.

Difference between switch and step
Option	Description
switch	Always preceded by `--`. Used to ensure different running options a user may want to use. Examples include: `--help`, `--version`, `--debug` and `--open`. A more detailed explanation of the options can be found using the `--help` switch.
step	Represents the calculation step you want to run. The steps are sequential. Any prerequisite to the chosen step will run automatically. The four steps available are: `area-forecast`, `energy-requirements`, `heating-systems` and `energy-use`.

3. Example of how to run your first model: test

Help command

Typing ebm –help will give you a list of most parameters:

usage: ebm [-h] [--version] [--debug] [--output-format {pretty,xlsx,csv}] [--categories [CATEGORIES ...]] [--input [INPUT]] [--force] [--open] [--csv-delimiter CSV_DELIMITER]
        [--create-input] [--dataset DATASET] [--horizontal-years]
        [{area-forecast,energy-requirements,heating-systems,energy-use,list-input,create-input}] [output_file] [create_input_dir]

 Calculate EBM energy use 1.1.1

 positional arguments:
   {area-forecast,energy-requirements,heating-systems,energy-use,list-input,create-input}

                         The calculation step you want to run. The steps are sequential. Any prerequisite to the chosen step will run
                             automatically.
                         list-input: List available input datasets bundled with ebm.
                         create-input: Create input directory containing all required files in the current working directory.
   output_file           The location of the output to be written. default: output\ebm_output.xlsx
                             For energy-use, this is treated as an output directory and multiple files will be written there.
                             For other steps, this is treated as a single output file.
                             If the file already exists the program will terminate without overwriting.
                             Use "-" to output to the console instead. This is not supported for energy-use.
                             For create-input, this is the dataset name (e.g. calibrated).
   create_input_dir      The location of the input directory to be created. default: current working directory

 options:
   -h, --help            show this help message and exit
   --version, -v         show program's version number and exit
   --debug               Run in debug mode. (Extra information written to stdout)
   --output-format {pretty,xlsx,csv}, -F {pretty,xlsx,csv}
                         Output file format for step energy-use.
                                     Choices:
                                      - pretty: Excel with style and filters
                                      - xlsx: Plain Excel format
                                      - csv: Comma-separated values format (CSV). See also --csv-delimiter
                                      default: pretty

   --input [INPUT], --input-directory [INPUT], -i [INPUT]
                         path to the directory with input files
   --force, -f           Write to <filename> even if it already exists
   --open, -o            Open output file(s) automatically when finished writing. (Usually Excel)
   --csv-delimiter CSV_DELIMITER, --delimiter CSV_DELIMITER, -e CSV_DELIMITER
                         A single character to be used for separating columns when writing csv. Default: "," Special characters like ; should be quoted ";"
   --create-input
                         Create input directory containing all required files in the current working directory
   --dataset DATASET     The built-in dataset to use when creating input with --create-input.
                         Available datasets: __pycache__, long_analysis_2024, original, short_analysis_2025.
                         Default: calibrated.
                         Use `list-input` to list available datasets.
   --horizontal-years, --horizontal, --horisontal
                         Show years horizontal (left to right)

4. Calculate the projected annual area requiring heating

# This is the default cammand, where the output file is area-forecast-vertical.xlsx located
# in the output directory
# The output file will be written in vertical format
ebm area-forecast output/area-forecast-vertical.xlsx

Output from using the command above
Building_category	TEK	Building_condition	Year	m2
House	PRE_TEK49	original_condition	2020	941109.5047
house	PRE_TEK49	original_condition	2021	494082.49
house	PRE_TEK49	original_condition	2022	494082.49

If the user wants the output file in horizontal format, the user can use the following command:

# This command will write the output file in horizontal format with the name area-forecast.xlsx
ebm --horizontal area-forecast output/area-forecast.xlsx

Output from using the command above (horizontal format)
building_category	TEK	building_condition	U	2020	2021	2022
house	PRE_TEK49	original_condition	m2	941 110	494 082	494 082
house	PRE_TEK49	small_measure	m2	1529 303	1976 330	1976 330
house	PRE_TEK49	renovation	m2	0	0	0

5. Calculate energy-requirements

The energy-requirements is calculated by multiplying the heating demand per square meter by the area from the previous step.

# This is the default cammand, where the output file is energy-requirements-vertical.xlsx located
# in the output directory
ebm energy-requirements output/energy-requirements-vertical.xlsx

Output from using the command above
building_category	TEK	building_condition	year	purpose	m2	original_kwh_m2	reduction_yearly	reduction_policy	reduction_condition	reduced_kwh_m2	behavior_factor	kwh_m2	energy_requirement
house	PRE_TEK49	original_condition	2020	heating_rv	941109.5047	155.290712	1	1	1	155.290712	1	155.290712	146145565.1
house	PRE_TEK49	original_condition	2020	heating_dhw	941109.5047	29.78125	1	1	1	29.78125	1	29.78125	28027417.44
house	PRE_TEK49	original_condition	2020	fans_and_pumps	941109.5047	0.58125	1	1	1	0.58125	1	0.58125	547019.8996

If the user wants the output file in horizontal format, the user can use the following command:

# This command will write the output file in horizontal format with the name energy-requirements.xlsx
ebm --horizontal energy-requirements output/energy-requirements.xlsx

Output from using the command above (horizontal format)
building_category	TEK	building_condition	U	2020	2021	2022
house	PRE_TEK49	original_condition	GWh	199	104	104
house	PRE_TEK49	small_measure	GWh	307	395	394
house	PRE_TEK49	renovation	GWh	0	0	0

6. Energy consumption

The energy consumption is calculated by multiplying the energy requirements from the previous step by the efficiency factor.

# This is the default command, where the output file is heating-systems-vertical.xlsx located
# in the output directory
ebm heating-systems output/heating-systems-vertical.xlsx

Output from using the command above
building_category	building_condition	purpose	TEK	year	heating_systems	heating_system_share	Grunnlast energivare	Grunnlast virkningsgrad	Spisslast energivare	Spisslast virkningsgrad	Ekstralast energivare	Ekstralast virkningsgrad	Tappevann energivare
apartment_block	original_condition	cooling	PRE_TEK49	2020	DH	0.20675904	DH	0.99	Ingen	1	Ingen	1	DH
apartment_block	original_condition	cooling	PRE_TEK49	2020	DH - Bio	0.003394661	DH	0.99	Bio	0.65	Ingen	1	DH
apartment_block	original_condition	cooling	PRE_TEK49	2020	Electric boiler	0.056017026	Electricity	0.98	Ingen	1	Ingen	1	Electricity

7. Holiday homes energy consumption

For the energy-use step the output argument is treated as a directory. Multiple report files (area.xlsx, energy_use.xlsx, etc.) will be written there. If the directory does not exist it will be created automatically.

# The default command writes several report files to the output directory
ebm energy-use output

Output from using the command above
building_category	energy_source	U	2020	2021	2022
Bolig	Elektrisitet	GWh	42133	42039	41926
Bolig	Fjernvarme	GWh	2727	2732	2736
Bolig	Bio	GWh	6138	6123	6094

8. Example case

If the user wants to run the program with input files located in another directory, for instance the “calibration” directory, the user can use the following command:

# This command will run the program with input files located in the "calibration" directory
ebm --input calibration energy-use output

Last Updated on 2026-10-22.

Version: 1.2.0.