Inside a HEM Input File

The Home Energy Model takes a single JSON file that describes everything about a building — its walls, windows, heating system, weather, and how it is occupied. We ran the actual open-source HEM engine and looked inside a real input file. Here is what is in it, what each section means, and how it compares to what SAP asks for.

What HEM needs to know

A HEM input file is divided into around 15 top-level sections, each describing a different aspect of the building and how it is used. Here is the full list from a real input file:

Under SAP, most of this is compressed into a single fixed-format worksheet. HEM separates each concern into its own section, allowing far more detailed modelling — and, critically, allowing the half-hourly simulation to capture how these elements interact over time.

Building fabric: how HEM sees your walls

The Zone section is where the physical building lives. Each zone (typically one per main living area) contains a set of BuildingElement entries — one for each wall, roof section, floor, and window. Here is a real wall definition from the open-source demo file:

{
  "type": "BuildingElementOpaque",
  "area": 20.0,
  "pitch": 90.0,
  "orientation360": 90.0,
  "thermal_resistance_construction": 0.7,
  "areal_heat_capacity": 19000.0,
  "solar_absorption_coeff": 0.6,
  "mass_distribution_class": "IE",
  "height": 2.5,
  "width": 10.0
}

Notice what HEM asks for that SAP does not:

• Orientation (orientation360) — a south-facing wall and a north-facing wall behave very differently under half-hourly solar modelling. SAP cannot distinguish between them.
• Thermal mass (areal_heat_capacity and mass_distribution_class) — how much heat the wall stores and releases over time, essential for dynamic thermal modelling.
• Solar absorption (solar_absorption_coeff) — dark walls absorb more solar radiation than light ones, affecting heat gain through the fabric.
• Thermal resistance (thermal_resistance_construction) — rather than a U-value, HEM takes the construction's R-value directly. The engine calculates the overall U-value internally, accounting for surface resistances.

Windows carry even more detail. Here is a real window definition:

{
  "type": "BuildingElementTransparent",
  "height": 1.25,
  "width": 4.0,
  "orientation360": 90.0,
  "thermal_resistance_construction": 0.4,
  "g_value": 0.75,
  "frame_area_fraction": 0.25,
  "mid_height": 1.5
}

The g_value (solar transmittance) determines how much solar energy passes through the glazing. Combined with the window's orientation and the half-hourly solar radiation data, HEM models solar gains far more accurately than SAP's monthly averages. Windows can also have shading definitions — overhangs and side fins — that reduce solar gain at specific sun angles.

Heating and hot water

The SpaceHeatSystem section defines how the building is heated. Here is a simple electric heater from the demo file:

{
  "type": "InstantElecHeater",
  "EnergySupply": "mains elec",
  "Control": "HeatingPattern_main 1",
  "frac_convective": 0.4,
  "rated_power": 6.0
}

An electric heater is straightforward — a power rating and an efficiency of 1.0. But compare this to how HEM defines a heat pump:

{
  "type": "HeatPump",
  "source_type": "OutsideAir",
  "sink_type": "Water",
  "modulating_control": true,
  "min_modulation_rate_35": 0.35,
  "temp_return_feed_max": 70.0,
  "temp_lower_operating_limit": -5.0,
  "design_flow_temp": 55
}

The heat pump definition includes modulation rates, operating temperature limits, and flow temperature design parameters. Behind this sits a full set of COP (coefficient of performance) test data at different source and sink temperatures, following BS EN 14825. HEM uses this data to calculate how efficiently the heat pump operates at each half-hourly timestep, based on the actual outdoor temperature at that moment.

This is fundamentally different from SAP, which uses a single seasonal efficiency value from the Product Characteristics Database (PCDB). A heat pump that performs brilliantly at 7°C but poorly at -3°C will show that in HEM's results. SAP averages it away.

Weather and time

The SimulationTime section is the simplest in the file:

{
  "start": 0.0,
  "end": 8760.0,
  "step": 0.5
}

This says: simulate from hour 0 to hour 8,760 (a full year) in half-hourly steps — that is 17,520 individual calculation timesteps. For each one, the engine reads the corresponding weather data from the ExternalConditions section: 8,760 hourly values for air temperature, direct and diffuse solar radiation, wind speed, and wind direction.

Weather data comes from CIBSE Test Reference Years, which represent typical conditions for 14 UK climate regions. The engine accepts standard EnergyPlus .epw weather files, making it compatible with the same weather data used in commercial dynamic simulation tools.

Measured vs assumed: the wrapper's role

This is the most important distinction in HEM's input file. The data falls into two categories:

• Things you measure about the building — fabric U-values, system types, geometry, air permeability. These come from the assessor's survey or the architect's design.
• Standardised assumptions about how it is used — occupancy patterns, heating schedules, appliance usage, hot water demand. For compliance and EPC assessments, these come from the wrapper, not from measurements.

HEM's core engine is completely flexible — it accepts any occupancy pattern, any heating schedule, any shower timing. But for regulatory assessments, you cannot measure how often someone actually showers. So the FHS wrapper and the future EPC wrapper define standardised assumptions: fixed occupancy based on floor area and bedroom count, standardised hot water demand, standard heating patterns, and standard appliance profiles.

Here is what a standardised shower event looks like in the input file:

{
  "duration": 5.9,
  "start": 7.6,
  "temperature": 41.0
}

That is an individual shower: 5.9 minutes long, starting at hour 7.6 (around 7:36 am), at 41°C. A full-year input file contains hundreds of these events, generated to represent typical UK household water usage patterns. The assessor does not create these — the wrapper generates them automatically from the dwelling's floor area and number of bedrooms.

SAP also uses standardised occupancy, but at monthly resolution. HEM's standardised schedules are half-hourly — the 7am shower, the 6pm cooking, the overnight heating setback are all modelled as individual events. This granularity is what allows HEM to accurately model technologies like solar PV self-consumption, battery storage, and smart heating controls that respond to time-of-use electricity tariffs.

What comes out

The engine produces three output files: a half-hourly CSV with energy flows and temperatures at every timestep, a fabric performance summary (heat transfer coefficient, heat loss parameter), and an annual energy summary broken down by end use and fuel type. A full-year run produces over 17,500 rows of timestep data.

For more on how HEM processes this input to produce results, see How HEM Calculates Energy Performance.

Frequently Asked Questions

Related Pages