Steven Firth

How to run the Home Energy Model

Steven Firth -

This article looks at how to run an energy calculation using the latest available version of the Home Energy Model.

What is the Home Energy Model?

The Home Energy Model (HEM) is a new energy calculation tool currently being developed by the UK Government. It is planned that the HEM will replace the Standard Assessment Procedure (SAP) in the coming years and will be used for building regulations and EPC calculations.

The HEM is currently under development and as part of a recent Government consultation the draft code of the model has been made available (see here). The documentation states that: "Please note that HEM is currently in development and should not be used for any official purpose". The HEM code is made available under the MIT license.

How did I run the Home Energy Model?

For this article, I did the following:

  • I downloaded the online repository containing the draft code of the HEM. The link is here and I used the 'Download as Zip' option available in the 'More actions' button. The code was downloaded on 19th Nov 2024.
  • I extracted the repository from the downloaded zip file to a local folder on my computer.
  • I downloaded an EnergyPlus weather file for London (from here) and placed this file in the same folder as the HEM code repository.
  • I ran an energy calculation using one of the sample input files. This was the "demo.json" file in the "test/demo_files/core" folder.
    • When I tried this without using the EnergyPlus weather file, it failed.
    • When I tried this with the EnergyPlus weather file, the calculation ran and three new results files were created.
  • I viewed the three results file created by the energy calculation.

This work only looks at the "core" Home Energy Model which is the main building physics engine.

Setting up the Home Energy Model

The HEM documentation includes instructions for running calculations (see here).

The HEM code is written in Python so we will need Python installed in order to run the code. I have Python installed via the Anaconda distibution.

The HEM is run by using the command line. For Windows this is the Command Prompt program. I used the Anaconda Prompt from the Anaconda distribution as I prefer to use the version of Python provided by Anaconda.

You can check if you have Python installed by opening the Command Prompt and running the command: 

python

(If Python is working, this will enter the Python interpreter... use quit() to exit this).

Next, we need to change the current working directory of the Command Prompt to the location of the HEM repository. This is done using the Change Directory cd command:

cd [change this text to the path of the local folder where the HEM repository is stored]

Lastly, if you try to run the code and receive some "import" errors then it is likely that you are missing some of the additional, external Python packages that the HEM code requires. These are described in the section on "Installing dependencies" in the HEM documentation.

The input data file

The input file used for these calculations can be viewed here. This is the "demo.json" file located in the "test/demo_files/core" folder.

A screenshot of the start of the "demo.json" input file for the Home Energy Model.

This is a JSON file. JSON files are text files that are structured according a well-established standard and are used extensively to transfer data, for example across the internet. All major computer languages will have standard libraries for parsing (i.e. reading) JSON files and can easily extract the data from these files.

There doesn't seem to be any documentation of how these input files are structured. However from visual inspection it seems that the input file contains the following:

  • Instructions for the calculation itself (start and stop points etc.)
  • Weather and location data (including time series data of weather variables)
  • Building information (such as the wall areas and constructions, thermal bridging)
  • Occupancy data (including time series data for people, lights and appliances)
  • Space and water heating systems information (rated power, efficiency etc.)
  • Control schedules (for the heating thermostat and the hot water use)

This is similar to the numerical, building physics inputs that are used in EnergyPlus input files.

Running a HEM calculation without an EnergyPlus weather file.

I first ran a calculation using the weather data already inside the input file (i.e. not using the EnergyPlus weather file). Following the instructions, the command is:

python src\hem.py test\demo_files\core\demo.json

This means:

  • python: Run a Python module
  • src\hem.py: Run the 'hem.py' module located in the 'src' folder
  • test\demo_files\core\demo.json: Use this file as the input file

This failed, with the following error reported in the Command Prompt:

File "...\src\core\external_conditions.py", line 1943, in create_external_conditions
    external_conditions_dict['wind_directions'],
KeyError: 'wind_directions'

