A sector-spanning bottom-up model for long-term energy demand modelling.
- What is endemo
- How to Install
- Model Structure and Logic
- How to Create Your Own Model
- License, Dataset and Copyright
- Citations
endemo is a bottom-up energy demand framework for long-term energy demand estimation and exploration.
It is used to estimate future energy demand for a defined geographical area in different sectors such as:
- industry
- households
- traffic
- commerce, trade and services
The model can generate:
- Useful Energy
- Final Energy
- Regional and subregional results
- Annual and temporally resolved results (hourly time series)
This allows the user to analyse not only total future demand, but also its sectoral, spatial, and temporal structure. Depending on the selected configuration, the model can represent different technologies, energy carriers, useful energy types, and temperature levels. It can therefore be used both for high-level scenario comparisons and for more detailed analyses of sectoral demand development, subregional distributions, and hourly load patterns.
If you intend to further develop the software, please install the git version control system first. In Linux distributions, git can be installed via the package manager. For Windows, go to http://git-scm.com/. Remark: At step "Adjusting your PATH environment", select "Run Git from the Windows Command Prompt".
Then, in a directory of your choice, clone this repository by:
git clone https://github.com/tum-ens/endemo.git
A better way to clone repositories is to use a password-protected SSH key. See the Github documentation on how to add an SSH key to your account.
Continue at “Installation of endemo” below.
If you do not intend to further develop the software, pick the latest release and download the zip file.
We recommend using the Python distribution Anaconda or Mamba. If you don't want to use it or already have an existing Python (version 3.10 recommended) installation, you can also download the required packages by yourself.
- Anaconda (Python 3)/Mamba Choose the 64-bit installer if possible.
During the installation procedure, keep both checkboxes "modify PATH" and "register Python" selected! If only higher Python versions are available, you can switch to a specific Python Version by typing
conda install python=<version> - Packages
- Download the environment file endemo-env.yml.
- Launch a new command prompt (Windows: Win+R, type "cmd", Enter / Linux: CTRL+Alt+T)
- Install it via conda or mamba by
conda env create -f endemo-env.yml. - Each time you open a new terminal for running endemo, you can activate the environment by
conda activate endemo. - At first run, you may have to init conda or mamba by running
conda init
Continue at Get Started.
For all packages, best take the latest release or release candidate version. Both 32 bit and 64 bit versions work, though 64 bit is recommended. The list of packages can be found in the environment file endemo-env.yml.
After installation, got to the directory you downloaded or cloned endemo into and execute the script main.py by using the following on the command prompt (Windows) or Terminal (Linux) :
python main.py.
The results will be stored in the folder results.
The model follows the chain:
Demand Drivers -> ECU / DDet -> Useful Energy -> Final Energy
DDr (Demand Drivers)
Upstream explanatory variables such as population, GDP, employment, or time.
ECU (Energy Consuming Units)
Depending on the sector, an acting energy consumer or an energy consuming product.
DDet (Demand Determinants)
Factors which directly contribute to the level and structure of the energy consumption of an ECU.
UE (Useful Energy)
Calculated from ECU and DDet.
FE (Final Energy)
Derived from Useful Energy using efficiencies and energy carrier shares.
The model is based on four central Excel input files:
- Model_Settings.xlsx
- Data_yearly_Hist.xlsx
- Data_yearly_Scenario_.xlsx
- Data_hourly.xlsx
Model_Settings.xlsx defines the active model structure, including:
- active regions
- subregions (optional)
- active sectors and subsectors
- ECU and DDet variables per subsector
- subregional distribution variables per subsector (optional)
- Technologies per subsector (optional)
- useful energy types
- heat levels
- final energy types
- selected scenario
- enabled outputs such as FE, subregions, and timeseries
Only variables and structural paths referenced in the settings are processed.
The yearly input data are split into two files:
- Data_yearly_Hist.xlsx
- Data_yearly_Scenario_.xlsx
Data_yearly_Hist.xlsx contains the historical input values used as the observed data basis of the model. These include historical time series for sectoral variables, demand drivers, and subregional distribution variables.
Data_yearly_Scenario_.xlsx contains the scenario-specific input values and forecast definitions. This file defines how variables are extended into the future, for example through direct yearly values, historical forecasts, user-defined forecasts, interpolation points, or custom equations.
Each row describes one variable in one specific model context.
- Subsector: Defines the more specific subdivision of a sector, for example a particular industrial branch or application group within a main sector.
- Technology: Specifies the technology option or process to which a variable applies, for example a specific heating technology.
- Variable: Defines the actual model variable represented by the row, for example an activity level, a specific demand value, or a share.
- UE_Type: Specifies the useful energy type of the variable, for example electricity, heat, or mobility-related useful energy.
- FE_Type: Specifies the final energy carrier associated with the variable, for example electricity, hydrogen, or fuel.
- Temp_level (heat levels): Defines the temperature level of a heat-related variable and is used to distinguish between different heat demand classes.
- Forecast data (user or historical): Defines whether the future values are based on historical calibration or directly specified by the user in the scenario file.
- Function: Specifies the forecast method used to calculate future values, for example linear functions, interpolation, or custom equations.
- Equation: Contains the mathematical expression used for user-defined forecast functions.
- Factor: Applies a scaling factor to the calculated forecast values after the forecast itself has been computed.
- Lower limit: Defines the minimum allowed value for the forecasted variable before scaling is applied.
- Upper limit: Defines the maximum allowed value for the forecasted variable before scaling is applied.
- k0, k1, …: Define the coefficients of the selected forecast function, for example intercepts or slope parameters in linear or user-defined equations.
Data_hourly.xlsx contains load profiles used to distribute yearly results into hourly time series.
Profiles are matched by metadata such as:
- region
- sector
- subsector
- technology
- UE_Type
- Temp_level
Forecasts are defined row-wise and use a shared infrastructure for:
- ECU
- DDet
- dependent demand drivers
- subregional distribution variables
Two forecast modes are supported:
Historical
Function and dependencies come from the scenario file. Coefficients are estimated from historical data.
User
Coefficients, yearly values, interpolation points, or custom equations are taken directly from the scenario file.
The model uses an exact-first, default-as-fallback principle.
Default rows are only used if no sufficiently specific row exists.
For yearly variables, matching is resolved from the variable level to the more detailed hierarchy, for example:
Variable -> Sector -> Subsector -> Technology -> further metadata -> Region
Historical and scenario data are merged into one combined variable description before forecasting starts.
Depending on the configuration, the model generates:
- sector forecast files such as predictions_.xlsx
- yearly useful energy files such as UE_.xlsx
- yearly final energy files such as FE_.xlsx
- demand driver outputs
- subregional outputs
- hourly timeseries outputs
- validation files
- optional trace information
To create your own model, proceed in five steps.
In Model_Settings.xlsx, add/activate:
-
regions you want to model
-
sectors and subsectors you want to include
-
define ECU and DDet variables used in each subsector
-
useful energy and final energy types
-
optional: subregional and timeseries outputs ** define subregions of the activated regions you want to model ** define demand distribution variables used in each subsector (optional)
The settings define the active model hierarchy. Only regions, sectors, subsectors, and variable paths referenced here are processed later in the model run.
If a new sector is added, a corresponding sheet for its subsectors must also be defined in the settings structure.
If subregional resolution is enabled, subregions must be defined for each active region. Missing or inconsistent subregional definitions can stop the model run.
In Data_yearly_Scenario_.xlsx, define how each variable should behave in the future. This is the central modelling step, because the scenario file specifies the transition from historical input data to future model values.
The scenario file determines for each variable defined in the Model_Settings.xlsx how it is projected for the future. In scenario file it is defined whether a variable is estimated based on historical data or user inputs. Furthermore, which Demand Drivers (DDr), if any, are used for the estimation. Next, which function is applied - exogenous determination from historical data, values interpolated between the user data (one DDr necessary, usualy TIME), or calculated from user given coefficints. Demand drivers can also be dependent and calulated based on other demand drivers. In this way, the scenario file contains the forecast logic of the model and controls the future development of ECU, DDet, demand drivers, and subregional distribution variables.
Typical options are:
- interpolation between yearly values (or full list of values per year)
- historical forecast
- user-defined forecast with pre-given equations
- user-defined forecast with custom equation
The selected function then determines the mathematical form of the forecast, for example a simple continuation, a coefficient-based function, an interpolation, or a user-defined equation.
In Data_yearly_Hist.xlsx, add the historical rows for:
- sectoral ECU and DDet variables
- demand drivers
- subregional distribution variables
Historical data is only required if variables should be calculated on the basis of observed past values.
A row is only processed correctly if both the variable name and the full metadata context match the settings and the historical data.
If hourly timeseries are enabled, add matching load profiles to Data_hourly.xlsx.
The profiles define how yearly values are distributed over time. To be applied correctly, their metadata must match the corresponding model context, for example by region, sector, subsector, technology, UE_Type, and Temp_level.
Run:
python main.py
Then check the generated outputs in the output folder.
Important notes
A variable row alone is not sufficient. The variable must also be referenced in the correct settings path.
Historical forecasts require overlapping numeric years for the target variable and all required demand drivers.
Missing or inconsistent subregional definitions can stop the run.
Timeseries together with subregional resolution can significantly increase runtime.
Please see the LICENSE file of this repository for the software license.
The model historical input data used in the ENDEMO context are provided separately via the corresponding Zenodo dataset.
https://zenodo.org/records/17805753
Software
Kerekes, A., Breuning, L., Epishev, A., Kobalt, C. and Haag, M. endemo, GitHub repository.
Methodological reference
Kerekes, A., Breuning, L., Kuhn, P., and Hamacher, T. endemo – an Open-Source Energy Demand Modelling Framework in European Context.