OpenStudio-HPXML documentation

Introduction

The OpenStudio-HPXML repository consists of residential OpenStudio measures that handle HPXML files.

Measures

This repository contains two OpenStudio measures:

1. HPXMLtoOpenStudio: A measure that translates an HPXML file to an OpenStudio model.
2. SimulationOutputReport: A reporting measure that generates a variety of annual/timeseries outputs for a residential HPXML-based model.

License

This project is available under a BSD-3-like license, which is a free, open-source, and permissive license. For more information, check out the license file.

Getting Started

Setup

To get started:

1. Download OpenStudio 3.0.0 and install the Command Line Interface/EnergyPlus components, or use the nrel/openstudio docker image.
2. Download the latest release for these OpenStudio measures.

Running

To programatically run simulations, it’s recommended to use the OpenStudio Command Line Interface. Two general approaches (basic and advanced) for running via the CLI are described below. The OpenStudio measures can also be run from user interfaces (e.g., the OpenStudio Application or Parametric Analysis Tool).

Note

If the openstudio command is not found, it’s because the executable is not in your PATH. Either add the executable to your PATH or point directly to the executable found in the openstudio-X.X.X/bin directory.

Basic Run

The simplest and fastest method is to call the OpenStudio CLI with the provided workflow/run_simulation.rb script.

For example: openstudio workflow/run_simulation.rb -x workflow/sample_files/base.xml

This will create a “run” directory with all input/output files. By default it will be found at the same location as the input HPXML file.

Run openstudio workflow/run_simulation.rb -h to see all available commands/arguments.

Advanced Run

If additional flexibility is desired (e.g., specifying individual measure arguments, including additional OpenStudio measures to run alongside this measure in a workflow, etc.), create an OpenStudio Workflow (OSW) file. The OSW is a JSON file that will specify all the OpenStudio measures (and their arguments) to be run sequentially. A template OSW that simply runs the HPXMLtoOpenStudio and SimulationOutputReport measures on the workflow/sample_files/base.xml file can be found at workflow/template.osw.

For example: openstudio run -w workflow/template.osw

This will create a “run” directory with all input/output files. By default it will be found at the same location as the OSW file.

Outputs

In addition to the standard EnergyPlus outputs found in the run directory, a variety of high-level annual outputs are conveniently reported in the resulting run/results_annual.csv file.

Timeseries outputs can also be requested using either the Basic or Advanced approaches. When requested, timeseries outputs will be found in the run/results_timeseries.csv file.

See the SimulationOutputReport Measure section for a description of all available outputs available.

HPXMLtoOpenStudio Measure

The HPXMLtoOpenStudio measure requires a building description in an HPXML file format. HPXML is an open data standard for collecting and transferring home energy data. Using HPXML files reduces the complexity and effort for software developers to leverage the EnergyPlus simulation engine.

Capabilities

The following building features/technologies are available for modeling via the HPXMLtoOpenStudio measure:

• Enclosure
  • Attics (Vented, Unvented, Conditioned)
  • Foundations (Slab, Unconditioned Basement, Conditioned Basement, Vented Crawlspace, Unvented Crawlspace, Ambient)
  • Garages
  • Windows & Overhangs
  • Skylights
  • Doors
• HVAC
  • Heating Systems (Electric Resistance, Central/Wall/Floor Furnaces, Stoves, Boilers, Portable Heaters, Fireplaces)
  • Cooling Systems (Central Air Conditioners, Room Air Conditioners, Evaporative Coolers)
  • Heat Pumps (Air Source, Mini Split, Ground Source, Dual-Fuel)
  • Setpoints
  • Ducts
• Water Heating
  • Water Heaters (Storage, Tankless, Heat Pump, Indirect, Tankless Coil)
  • Solar Hot Water
  • Desuperheater
  • Hot Water Distribution (Standard, Recirculation)
  • Drain Water Heat Recovery
  • Hot Water Fixtures
• Ventilation
  • Mechanical Ventilation (Exhaust, Supply, Balanced, ERV, HRV, CFIS)
  • Kitchen/Bathroom Fans
  • Whole House Fan
• Photovoltaics
• Appliances (Clothes Washer/Dryer, Dishwasher, Refrigerator, Cooking Range/Oven)
• Dehumidifier
• Lighting
• Ceiling Fans
• Plug Loads

EnergyPlus Use Case for HPXML

HPXML is an flexible and extensible format, where nearly all elements in the schema are optional and custom elements can be included. Because of this, an EnergyPlus Use Case for HPXML has been developed that specifies the HPXML elements or enumeration choices required to run the measure.

Software developers should use the EnergyPlus Use Case (found at HPXMLtoOpenStudio/resources/EPvalidator.rb, which defines sets of conditional XPath expressions) as well as the HPXML schema (HPXML.xsd) to construct valid HPXML files for EnergyPlus simulations.

The HPXML Toolbox website also provides several resources for software developers, including:

1. An interactive schema validator
2. A data dictionary
3. An implementation guide

Scope (Dwelling Units)

The OpenStudio-HPXML workflow is intended to be used to model individual residential dwelling units – either a single-family detached (SFD) building, or a single unit of a single-family attached (SFA) or multifamily (MF) building. This approach was taken because:

• It is required/desired for certain projects.
• It improves runtime speed by being able to simulate individual units in parallel (as opposed to simulating the entire building).
• It doesn’t necessarily preclude the possibility of running a single integrated EnergyPlus simulation.

To model units of SFA/MF buildings, current capabilities include:

• Defining surfaces adjacent to generic SFA/MF space types (e.g., “other housing unit” or “other multifamily buffer space”).
• Locating various building components (e.g., ducts, water heaters, appliances) in these spaces.

Note that only the energy use attributed to each dwelling unit is calculated. Other OpenStudio capabilities should be used to supplement this workflow if the energy use of non-residential dwelling spaces (e.g., gyms, elevators, corridors, etc.) are of interest. In the near future, the OpenStudio-HPXML workflow will also begin supporting shared systems (HVAC, water heating, mechanical ventilation, etc.) by approximating the energy use attributed to the unit.

For situations where more complex, integrated modeling is required, it is possible to merge multiple OpenStudio models together into a single model, such that one could merge all residential OSMs together and potentially combine it with a commercial OSM. That capability is outside the scope of this project.

Input Defaults

An increasing number of elements in the HPXML file are being made optional with “smart” defaults. Default values, equations, and logic are described throughout this documentation.

Most defaults can also be seen by using the debug argument/flag when running the workflow on an actual HPXML file. This will create a new HPXML file (in.xml in the run directory) where additional fields are populated for inspection.

For example, suppose a HPXML file has a window defined as follows:

<Window>
  <SystemIdentifier id='Window'/>
  <Area>108.0</Area>
  <Azimuth>0</Azimuth>
  <UFactor>0.33</UFactor>
  <SHGC>0.45</SHGC>
  <AttachedToWall idref='Wall'/>
</Window>

In the in.xml file, the window would have additional elements like so:

