Skip to main content

Introduction

EBM is a model used by the Norwegian Water Resources and Energy Directorates (NVE) to forecast energy use in the building stock. EBM is an open-source model developed and managed by NVE. The model allows the user to analyze how demographic trends and policy instruments impact the yearly energy use on a national and regional level. Energy use is estimated by a bottom- up approach, based on the building stock floor area, energy need and distribution of heating systems. The mathematical model is implemented in Python, with input and output files in Excel or CSV.

Getting Started

More information

Setting up virtual environment

It is recommended that you use ebm in a python virtual environment (venv).

For detailed instructions, see How to create and activate a virtual environment

1. Installation process

You can install the package in two main ways, depending on your needs:

Option 1: Install from PyPI (recommended for most users)

This is the simplest and most stable way to get the latest released version:

python -m pip install ebm

Option 2: Install from source (for development or contributions)

If you plan to modify the code or contribute to the project, clone the repository and install it in editable mode:

git clone https://github.com/NVE/ebm

cd ebm

Make sure your current working directory is the EBM root.

python -m pip install -e .

The command will install install all dependencies and ebm as an editable module.

2. Software dependencies

  • pandas
  • loguru
  • openpyxl
  • pandera

Dependecies will be automatically installed when you install the package as described under Installation process. See also requirements.txt

3. Create an input directory

Before running the model you need to create a directory with the necessary input files:

python -m ebm --create-input

4. Run the model

There are multiple ways to run the program. Listed bellow is running as a standalone program and running as a module. If running as a program fails due to security restriction, you might be able to use the module approach instead.

See also Running as code

Running as a module

python -m ebm

By default, the results will be written to the subdirectory output

For more information use --help

python -m ebm --help

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

Calculate EBM energy use 1.2.15

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

                        The calculation step you want to run. The steps are sequential. Any prerequisite to the chosen step will run
                            automatically.
  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.

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)
  --categories [CATEGORIES ...], --building-categories [CATEGORIES ...], -c [CATEGORIES ...]

                        One or more of the following building categories:
                            house, apartment_block, kindergarten, school, university, office, retail, hotel, hospital, nursing_home, culture, sports, storage_repairs.
                            The default is to use all categories.
  --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: calibrated, original, tiks26, tiks26v1.0.9.
                        Default: calibrated.
                        Use `list-input` to list available datasets.
  --horizontal-years, --horizontal, --horisontal
                        Show years horizontal (left to right)

Running as code

from ebm.temp_calc import calculate_energy_use_wide
from ebm.model.file_handler import FileHandler

fh = FileHandler()
fh.create_missing_input_files()

df = calculate_energy_use_wide(ebm_input=fh.input_directory)
print(df)

License

This project is licensed under the MIT License. You are free to use, modify, and distribute the software with proper attribution.

Contributing

We welcome contributions! Please refer to the Contributing Guide for details on how to get started.

Documentation

Full documentation is available at the EBM User Guide: https://nve.github.io/ebm-docs/

Metadata

Release files for ebm 1.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ebm 1.1.1
File Size Uploaded Provenance Actions
ebm-1.1.1.tar.gz 1.2 MB Without provenance Details for ebm-1.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ebm 1.1.1
File Interpreter ABI Platform Actions
ebm-1.1.1-py3-none-any.whl Python 3 none any Details for ebm-1.1.1-py3-none-any.whl

Total release size: 2.5 MB

Release files / ebm-1.1.1.tar.gz

Download URL ebm-1.1.1.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
4ed6cf03e6159b6441f03986e1d3b88c2780ed2d82f887fbe8a14910bff362c5
BLAKE2b-256 checksum
How to use checksums
136844baf22e73ac369eed350dea386715ffdc1e621dd491b127557753da2d13
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Release files / ebm-1.1.1-py3-none-any.whl

Download URL ebm-1.1.1-py3-none-any.whl
Size 1.2 MB
Tags Python 3
SHA-256 checksum
How to use checksums
515f85dfc01574806e6d193c6b4d35c887f05e8aef1925f247937194e158ae0d
BLAKE2b-256 checksum
How to use checksums
6e3b13e827431e712616529e9b8f656da4bf2cf663f720e4768efffe19b32e88
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.16

Security for ebm 1.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page