Home Energy Model Interface Specifcation: Illustrative Prototype

Modelling
, ,
1

Hello All

The UK Government’s Home Energy Model (HEM) will replace the existing Standard Assessment Procedure (SAP) that is used for various purposes including generating Energy Performance Certificates (EPCs).

At Friends of the Earth (England, Wales and Northern Ireland) we are exploring how the Home Energy Model might enable development of an open source tool or tools to help inform our supporters and others on insulation and heating options. A key challenge that anyone wanting to use the Home Energy Model faces is to set up the main input file. This file enables a user to set the various options and parameter values defining the characteristics of the building(s) being modelled. What is needed is a document that describes how to set up the file. In effect, a “driver’s manual” for the Home Energy Model. (In more technical language, an input interface specification).

We have produced (included with this posting) an Illustrative Prototype for such a document. We would like it to be an initial contribution towards the development of a full open content interface specification. The Illustrative Prototype itself is an open content document, distributed under a Creative Commons License.

We would would very much welcome any comments you may have on the Illustrative Prototype. They will help us to improve the document.

Illustrative_Prototype-HEM_Building_Specification_Input_Documentation-V1.0.pdf (675.0 KB)

1 Like
2

@Chris.Gordon-Smith I flipped through much of the PDF. Without having acted on the content, the document seems precise and clear and comprehensive.

I would however suggest a “TL:DR” before section 1.1 and written in a more casual style. Perhaps:

TL:DR

This PDF provides a first‑cut at the kind of “operators manual” that would help users get a Home Energy Model (HEM) model instance up and running for their particular circumstances. This PDF covers things like how to use and assign the various options and parameters needed for a specific HEM model to execute. And how to structure the required input data using JSON markup.

The idea is for this PDF to grow into a full manual — one that provides guidance and detail and is also responsive to feedback from users.

Later, when the project migrates to GitLab [or whatever], you should be able to file issues on the content of this PDF.

As you can imagine from the above, it took me some time to get my bearings. And a TL:DR might help with that task.

A graphical key for the diagrams would help (and noting §4.4). For instance, what are those :small_orange_diamond: symbols supposed to represent? :upside_down_face:

Is this workflow suitable for a Jupyter notebook (or Marimo or similar)? Does there need to be a section on workflow?

Should the use of YAML, as a superset of JSON, be mentioned in this context (without trying to spark a flame war)?

Passing your text thru DeepL Write could help? And some commas are arguably missing too?

Good luck with this important work. And :heavy_plus_sign: :one: to the United Kingdom government for this truly innovative legislation.

And finally, those working with building stock in this community should definitely take a look at this draft documentation for the HEM framework.

▢

PS: @Chris.Gordon-Smith are you going to present at the next openmod workshop in 2025 (quite possibly in Scandinavia)?

3

Hello @robbie.morrison

Thanks for these helpful comments. It’s good to hear that you found the document precise, clear and comprehensive! I think you’re right that readers could be helped to “get their bearings”. I’ll take that on board for the next version.

TL:DR - Although the document does explain its purpose, I can see there is scope to make the up-front text more accessible. In addition to the points you mention, I have thought that a shorter and snappier title for the document would help.

Graphical key: Agree this is needed. Although the graphical symbols are explained in the text, a graphical key would be much clearer and more accessible.

YAML: Interesting point. I can see that this could make the input data more readable. Eg by using comments and multi-line lists. I’ll put something about this in the next version of the document. The format of the HEM input file is determined by Home Energy Model (HEM) Team, but perhaps it would be possible to produce a readable file in YAML and convert it to JSON using a Jupyter Notebook?

DeepL Write: Looks like a useful tool!

openmod workshop 2025: Interesting prospect! I’ll look into it.

1 Like