From looking into the code itself, I could see that the model is expecting the "ExternalConditions" input to contain information on the wind direction. This is missing in the demo.json input file so, correctly, the code raises an error at this point.

I don't think this is anything to be too concerned about as these kind of minor errors are a part of developing software, and I'm sure this is easily fixed.

Running a HEM calculation with an EnergyPlus weather file.

Next, I ran a calculation with an EnergyPlus weather file using this command line:

python src\hem.py test\demo_files\core\demo.json --epw-file GBR_London.Gatwick.037760_IWEC.epw

This means:

  • python: Run a Python module
  • src\hem.py: Run the 'hem.py' module located in the 'src' folder
  • test\demo_files\core\demo.json: Use this file as the input file
  • --epw-file: Use the following filepath for an EnergyPlus weather file
  • GBR_London.Gatwick.037760_IWEC.epw: Use this EnergyPlus weather file

This succeded, with the following response printed in the Command Prompt:

Running 1 cases in series

The results files are placed in a "*__results" folder which is created in the folder where the input file is located. This calculation produced three results files:

  • demo__core__results.csv: This can be viewed here and contains half-hourly results for the main temperature and energy flow calcuations. In this case, only 8 rows (4 hours) of data are calculated. This is similar to the CSV files produced by EnergyPlus calculations.
Timestep,DHW: demand volume (including distribution pipework losses),DHW: demand energy (including distribution pipework losses),DHW: demand energy (excluding distribution pipework losses),DHW: total event duration,DHW: number of events,DHW: distribution pipework losses,DHW: primary pipework losses,DHW: storage losses,Ventilation: Ductwork gains,zone 1: internal gains,zone 1: solar gains,zone 1: operative temp,zone 1: internal air temp,zone 1: space heat demand,zone 1: space cool demand,main: energy output,None: energy output,_unmet_demand: total,_unmet_demand: zone 1,_unmet_demand: hw cylinder,_unmet_demand: import,_unmet_demand: export,_unmet_demand: generated and consumed,_unmet_demand: beta factor,_unmet_demand: generation to storage,_unmet_demand: from storage,_unmet_demand: grid to storage,_unmet_demand: battery charge level,_unmet_demand: diverted,mains elec: total,mains elec: IES,mains elec: cooking,mains elec: lighting,mains elec: immersion,mains elec: main,mains elec: import,mains elec: export,mains elec: generated and consumed,mains elec: beta factor,mains elec: generation to storage,mains elec: from storage,mains elec: grid to storage,mains elec: battery charge level,mains elec: diverted
[count],[litres],[kWh],[kWh],[mins],[count],[kWh],[kWh],[kWh],[kWh],[W],[W],[deg C],[deg C],[kWh],[kWh],[kWh],[kWh],[kWh],[kWh],[kWh],[kWh],[kWh],[kWh],[ratio],[kWh],[kWh],[kWh],[ratio],[kWh],[kWh],[kWh],[kWh],[kWh],[kWh],[kWh],[kWh],[kWh],[kWh],[ratio],[kWh],[kWh],[kWh],[ratio],[kWh]
0,0,0,0,0,0,0,0,0.070508,0,712.881111,0,21.0,21.830857,2.461064,0,2.461064,0,0,0,0,0,0,0,1.0,0,0,0,0,0,2.793064,0,0.3,0.032,0,2.461064,2.793064,0,0,1.0,0,0,0,0,0
1,0,0,0,0,0,0,0,0.069137,0,762.852867,0,21.0,21.833794,2.682572,0,2.682572,0,0,0,0,0,0,0,1.0,0,0,0,0,0,2.848572,0,0.12,0.046,0,2.682572,2.848572,0,0,1.0,0,0,0,0,0
2,0,0,0,0,0,0,0,0.067793,0,1055.344617,0,21.0,21.875856,2.492624,0,2.492624,0,0,0,0,0,0,0,1.0,0,0,0,0,0,2.745624,0,0.22,0.033,0,2.492624,2.745624,0,0,1.0,0,0,0,0,0
3,0,0,0,0,0,0,0,0.066475,0,1602.355972,0,21.0,21.894148,2.098029,0,2.098029,0,0,0,0,0,0,0,1.0,0,0,0,0,0,2.869029,0,0.75,0.021,0,2.098029,2.869029,0,0,1.0,0,0,0,0,0
4,0,0,0,0,0,0,0,0.065182,0,2400.652692,0,21.0,21.888294,1.425396,0,1.425396,0,0,0,0,0,0,0,1.0,0,0,0,0,0,3.227396,0.9,0.89,0.012,0,1.425396,3.227396,0,0,1.0,0,0,0,0,0
5,0,0,0,0,0,0,0,0.063915,0,1198.435978,0,21.0,21.904842,2.649561,0,2.649561,0,0,0,0,0,0,0,1.0,0,0,0,0,0,2.816561,0,0.15,0.017,0,2.649561,2.816561,0,0,1.0,0,0,0,0,0
6,54.741735,2.76756,2.502846,9.125,1.0,0.238627,0,0.015474,0,2880.035112,0,21.0,21.886383,0.613253,0,0.613253,0,0,0,0,0,0,0,1.0,0,0,0,0,0,2.088253,0.9,0.55,0.025,0,0.613253,2.088253,0,0,1.0,0,0,0,0,0
7,48.196917,2.403066,1.88094,7.0,2.0,0.004343,0,0,0,1657.585823,0,21.0,21.885477,1.844562,0,1.844562,0,1.009949,0,1.009949,1.009949,0,0,1.0,0,0,0,0,0,2.170562,0,0.28,0.046,0,1.844562,2.170562,0,0,1.0,0,0,0,0,0
  • demo__core__results_static.csv: This can be viewed here and contains the results of calculations done at a pre-calculation stage, before the half-hourly calculations start. 