<Window>
  <SystemIdentifier id='Window'/>
  <Area>108.0</Area>
  <Azimuth>0</Azimuth>
  <UFactor>0.33</UFactor>
  <SHGC>0.45</SHGC>
  <InteriorShading>
    <SystemIdentifier id='WindowInteriorShading'/>
    <SummerShadingCoefficient>0.7</SummerShadingCoefficient>
    <WinterShadingCoefficient>0.85</WinterShadingCoefficient>
  </InteriorShading>
  <FractionOperable>0.67</FractionOperable>
  <AttachedToWall idref='Wall'/>
</Window>

Warning

The OpenStudio-HPXML workflow generally treats missing HPXML elements differently than elements provided but without additional detail. For example, if an HPXML file has no Refrigerator element defined, it will be interpreted as a building that has no refrigerator and modeled this way. On the other hand, if there is a Refrigerator element defined but no elements within, it is interpreted as a building that has a refrigerator, but no information about the refrigerator is known. In this case, its details (e.g., location, energy use) will be defaulted in the model.

Simulation Controls

EnergyPlus simulation controls can be entered in /HPXML/SoftwareInfo/extension/SimulationControl.

The simulation controls currently offered are timestep, begin month, begin day of month, end month, and end day of month.

Timestep can be optionally provided as Timestep, where the value is in minutes and must be a divisor of 60. If not provided, the default value of 60 is used.

The simulation run period can be optionally specified with BeginMonth/BeginDayOfMonth and/or EndMonth/EndDayOfMonth. The BeginMonth/BeginDayOfMonth provided must occur before EndMonth/EndDayOfMonth provided (e.g., a run period from 10/1 to 3/31 is invalid). If not provided, default values of January 1st and December 31st will be used.

Building Details

The building description is entered in HPXML’s /HPXML/Building/BuildingDetails.

Building Summary

This section describes elements specified in HPXML’s BuildingSummary. It is used for high-level building information including conditioned floor area, number of bedrooms, number of residents, number of conditioned floors, etc. Most occupancy assumptions are based on the number of bedrooms, while the number of residents is solely used to determine heat gains from the occupants themselves. Note that a walkout basement should be included in NumberofConditionedFloorsAboveGrade.

If NumberofBathrooms is not provided, it is calculated using the following equation based on the Building America House Simulation Protocols.

\[NumberofBathrooms = \frac{NumberofBedrooms}{2} + 0.5\]

Shading due to neighboring buildings can be defined inside an Site/extension/Neighbors element. Each Neighbors/NeighborBuilding element is required to have an Azimuth and Distance from the house. A Height is also optionally allowed; if not provided, the neighbor is assumed to be the same height as the house.

The local shelter coefficient can be entered as Site/extension/ShelterCoefficient. The shelter coefficient is defined by the AIM-2 infiltration model to account for nearby buildings, trees and obstructions. If not provided, the value of 0.5 will be assumed.

Shelter Coefficient	Description
1.0	No obstructions or local shielding
0.9	Light local shielding with few obstructions within two building heights
0.7	Local shielding with many large obstructions within two building heights
0.5	Heavily shielded, many large obstructions within one building height
0.3	Complete shielding with large buildings immediately adjacent

The terrain surrounding the building can be entered as Site/SiteType; if not provided, it is assumed to be suburban.

Weather File

The ClimateandRiskZones/WeatherStation element specifies the EnergyPlus weather file (EPW) to be used in the simulation. The weather file can be entered in one of two ways:

1. Using WeatherStation/WMO, which must be one of the acceptable TMY3 WMO station numbers found in the weather/data.csv file. The full set of U.S. TMY3 weather files can be downloaded here.
2. Using WeatherStation/extension/EPWFilePath.

Enclosure

This section describes elements specified in HPXML’s Enclosure.

All surfaces that bound different space types in the building (i.e., not just thermal boundary surfaces) must be specified in the HPXML file. For example, an attached garage would generally be defined by walls adjacent to conditioned space, walls adjacent to outdoors, a slab, and a roof or ceiling. For software tools that do not collect sufficient inputs for every required surface, the software developers will need to make assumptions about these surfaces or collect additional input.

The space types used in the HPXML building description are:

Space Type	Description	Temperature
living space	Above-grade conditioned floor area	EnergyPlus calculation
attic - vented		EnergyPlus calculation
attic - unvented		EnergyPlus calculation
basement - conditioned	Below-grade conditioned floor area	EnergyPlus calculation
basement - unconditioned		EnergyPlus calculation
crawlspace - vented		EnergyPlus calculation
crawlspace - unvented		EnergyPlus calculation
garage		EnergyPlus calculation
other housing unit	Conditioned space of an adjacent housing unit	Same as conditioned space
other heated space	E.g., shared laundry/equipment space	Average of conditioned space and outside; minimum of 68F
other multifamily buffer space	E.g., enclosed unconditioned stairwell	Average of conditioned space and outside; minimum of 50F
other non-freezing space	E.g., parking garage ceiling	Floats with outside; minimum of 40F

Warning

It is the software tool’s responsibility to provide the appropriate building surfaces. While some error-checking is in place, it is not possible to know whether some surfaces are incorrectly missing.

Also note that wall and roof surfaces do not require an azimuth to be specified. Rather, only the windows/skylights themselves require an azimuth. Thus, software tools can choose to use a single wall (or roof) surface to represent multiple wall (or roof) surfaces for the entire building if all their other properties (construction type, interior/exterior adjacency, etc.) are identical.

Air Leakage

Building air leakage is entered using Enclosure/AirInfiltration/AirInfiltrationMeasurement. Air leakage can be provided in one of three ways:

1. nACH (natural air changes per hour): Use BuildingAirLeakage/UnitofMeasure='ACHnatural'
2. ACH50 (air changes per hour at 50Pa): Use BuildingAirLeakage/UnitofMeasure='ACH' and HousePressure='50'
3. CFM50 (cubic feet per minute at 50Pa): Use BuildingAirLeakage/UnitofMeasure='CFM' and HousePressure='50'

In addition, the building’s volume associated with the air leakage measurement can be provided in HPXML’s AirInfiltrationMeasurement/InfiltrationVolume. If not provided, the infiltration volume is assumed to be equal to the conditioned building volume.

Vented Attics/Crawlspaces

The ventilation rate for vented attics (or vented crawlspaces) can be specified using an Attic (or Foundation) element. First, define the AtticType as Attic[Vented='true'] (or FoundationType as Crawlspace[Vented='true']). Then specify the specific leakage area (SLA) using the VentilationRate[UnitofMeasure='SLA']/Value element. For vented attics, the natural air changes per hour (nACH) can instead be specified using UnitofMeasure='ACHnatural'. If the ventilation rate is not provided, default values of SLA=1/300 for vented attics and SLA=1/150 for vented crawlspaces will be used based on ANSI/RESNET/ICC 301-2019.

Roofs

Pitched or flat roof surfaces that are exposed to ambient conditions should be specified as an Enclosure/Roofs/Roof. For a multifamily building where the dwelling unit has another dwelling unit above it, the surface between the two dwelling units should be considered a FrameFloor and not a Roof.

Beyond the specification of typical heat transfer properties (insulation R-value, solar absorptance, emittance, etc.), note that roofs can be defined as having a radiant barrier.

