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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.