Working with Input Files

What is a HEM Input File?

HEM input files are JSON files which contains all the data (except, in some cases, the weather data) which a HEM calculation requires.

This typically includes:

  • Information about the building geometry and location.

  • Information about the constructions used in the walls, roof, floors and windows.

  • Information about the heating and cooling systems.

  • Information about many other things which impact on the energy consumption of the building.

What is a JSON file?

A JSON file is a standard file format used extensively in computer science.

It is a text file in the same way as a CSV file. But where CSV files are good at storing tabular data, JSON files are good at storing nested data.

JSON files are constructed according to: https://www.json.org/json-en.html

Why use JSON files?

The nested data property of JSON files is useful for building energy models.

This is because buildings are often made up of a variable number of objects. For example:

  • A building can have a variable number of rooms.

  • Each room can have a variable number of lights.

This variable-length, nested information is difficult to store in a tabular data structure like CSV files, but works well in JSON using the object (dictionaries) and array (lists) JSON components.

What are the rules when creating a HEM Input File?

The contents of the HEM input files are structured according to a schema.

There are three schemas currently available for HEM:

These schemas are also written in JSON and follow the JSON Schema standard.

How do I use these schemas?

The schemas themselves are long text documents which are difficult to use directly.

Instead I have converted these JSON Schema documents into an online reference which contains the same content and is easier to navigate.

I can then use these online references to either manually create an input JSON file in a text editor or to write a Python script to create an input JSON file.