Walls

Any wall that has no contact with the ground and bounds a space type should be specified as an Enclosure/Walls/Wall. Interior walls (for example, walls solely within the conditioned space of the building) are not required.

Walls are primarily defined by their Insulation/AssemblyEffectiveRValue. The choice of WallType has a secondary effect on heat transfer in that it informs the assumption of wall thermal mass.

Rim Joists

Rim joists, the perimeter of floor joists typically found between stories of a building or on top of a foundation wall, are specified as an Enclosure//RimJoists/RimJoist.

The InteriorAdjacentTo element should typically be “living space” for rim joists between stories of a building and “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, or “crawlspace - unvented” for rim joists on top of a foundation wall.

Foundation Walls

Any wall that is in contact with the ground should be specified as an Enclosure/FoundationWalls/FoundationWall. Other walls (e.g., wood framed walls) that are connected to a below-grade space but have no contact with the ground should be specified as Walls and not FoundationWalls.

Exterior foundation walls (i.e., those that fall along the perimeter of the building’s footprint) should use “ground” for ExteriorAdjacentTo and the appropriate space type (e.g., “basement - unconditioned”) for InteriorAdjacentTo.

Interior foundation walls should be specified with two appropriate space types (e.g., “crawlspace - vented” and “garage”, or “basement - unconditioned” and “crawlspace - unvented”) for InteriorAdjacentTo and ExteriorAdjacentTo. Interior foundation walls should never use “ground” for ExteriorAdjacentTo even if the foundation wall has some contact with the ground due to the difference in below-grade depths of the two adjacent space types.

Foundations must include a Height as well as a DepthBelowGrade. For exterior foundation walls, the depth below grade is relative to the ground plane. For interior foundation walls, the depth below grade should not be thought of as relative to the ground plane, but rather as the depth of foundation wall in contact with the ground. For example, an interior foundation wall between an 8 ft conditioned basement and a 3 ft crawlspace has a height of 8 ft and a depth below grade of 5 ft. Alternatively, an interior foundation wall between an 8 ft conditioned basement and an 8 ft unconditioned basement has a height of 8 ft and a depth below grade of 0 ft.

Foundation wall insulation can be described in two ways:

Option 1. Both interior and exterior continuous insulation layers with NominalRValue, extension/DistanceToTopOfInsulation, and extension/DistanceToBottomOfInsulation. Insulation layers are particularly useful for describing foundation wall insulation that doesn’t span the entire height (e.g., 4 ft of insulation for an 8 ft conditioned basement). If there is not insulation on the interior and/or exterior of the foundation wall, the continuous insulation layer must still be provided – with the nominal R-value, etc., set to zero. When insulation is specified with option 1, it is modeled with a concrete wall (whose Thickness is provided) as well as air film resistances as appropriate.

Option 2. An AssemblyEffectiveRValue. The assembly effective R-value should include the concrete wall and an interior air film resistance. The exterior air film resistance (for any above-grade exposure) or any soil thermal resistance should not be included.

Frame Floors

Any horizontal floor/ceiling surface that is not in contact with the ground (Slab) nor adjacent to ambient conditions above (Roof) should be specified as an Enclosure/FrameFloors/FrameFloor. Frame floors in an attached/multifamily building that are adjacent to “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space” must have the extension/OtherSpaceAboveOrBelow property set to signify whether the other space is “above” or “below”.

Frame floors are primarily defined by their Insulation/AssemblyEffectiveRValue.

Slabs

Any space type that borders the ground should include an Enclosure/Slabs/Slab surface with the appropriate InteriorAdjacentTo. This includes basements, crawlspaces (even when there are dirt floors – use zero for the Thickness), garages, and slab-on-grade foundations.

A primary input for a slab is its ExposedPerimeter. The exposed perimeter should include any slab length that falls along the perimeter of the building’s footprint (i.e., is exposed to ambient conditions). So, a basement slab edge adjacent to a garage or crawlspace, for example, should not be included.

Vertical insulation adjacent to the slab can be described by a PerimeterInsulation/Layer/NominalRValue and a PerimeterInsulationDepth.

Horizontal insulation under the slab can be described by a UnderSlabInsulation/Layer/NominalRValue. The insulation can either have a fixed width (UnderSlabInsulationWidth) or can span the entire slab (UnderSlabInsulationSpansEntireSlab).

For foundation types without walls, the DepthBelowGrade element must be provided. For foundation types with walls, the DepthBelowGrade element is not used; instead the slab’s position relative to grade is determined by the FoundationWall/DepthBelowGrade values.

Windows

Any window or glass door area should be specified as an Enclosure/Windows/Window.

Windows are defined by full-assembly NFRC UFactor and SHGC, as well as Area. Windows must reference a HPXML Enclosures/Walls/Wall element via the AttachedToWall. Windows must also have an Azimuth specified, even if the attached wall does not.

In addition, the summer/winter interior shading coefficients can be optionally entered as InteriorShading/SummerShadingCoefficient and InteriorShading/WinterShadingCoefficient. The summer interior shading coefficient must be less than or equal to the winter interior shading coefficient. Note that a value of 0.7 indicates a 30% reduction in solar gains (i.e., 30% shading). If not provided, default values of 0.70 for summer and 0.85 for winter will be used based on ANSI/RESNET/ICC 301-2019.

Overhangs (e.g., a roof eave) can optionally be defined for a window by specifying a Window/Overhangs element. Overhangs are defined by the vertical distance between the overhang and the top of the window (DistanceToTopOfWindow), and the vertical distance between the overhang and the bottom of the window (DistanceToBottomOfWindow). The difference between these two values equals the height of the window.

Finally, windows can be optionally described with FractionOperable. The input should solely reflect whether the windows are operable (can be opened), not how they are used by the occupants. If a Window represents a single window, the value should be 0 or 1. If a Window represents multiple windows (e.g., 4), the value should be between 0 and 1 (e.g., 0, 0.25, 0.5, 0.75, or 1). If not provided, it is assumed that 67% of the windows are operable. The total open window area for natural ventilation is thus calculated using A) the fraction of windows that are operable, B) the assumption that 50% of the area of operable windows can be open, and C) the assumption that 20% of that openable area is actually opened by occupants whenever outdoor conditions are favorable for cooling.

Skylights

Any skylight should be specified as an Enclosure/Skylights/Skylight.

Skylights are defined by full-assembly NFRC UFactor and SHGC, as well as Area. Skylights must reference a HPXML Enclosures/Roofs/Roof element via the AttachedToRoof. Skylights must also have an Azimuth specified, even if the attached roof does not.

Doors

Any opaque doors should be specified as an Enclosure/Doors/Door.

Doors are defined by RValue and Area. Doors must reference a HPXML Enclosures/Walls/Wall element via the AttachedToWall. Doors must also have an Azimuth specified, even if the attached wall does not.

Systems

This section describes elements specified in HPXML’s Systems.

If any HVAC systems are entered that provide heating (or cooling), the sum of all their FractionHeatLoadServed (or FractionCoolLoadServed) values must be less than or equal to 1. For example, a room air conditioner might be specified with FractionCoolLoadServed equal to 0.3 if it serves 30% of the home’s conditioned floor area.

