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.2.0

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.2.0
File Size Uploaded Provenance Actions
ebm-1.2.0.tar.gz 1.2 MB Without provenance Details for ebm-1.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 2.5 MB

Release files / ebm-1.2.0.tar.gz

Download URL ebm-1.2.0.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
6dad5220a175ef10911f55858d0ac756bc463fecc543e2080e616d019fc63251
BLAKE2b-256 checksum
How to use checksums
ae3ae9168cda40362aa7a2925891d8952ecc4e8e13556b66c690385840a4532f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

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

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

Security for ebm 1.2.0

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