Heat transfer coefficient,W / K,171.651229
Heat loss parameter,W / m2.K,2.14564
Heat capacity parameter,kJ / m2.K,52.8875
Heat loss form factor,,2.5625
Assumptions used for HTC/HLP calculation:
Internal air temperature,Celsius,20.0
External air temperature,Celsius,-2.708333
  • demo__core__results_summary.csv: This can be viewed here and contains total values and other statistics of the half-hourly results. This is similar to the "table" outputs produced by EnergyPlus.
Energy Demand Summary
,,Total
Space heat demand,kWh/m2,0.203338
Space cool demand,kWh/m2,0

Energy Supply Summary
,kWh,timestep,month,day,hour of day
Peak half-hour consumption (electricity),3.227396,4,JAN,1,5.0

,Total,_unmet_demand,mains elec
Consumption,kWh,1.009949,21.559062
Generation,kWh,0,0
Generation to consumption (immediate excl. diverter),kWh,0,0
Generation to storage,kWh,0,0
Generation to diverter,kWh,0,0
Generation to grid (export),kWh,0,0
Storage to consumption,kWh,0,0
Grid to storage,kWh,0,0
Grid to consumption (import),kWh,1.009949,21.559062
Net import,kWh,1.009949,21.559062
Storage round-trip efficiency,ratio,DIV/0,DIV/0

Delivered Energy Summary
Delivered energy by end-use (below) and fuel (right) [kWh/m2],total,mains elec
total,0.269488,0.269488
IES,0.0225,0.0225
cooking,0.04075,0.04075
lighting,0.0029,0.0029
immersion,0,0
main,0.203338,0.203338

Hot water system,Overall CoP,Daily HW demand ([kWh] 75th percentile),HW cylinder volume (litres)
hw cylinder,DIV/0,5.170626,80.0

Space heating system,Overall CoP
main,1.0

Summary

  • This post demonstrates the method to download and run the latest draft version of the Home Energy Model.
  • The core Home Energy Model seems to work in a similar way to EnergyPlus. It uses numerical, building physics data as inputs and calculates half-hourly temperature and energy results.
  • It would be useful to have more documentation for the Home Energy Model, in particular for the JSON input file.