If any water heating systems are entered, the sum of all their FractionDHWLoadServed values must be equal to 1.

Heating Systems

Each heating system (other than heat pumps) should be entered as a Systems/HVAC/HVACPlant/HeatingSystem. Inputs including HeatingSystemType, and FractionHeatLoadServed must be provided. HeatingCapacity may be provided; if not, the system will be auto-sized via ACCA Manual J/S.

Depending on the type of heating system specified, additional elements are used:

HeatingSystemType	DistributionSystem	HeatingSystemFuel	AnnualHeatingEfficiency
ElectricResistance		electricity	Percent
Furnace	AirDistribution or DSE	<any>	AFUE
WallFurnace		<any>	AFUE
FloorFurnace		<any>	AFUE
Boiler	HydronicDistribution or DSE	<any>	AFUE
Stove		<any>	Percent
PortableHeater		<any>	Percent
Fireplace		<any>	Percent

If a non-electric heating system is specified, the ElectricAuxiliaryEnergy element may be provided if available.

Cooling Systems

Each cooling system (other than heat pumps) should be entered as a Systems/HVAC/HVACPlant/CoolingSystem. Inputs including CoolingSystemType and FractionCoolLoadServed must be provided. For all systems other than evaporative coolers, CoolingCapacity may be provided; if not, the system will be auto-sized via ACCA Manual J/S.

Depending on the type of cooling system specified, additional elements are used:

CoolingSystemType	DistributionSystem	CoolingSystemFuel	AnnualCoolingEfficiency	SensibleHeatFraction
central air conditioner	AirDistribution or DSE	electricity	SEER	(optional)
room air conditioner		electricity	EER	(optional)
evaporative cooler	AirDistribution or DSE (optional)	electricity

Central air conditioners can also have the CompressorType specified; if not provided, it is assumed as follows:

• “single stage”: SEER <= 15
• “two stage”: 15 < SEER <= 21
• “variable speed”: SEER > 21

Heat Pumps

Each heat pump should be entered as a Systems/HVAC/HVACPlant/HeatPump. Inputs including HeatPumpType, FractionHeatLoadServed, and FractionCoolLoadServed must be provided. Note that heat pumps are allowed to provide only heating (FractionCoolLoadServed = 0) or cooling (FractionHeatLoadServed = 0) if appropriate. HeatingCapacity and CoolingCapacity may be provided; if not, the system will be auto-sized via ACCA Manual J/S.

Depending on the type of heat pump specified, additional elements are used:

HeatPumpType	DistributionSystem	HeatPumpFuel	AnnualCoolingEfficiency	AnnualHeatingEfficiency	CoolingSensibleHeatFraction	HeatingCapacity17F
air-to-air	AirDistribution or DSE	electricity	SEER	HSPF	(optional)	(optional)
mini-split	AirDistribution or DSE (optional)	electricity	SEER	HSPF	(optional)	(optional)
ground-to-air	AirDistribution or DSE	electricity	EER	COP	(optional)

Air-to-air heat pumps can also have the CompressorType specified; if not provided, it is assumed as follows:

• “single stage”: SEER <= 15
• “two stage”: 15 < SEER <= 21
• “variable speed”: SEER > 21

If the heat pump has backup heating, it can be specified with BackupSystemFuel, BackupAnnualHeatingEfficiency, and (optionally) BackupHeatingCapacity. If the heat pump has a switchover temperature (e.g., dual-fuel heat pump) where the heat pump stops operating and the backup heating system starts running, it can be specified with BackupHeatingSwitchoverTemperature. If the BackupHeatingSwitchoverTemperature is not provided, the backup heating system will operate as needed when the heat pump has insufficient capacity.

Thermostat

A Systems/HVAC/HVACControl must be provided if any HVAC systems are specified. The heating setpoint (SetpointTempHeatingSeason) and cooling setpoint (SetpointTempCoolingSeason) are required elements.

If there is a heating setback, it is defined with:

• SetbackTempHeatingSeason: Temperature during heating setback
• extension/SetbackStartHourHeating: The start hour of the heating setback where 0=midnight and 12=noon
• TotalSetbackHoursperWeekHeating: The number of hours of heating setback per week

If there is a cooling setup, it is defined with:

• SetupTempCoolingSeason: Temperature during cooling setup
• extension/SetupStartHourCooling: The start hour of the cooling setup where 0=midnight and 12=noon
• TotalSetupHoursperWeekCooling: The number of hours of cooling setup per week

Finally, if there are sufficient ceiling fans present that result in a reduced cooling setpoint, this offset can be specified with extension/CeilingFanSetpointTempCoolingSeasonOffset.

HVAC Distribution

Each separate HVAC distribution system should be specified as a Systems/HVAC/HVACDistribution. There should be at most one heating system and one cooling system attached to a distribution system. See the sections on Heating Systems, Cooling Systems, and Heat Pumps for information on which DistributionSystemType is allowed for which HVAC system. Also note that some HVAC systems (e.g., room air conditioners) are not allowed to be attached to a distribution system.

AirDistribution systems are defined by:

• ConditionedFloorAreaServed
• Optional NumberofReturnRegisters. If not provided, one return register per conditioned floor will be assumed.
• Supply leakage to the outside in CFM25 or percent of airflow (DuctLeakageMeasurement[DuctType='supply']/DuctLeakage/Value)
• Optional return leakage to the outside in CFM25 or percent of airflow (DuctLeakageMeasurement[DuctType='return']/DuctLeakage/Value)
• Optional supply ducts (Ducts[DuctType='supply'])
• Optional return ducts (Ducts[DuctType='return'])

For each duct, DuctInsulationRValue must be provided. DuctLocation and DuctSurfaceArea can be optionally provided. The provided DuctLocation can be one of the following:

Location	Description	Temperature	Default Priority
living space	Above-grade conditioned floor area	EnergyPlus calculation	8
basement - conditioned	Below-grade conditioned floor area	EnergyPlus calculation	1
basement - unconditioned		EnergyPlus calculation	2
crawlspace - unvented		EnergyPlus calculation	4
crawlspace - vented		EnergyPlus calculation	3
attic - unvented		EnergyPlus calculation	6
attic - vented		EnergyPlus calculation	5
garage		EnergyPlus calculation	7
outside		Outside
exterior wall		Average of conditioned space and outside
under slab		Ground
roof deck		Outside
other housing unit	Conditioned space of an adjacent housing unit	Same as conditioned space
other heated space	E.g., shared laundry/equipment space	Average of conditioned space and outside; minimum of 68F
other multifamily buffer space	E.g., enclosed unconditioned stairwell	Average of conditioned space and outside; minimum of 50F
other non-freezing space	E.g., parking garage ceiling	Floats with outside; minimum of 40F

If DuctLocation is not provided, the primary duct location will be chosen based on the presence of spaces and the “Default Priority” indicated above. For a 2+ story home, secondary ducts will also be located in the living space.

If DuctSurfaceArea is not provided, the total duct area will be calculated based on ANSI/ASHRAE Standard 152-2004:

Element Name	Default Value
DuctSurfaceArea (primary supply ducts)	\(0.27 \cdot F_{out} \cdot CFA_{ServedByAirDistribution}\)
DuctSurfaceArea (secondary supply ducts)	\(0.27 \cdot (1 - F_{out}) \cdot CFA_{ServedByAirDistribution}\)
DuctSurfaceArea (primary return ducts)	\(b_r \cdot F_{out} \cdot CFA_{ServedByAirDistribution}\)
DuctSurfaceArea (secondary return ducts)	\(b_r \cdot (1 - F_{out}) \cdot CFA_{ServedByAirDistribution}\)

where F_out is 1.0 for 1-story homes and 0.75 for 2+ story homes and b_r is 0.05 * NumberofReturnRegisters with a maximum value of 0.25.

HydronicDistribution systems do not require any additional inputs.

DSE systems are defined by a AnnualHeatingDistributionSystemEfficiency and AnnualCoolingDistributionSystemEfficiency elements.

Warning

Specifying a DSE for the HVAC distribution system will NOT be reflected in the raw EnergyPlus simulation outputs, but IS reflected in the SimulationOutputReport reporting measure outputs.

Mechanical Ventilation

A single whole-house mechanical ventilation system may be specified as a Systems/MechanicalVentilation/VentilationFans/VentilationFan with UsedForWholeBuildingVentilation='true'. Inputs including FanType, TestedFlowRate (or RatedFlowRate), HoursInOperation, and FanPower must be provided.

Depending on the type of mechanical ventilation specified, additional elements are required:

FanType	SensibleRecoveryEfficiency	TotalRecoveryEfficiency	AttachedToHVACDistributionSystem
energy recovery ventilator	required	required
heat recovery ventilator	required
exhaust only
supply only
balanced
central fan integrated supply (CFIS)			required

Note that AdjustedSensibleRecoveryEfficiency and AdjustedTotalRecoveryEfficiency can be provided instead.

In many situations, the rated flow rate should be the value derived from actual testing of the system. For a CFIS system, the rated flow rate should equal the amount of outdoor air provided to the distribution system.

Kitchen Fan

A kitchen range fan may be specified as a Systems/MechanicalVentilation/VentilationFans/VentilationFan with FanLocation='kitchen' and UsedForLocalVentilation='true'.

Additional fields may be provided per the table below. If not provided, default values will be assumed based on the Building America House Simulation Protocols.

Element Name	Default Value
RatedFlowRate [cfm]	100
HoursInOperation [hrs/day]	1
FanPower [W]	0.3 * RatedFlowRate
extension/StartHour [0-23]	18

Bathroom Fans

Bathroom fans may be specified as a Systems/MechanicalVentilation/VentilationFans/VentilationFan with FanLocation='bath' and UsedForLocalVentilation='true'.

Additional fields may be provided per the table below. If not provided, default values will be assumed based on the Building America House Simulation Protocols.

Element Name	Default Value
Quantity [#]	NumberofBathrooms
RatedFlowRate [cfm]	50
HoursInOperation [hrs/day]	1
FanPower [W]	0.3 * RatedFlowRate
extension/StartHour [0-23]	7

Whole House Fan

A single whole house fan may be specified as a Systems/MechanicalVentilation/VentilationFans/VentilationFan with UsedForSeasonalCoolingLoadReduction='true'. Required elements include RatedFlowRate and FanPower.

The whole house fan is assumed to operate during hours of favorable outdoor conditions. If available, it will take priority over natural ventilation.

Water Heaters

Each water heater should be entered as a Systems/WaterHeating/WaterHeatingSystem. Inputs including WaterHeaterType and FractionDHWLoadServed must be provided.

Depending on the type of water heater specified, additional elements are required/available:

WaterHeaterType	UniformEnergyFactor or EnergyFactor	FuelType	TankVolume	HeatingCapacity	RecoveryEfficiency	PerformanceAdjustment	UsesDesuperheater	WaterHeaterInsulation/Jacket/JacketRValue	RelatedHVACSystem
storage water heater	required	<any>	<optional>	<optional>	<optional>		<optional>	<optional>	required if uses desuperheater
instantaneous water heater	required	<any>				<optional>	<optional>		required if uses desuperheater
heat pump water heater	required	electricity	required				<optional>	<optional>	required if uses desuperheater
space-heating boiler with storage tank			required					<optional>	required
space-heating boiler with tankless coil									required

For storage water heaters, the tank volume in gallons, heating capacity in Btuh, and recovery efficiency can be optionally provided. If not provided, default values for the tank volume and heating capacity will be assumed based on Table 8 in the 2014 Building America House Simulation Protocols and a default recovery efficiency shown in the table below will be assumed based on regression analysis of AHRI certified water heaters.

EnergyFactor	RecoveryEfficiency (default)
>= 0.75	0.778114 * EF + 0.276679
< 0.75	0.252117 * EF + 0.607997

For tankless water heaters, a performance adjustment due to cycling inefficiencies can be provided. If not provided, a default value of 0.92 (92%) will apply to the Energy Factor.

For combi boiler systems, the RelatedHVACSystem must point to a HeatingSystem of type “Boiler”. For combi boiler systems with a storage tank, the storage tank losses (deg-F/hr) can be entered as StandbyLoss; if not provided, a default value based on the AHRI Directory of Certified Product Performance will be calculated.

For water heaters that are connected to a desuperheater, the RelatedHVACSystem must either point to a HeatPump or a CoolingSystem.

The water heater Location can be optionally entered as one of the following:

Location	Description	Temperature
living space	Above-grade conditioned floor area	EnergyPlus calculation
basement - conditioned	Below-grade conditioned floor area	EnergyPlus calculation
basement - unconditioned		EnergyPlus calculation
attic - unvented		EnergyPlus calculation
attic - vented		EnergyPlus calculation
garage		EnergyPlus calculation
crawlspace - unvented		EnergyPlus calculation
crawlspace - vented		EnergyPlus calculation
other exterior	Outside	EnergyPlus calculation
other housing unit	Conditioned space of an adjacent housing unit	Same as conditioned space
other heated space	E.g., shared laundry/equipment space	Average of conditioned space and outside; minimum of 68F
other multifamily buffer space	E.g., enclosed unconditioned stairwell	Average of conditioned space and outside; minimum of 50F
other non-freezing space	E.g., parking garage ceiling	Floats with outside; minimum of 40F

If the location is not provided, a default water heater location will be assumed based on IECC climate zone:

IECC Climate Zone	Location (default)
1-3, excluding 3A	garage if present, otherwise living space
3A, 4-8, unknown	conditioned basement if present, otherwise unconditioned basement if present, otherwise living space

The setpoint temperature may be provided as HotWaterTemperature; if not provided, 125F is assumed.

Hot Water Distribution

A Systems/WaterHeating/HotWaterDistribution must be provided if any water heating systems are specified. Inputs including SystemType and PipeInsulation/PipeRValue must be provided.

For a SystemType/Standard (non-recirculating) system, the following element are used:

• PipingLength: Optional. Measured length of hot water piping from the hot water heater to the farthest hot water fixture, measured longitudinally from plans, assuming the hot water piping does not run diagonally, plus 10 feet of piping for each floor level, plus 5 feet of piping for unconditioned basements (if any) If not provided, a default PipingLength will be calculated using the following equation from ANSI/RESNET/ICC 301-2019.

  \[PipeL = 2.0 \cdot (\frac{CFA}{NCfl})^{0.5} + 10.0 \cdot NCfl + 5.0 \cdot bsmnt\]

  Where, PipeL = piping length [ft], CFA = conditioned floor area [ft²], NCfl = number of conditioned floor levels number of conditioned floor levels in the residence including conditioned basements, bsmnt = presence = 1.0 or absence = 0.0 of an unconditioned basement in the residence.

For a SystemType/Recirculation system, the following elements are used:

• ControlType

• RecirculationPipingLoopLength: Optional. If not provided, the default value will be calculated by using the equation shown in the table below. Measured recirculation loop length including both supply and return sides, measured longitudinally from plans, assuming the hot water piping does not run diagonally, plus 20 feet of piping for each floor level greater than one plus 10 feet of piping for unconditioned basements.

• BranchPipingLoopLength: Optional. If not provided, the default value will be assumed as shown in the table below. Measured length of the branch hot water piping from the recirculation loop to the farthest hot water fixture from the recirculation loop, measured longitudinally from plans, assuming the branch hot water piping does not run diagonally.

• PumpPower: Optional. If not provided, the default value will be assumed as shown in the table below.

  Element Name	Default Value
  RecirculationPipingLoopLength [ft]	\(2.0 \cdot (2.0 \cdot (\frac{CFA}{NCfl})^{0.5} + 10.0 \cdot NCfl + 5.0 \cdot bsmnt) - 20.0\)
  BranchPipingLoopLength [ft]	10
  Pump Power [W]	50

In addition, a HotWaterDistribution/DrainWaterHeatRecovery (DWHR) may be specified. The DWHR system is defined by:

• FacilitiesConnected: ‘one’ if there are multiple showers and only one of them is connected to a DWHR; ‘all’ if there is one shower and it’s connected to a DWHR or there are two or more showers connected to a DWHR
• EqualFlow: ‘true’ if the DWHR supplies pre-heated water to both the fixture cold water piping and the hot water heater potable supply piping
• Efficiency: As rated and labeled in accordance with CSA 55.1

Water Fixtures

Water fixtures should be entered as Systems/WaterHeating/WaterFixture elements. Each fixture must have WaterFixtureType and LowFlow elements provided. Fixtures should be specified as low flow if they are <= 2.0 gpm.

A WaterHeating/extension/WaterFixturesUsageMultiplier can also be optionally provided that scales hot water usage; if not provided, it is assumed to be 1.0.

Solar Thermal

A solar hot water system can be entered as a Systems/SolarThermal/SolarThermalSystem. The SystemType element must be ‘hot water’.

Solar hot water systems can be described with either simple or detailed inputs.

If using simple inputs, the following elements are used:

• SolarFraction: Portion of total conventional hot water heating load (delivered energy and tank standby losses). Can be obtained from Directory of SRCC OG-300 Solar Water Heating System Ratings or NREL’s System Advisor Model or equivalent.
• ConnectedTo: Optional. If not specified, applies to all water heaters in the building. If specified, must point to a WaterHeatingSystem.

If using detailed inputs, the following elements are used:

• CollectorArea: in units of ft²
• CollectorLoopType: ‘liquid indirect’ or ‘liquid direct’ or ‘passive thermosyphon’
• CollectorType: ‘single glazing black’ or ‘double glazing black’ or ‘evacuated tube’ or ‘integrated collector storage’
• CollectorAzimuth
• CollectorTilt
• CollectorRatedOpticalEfficiency: FRTA (y-intercept); see Directory of SRCC OG-100 Certified Solar Collector Ratings
• CollectorRatedThermalLosses: FRUL (slope, in units of Btu/hr-ft²-R); see Directory of SRCC OG-100 Certified Solar Collector Ratings
• StorageVolume: Optional. If not provided, the default value in gallons will be calculated as 1.5 * CollectorArea
• ConnectedTo: Must point to a WaterHeatingSystem. The connected water heater cannot be of type space-heating boiler or attached to a desuperheater.

Photovoltaics

Each solar electric (photovoltaic) system should be entered as a Systems/Photovoltaics/PVSystem. The following elements, some adopted from the PVWatts model, are required for each PV system:

• Location: ‘ground’ or ‘roof’ mounted
• ModuleType: ‘standard’, ‘premium’, or ‘thin film’
• Tracking: ‘fixed’ or ‘1-axis’ or ‘1-axis backtracked’ or ‘2-axis’
• ArrayAzimuth
• ArrayTilt
• MaxPowerOutput

Inputs including InverterEfficiency, SystemLossesFraction, and YearModulesManufactured can be optionally entered. If InverterEfficiency is not provided, the default value of 0.96 is assumed.

SystemLossesFraction includes the effects of soiling, shading, snow, mismatch, wiring, degradation, etc. If neither SystemLossesFraction or YearModulesManufactured are provided, a default value of 0.14 will be used. If SystemLossesFraction is not provided but YearModulesManufactured is provided, SystemLossesFraction will be calculated using the following equation.

\[System Losses Fraction = 1.0 - (1.0 - 0.14) \cdot (1.0 - (1.0 - 0.995^{(CurrentYear - YearModulesManufactured)}))\]

Appliances

This section describes elements specified in HPXML’s Appliances.

The Location for each appliance can be optionally provided as one of the following:

Location	Description
living space	Above-grade conditioned floor area
basement - conditioned	Below-grade conditioned floor area
basement - unconditioned
garage
other	Any attached/multifamily space outside the unit, in which internal gains are neglected

If the location is not specified, the appliance is assumed to be in the living space.

Clothes Washer

An Appliances/ClothesWasher element can be specified; if not provided, a clothes washer will not be modeled.

Several EnergyGuide label inputs describing the efficiency of the appliance can be provided. If the complete set of efficiency inputs is not provided, the following default values representing a standard clothes washer from 2006 will be used.

Element Name	Default Value
IntegratedModifiedEnergyFactor [ft³/kWh-cyc]	1.0
RatedAnnualkWh [kWh/yr]	400
LabelElectricRate [$/kWh]	0.12
LabelGasRate [$/therm]	1.09
LabelAnnualGasCost [$]	27.0
Capacity [ft³]	3.0
LabelUsage [cyc/week]	6

If ModifiedEnergyFactor is provided instead of IntegratedModifiedEnergyFactor, it will be converted using the following equation based on the Interpretation on ANSI/RESNET 301-2014 Clothes Washer IMEF.

\[IntegratedModifiedEnergyFactor = \frac{ModifiedEnergyFactor - 0.503}{0.95}\]

An extension/UsageMultiplier can also be optionally provided that scales energy and hot water usage; if not provided, it is assumed to be 1.0.

Clothes Dryer

An Appliances/ClothesDryer element can be specified; if not provided, a clothes dryer will not be modeled. The dryer’s FuelType must be provided.

Several EnergyGuide label inputs describing the efficiency of the appliance can be provided. If the complete set of efficiency inputs is not provided, the following default values representing a standard clothes dryer from 2006 will be used.

Element Name	Default Value
CombinedEnergyFactor [lb/kWh]	3.01
ControlType	timer

If EnergyFactor is provided instead of CombinedEnergyFactor, it will be converted into CombinedEnergyFactor using the following equation based on the Interpretation on ANSI/RESNET/ICC 301-2014 Clothes Dryer CEF.

\[CombinedEnergyFactor = \frac{EnergyFactor}{1.15}\]

An extension/UsageMultiplier can also be optionally provided that scales energy usage; if not provided, it is assumed to be 1.0.

Dishwasher

An Appliances/Dishwasher element can be specified; if not provided, a dishwasher will not be modeled.

Several EnergyGuide label inputs describing the efficiency of the appliance can be provided. If the complete set of efficiency inputs is not provided, the following default values representing a standard dishwasher from 2006 will be used.

Element Name	Default Value
RatedAnnualkWh [kwh/yr]	467
LabelElectricRate [$/kWh]	0.12
LabelGasRate [$/therm]	1.09
LabelAnnualGasCost [$]	33.12
PlaceSettingCapacity [#]	12
LabelUsage [cyc/week]	4

If EnergyFactor is provided instead of RatedAnnualkWh, it will be converted into RatedAnnualkWh using the following equation based on ANSI/RESNET/ICC 301-2014.

\[RatedAnnualkWh = \frac{215.0}{EnergyFactor}\]

An extension/UsageMultiplier can also be optionally provided that scales energy and hot water usage; if not provided, it is assumed to be 1.0.

Refrigerator

An Appliances/Refrigerator element can be specified; if not provided, a refrigerator will not be modeled.

The efficiency of the refrigerator can be optionally entered as RatedAnnualkWh or extension/AdjustedAnnualkWh. If neither are provided, RatedAnnualkWh will be defaulted to represent a standard refrigerator from 2006 using the following equation based on ANSI/RESNET/ICC 301-2019.

\[RatedAnnualkWh = 637.0 + 18.0 \cdot NumberofBedrooms\]

Optional extension/WeekdayScheduleFractions, extension/WeekendScheduleFractions, and extension/MonthlyScheduleMultipliers can be provided; if not provided, values from Figures 16 & 24 of the Building America House Simulation Protocols are used. An extension/UsageMultiplier can also be optionally provided that scales energy usage; if not provided, it is assumed to be 1.0.

Cooking Range/Oven

Appliances/CookingRange and Appliances/Oven elements can be specified; if not provided, a range/oven will not be modeled. The FuelType of the range must be provided.

Inputs including CookingRange/IsInduction and Oven/IsConvection can be optionally provided. The following default values will be assumed unless a complete set of the optional variables is provided.

Element Name	Default Value
IsInduction	false
IsConvection	false

Optional CookingRange/extension/WeekdayScheduleFractions, CookingRange/extension/WeekendScheduleFractions, and CookingRange/extension/MonthlyScheduleMultipliers can be provided; if not provided, values from Figures 22 & 24 of the Building America House Simulation Protocols are used. An CookingRange/extension/UsageMultiplier can also be optionally provided that scales energy usage; if not provided, it is assumed to be 1.0.

Dehumidifier

An Appliance/Dehumidifier element can be specified; if not provided, a dehumidifier will not be modeled. The Capacity, DehumidistatSetpoint (relative humidity as a fraction, 0-1), and FractionDehumidificationLoadServed (0-1) must be provided. The efficiency of the dehumidifier can either be entered as an IntegratedEnergyFactor or EnergyFactor.

Lighting

The building’s lighting is described by nine Lighting/LightingGroup elements, each of which is the combination of:

• LightingType: ‘LightEmittingDiode’, ‘CompactFluorescent’, and ‘FluorescentTube’
• Location: ‘interior’, ‘garage’, and ‘exterior’

The fraction of lamps of the given type in the given location are provided as the LightingGroup/FractionofUnitsInLocation. The fractions for a given location cannot sum to greater than 1. If the fractions sum to less than 1, the remainder is assumed to be incandescent lighting. Garage lighting values are ignored if the building has no garage.

A Lighting/extension/UsageMultiplier can also be optionally provided that scales energy usage; if not provided, it is assumed to be 1.0.

Ceiling Fans

Each ceiling fan (or set of identical ceiling fans) should be entered as a Lighting/CeilingFan. The Airflow/Efficiency (at medium speed) and Quantity can be provided, otherwise the following default assumptions are used from ANSI/RESNET/ICC 301-2019.

Element Name	Default Value
Airflow/Efficiency [cfm/W]	3000/42.6
Quantity [#]	NumberofBedrooms+1

In addition, a reduced cooling setpoint can be specified for summer months when ceiling fans are operating. See the Thermostat section for more information.

Plug Loads

Plug loads can be provided by entering MiscLoads/PlugLoad elements; if not provided, plug loads will not be modeled. Currently only plug loads specified with PlugLoadType='other' and PlugLoadType='TV other' are recognized. The annual energy consumption (Load[Units='kWh/year']/Value) can be provided, otherwise they will be calculated using the following equations from ANSI/RESNET/ICC 301-2019.

\[TelevisionkWhs = 413.0 + 69.0 \cdot NumberofBedrooms\]

\[OtherkWhs = 0.91 \cdot ConditionedFloorArea\]

An extension/UsageMultiplier can also be optionally provided that scales energy usage; if not provided, it is assumed to be 1.0.

Validating & Debugging Errors

When running HPXML files, errors may occur because:

1. An HPXML file provided is invalid (either relative to the HPXML schema or the EnergyPlus Use Case).
2. An unexpected EnergyPlus simulation error occurred.

If an error occurs, first look in the run.log for details. If there are no errors in that log file, then the error may be in the EnergyPlus simulation – see eplusout.err.

Contact us if you can’t figure out the cause of an error.

Sample Files

Dozens of sample HPXML files are included in the workflow/sample_files directory. The sample files help to illustrate how different building components are described in HPXML.

Each sample file generally makes one isolated change relative to the base HPXML (base.xml) building. For example, the base-dhw-dwhr.xml file adds a DrainWaterHeatRecovery element to the building.

You may find it useful to search through the files for certain HPXML elements or compare (diff) a sample file to the base.xml file.

SimulationOutputReport Measure

The SimulationOutputReport reporting measure generates a variety of annual (and optionally, timeseries) outputs for a residential HPXML-based model.

Annual Outputs

The measure will always generate an annual CSV output file called results_annual.csv, co-located with the EnergyPlus output. The CSV file includes the following sections of output:

Annual Energy Consumption by Fuel Type

Current fuel types are:

Type	Notes
Electricity: Total (MBtu)
Electricity: Net (MBtu)	Excludes any PV generation.
Natural Gas: Total (MBtu)
Fuel Oil: Total (MBtu)
Propane: Total (MBtu)
Wood: Total (MBtu)
Wood Pellets: Total (MBtu)

Annual Energy Consumption By Fuel Type and End Use

Current end use/fuel type combinations are:

Type	Notes	Type (cont’d)	Notes
Electricity: Heating (MBtu)		Natural Gas: Heating (MBtu)
Electricity: Heating Fans/Pumps (MBtu)		Natural Gas: Hot Water (MBtu)
Electricity: Cooling (MBtu)		Natural Gas: Clothes Dryer (MBtu)
Electricity: Cooling Fans/Pumps (MBtu)		Natural Gas: Range/Oven (MBtu)
Electricity: Hot Water (MBtu)		Fuel Oil: Heating (MBtu)
Electricity: Hot Water Recirc Pump (MBtu)		Fuel Oil: Hot Water (MBtu)
Electricity: Hot Water Solar Thermal Pump (MBtu)		Fuel Oil: Clothes Dryer (MBtu)
Electricity: Lighting Interior (MBtu)		Fuel Oil: Range/Oven (MBtu)
Electricity: Lighting Garage (MBtu)		Propane: Heating (MBtu)
Electricity: Lighting Exterior (MBtu)		Propane: Hot Water (MBtu)
Electricity: Mech Vent (MBtu)		Propane: Clothes Dryer (MBtu)
Electricity: Whole House Fan (MBtu)		Propane: Range/Oven (MBtu)
Electricity: Refrigerator (MBtu)		Wood: Heating (MBtu)
Electricity: Dehumidifier (MBtu)		Wood: Hot Water (MBtu)
Electricity: Dishwasher (MBtu)		Wood: Clothes Dryer (MBtu)
Electricity: Clothes Washer (MBtu)		Wood: Range/Oven (MBtu)
Electricity: Clothes Dryer (MBtu)		Wood Pellets: Heating (MBtu)
Electricity: Range/Oven (MBtu)
Electricity: Ceiling Fan (MBtu)
Electricity: Television (MBtu)
Electricity: Plug Loads (MBtu)
Electricity: PV (MBtu)

Annual Building Loads

Current annual building loads are:

Type	Notes
Load: Heating (MBtu)	Includes HVAC distribution losses.
Load: Cooling (MBtu)	Includes HVAC distribution losses.
Load: Hot Water: Delivered (MBtu)	Includes contributions by desuperheaters or solar thermal systems.
Load: Hot Water: Tank Losses (MBtu)
Load: Hot Water: Desuperheater (MBtu)	Load served by the desuperheater.
Load: Hot Water: Solar Thermal (MBtu)	Load served by the solar thermal system.

Annual Unmet Building Loads

Current annual unmet building loads are:

Type	Notes
Unmet Load: Heating (MBtu)
Unmet Load: Cooling (MBtu)

These numbers reflect the amount of heating/cooling load that is not met by the HVAC system, indicating the degree to which the HVAC system is undersized. An HVAC system with sufficient capacity to perfectly maintain the thermostat setpoints will report an unmet load of zero.

Peak Building Electricity

Current peak building electricity outputs are:

Type	Notes
Peak Electricity: Winter Total (W)	Winter season defined by operation of the heating system.
Peak Electricity: Summer Total (W)	Summer season defined by operation of the cooling system.

Peak Building Loads

Current peak building loads are:

Type	Notes
Peak Load: Heating (kBtu)	Includes HVAC distribution losses.
Peak Load: Cooling (kBtu)	Includes HVAC distribution losses.

Annual Component Building Loads

Component loads represent the estimated contribution of different building components to the annual heating/cooling building loads. The sum of component loads for heating (or cooling) will roughly equal the annual heating (or cooling) building load reported above. Current component loads disaggregated by Heating/Cooling are:

Type	Notes
Component Load: *: Roofs (MBtu)	Heat gain/loss through HPXML Roof elements adjacent to conditioned space
Component Load: *: Ceilings (MBtu)	Heat gain/loss through HPXML FrameFloor elements (inferred to be ceilings) adjacent to conditioned space
Component Load: *: Walls (MBtu)	Heat gain/loss through HPXML Wall elements adjacent to conditioned space
Component Load: *: Rim Joists (MBtu)	Heat gain/loss through HPXML RimJoist elements adjacent to conditioned space
Component Load: *: Foundation Walls (MBtu)	Heat gain/loss through HPXML FoundationWall elements adjacent to conditioned space
Component Load: *: Doors (MBtu)	Heat gain/loss through HPXML Door elements adjacent to conditioned space
Component Load: *: Windows (MBtu)	Heat gain/loss through HPXML Window elements adjacent to conditioned space, including solar
Component Load: *: Skylights (MBtu)	Heat gain/loss through HPXML Skylight elements adjacent to conditioned space, including solar
Component Load: *: Floors (MBtu)	Heat gain/loss through HPXML FrameFloor elements (inferred to be floors) adjacent to conditioned space
Component Load: *: Slabs (MBtu)	Heat gain/loss through HPXML Slab elements adjacent to conditioned space
Component Load: *: Internal Mass (MBtu)	Heat gain/loss from internal mass (e.g., furniture, interior walls/floors) in conditioned space
Component Load: *: Infiltration (MBtu)	Heat gain/loss from airflow induced by stack and wind effects
Component Load: *: Natural Ventilation (MBtu)	Heat gain/loss from airflow through operable windows
Component Load: *: Mechanical Ventilation (MBtu)	Heat gain/loss from airflow/fan energy from a whole house mechanical ventilation system
Component Load: *: Whole House Fan (MBtu)	Heat gain/loss from airflow due to a whole house fan
Component Load: *: Ducts (MBtu)	Heat gain/loss from conduction and leakage losses through supply/return ducts outside conditioned space
Component Load: *: Internal Gains (MBtu)	Heat gain/loss from appliances, lighting, plug loads, water heater tank losses, etc. in the conditioned space

Annual Hot Water Uses

Current annual hot water uses are:

Type	Notes
Hot Water: Clothes Washer (gal)
Hot Water: Dishwasher (gal)
Hot Water: Fixtures (gal)	Showers and faucets.
Hot Water: Distribution Waste (gal)

Timeseries Outputs

The measure will generate a timeseries CSV output file if the Timeseries Reporting Frequency argument is specified and one or more Generate Timeseries Output arguments are true. The timeseries output file is called results_timeseries.csv and co-located with the EnergyPlus output.

Depending on the outputs requested, CSV files may include:

Type	Notes
Fuel Consumptions	Energy use for each fuel type (in kBtu for fossil fuels and kWh for electricity).
End Use Consumptions	Energy use for each end use type (in kBtu for fossil fuels and kWh for electricity).
Hot Water Uses	Water use for each end use type (in gallons).
Total Loads	Heating and cooling loads (in kBtu) for the building.
Component Loads	Heating and cooling loads (in kBtu) disaggregated by component (e.g., Walls, Windows, Infiltration, Ducts, etc.).
Zone Temperatures	Average temperatures (in deg-F) for each space modeled (e.g., living space, attic, garage, basement, crawlspace, etc.).
Airflows	Airflow rates (in cfm) for infiltration, mechanical ventilation, natural ventilation, and whole house fans.
Weather	Weather file data including outdoor temperatures, relative humidity, wind speed, and solar.

Indices and tables

• Index
• Search Page