OpenStudio-ERI documentation

Introduction

The OpenStudio-ERI project allows calculating an Energy Rating Index (ERI) using the Department of Energy’s open-source OpenStudio/EnergyPlus simulation platform. The building description is provided in an HPXML file format.

ERI is defined by ANSI/RESNET/ICC 301-2014© “Standard for the Calculation and Labeling of the Energy Performance of Low-Rise Residential Buildings using an Energy Rating Index”.

License

This workflow 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.

Disclaimer

Downloading and using this software from this website does not constitute accreditation of the final software product by RESNET. If you are seeking to develop RESNET Accredited Rating Software, you will need to submit your final software product to RESNET for accreditation.

Any reference herein to RESNET, its activities, products, or services, or any linkages from this website to RESNET’s website, does not constitute or imply the endorsement, recommendation, or favoring of the U.S. Government, the Alliance for Sustainable Energy, or any of their employees or contractors acting on their behalf.

Capabilities

ERI Capabilities

The following ERI Standards and Addenda are currently available:

• ANSI/RESNET/ICC 301-2014© “Standard for the Calculation and Labeling of the Energy Performance of Low-Rise Residential Buildings using an Energy Rating Index”.
• ANSI/RESNET/ICC 301-2014 Addendum A-2015, Domestic Hot Water Systems, January 15, 2016
• ANSI/RESNET/ICC 301-2014 Addendum D-2017, Duct Leakage to Outside Test Exception, January 1, 2018
• ANSI/RESNET/ICC 301-2014 Addendum E-2018, House Size Index Adjustment Factors, February 1, 2018
• ANSI/RESNET/ICC 301-2014 Addendum G-2018, Solid State Lighting, February 2, 2018
• ANSI/RESNET/ICC 301-2014 Addendum L-2018, Duct Leakage to Outside Test Exception, July 1, 2019
• ANSI/RESNET/ICC 301-2019 “Standard for the Calculation and Labeling of the Energy Performance of Dwelling and Sleeping Units using an Energy Rating Index”.
• ANSI/RESNET/ICC 301-2019 Addendum A-2019, Clothes Washers and Dryers and Dishwashers, July 1, 2020

Accuracy vs Speed

The EnergyPlus simulation engine is like a Swiss army knife. There are often multiple models available for the same building technology with varying trade-offs between accuracy and speed. This workflow standardizes the use of EnergyPlus (e.g., the choice of models appropriate for residential buildings) to provide a fast and easy to use solution.

The workflow is continuously being evaluated for ways to reduce runtime without significant impact on accuracy. A number of such enhancements have been made to date.

There are additional ways that software developers using this workflow can reduce runtime:

• Run on Linux/Mac platform, which is significantly faster by taking advantage of the POSIX fork call.
• Do not use the --hourly flag unless hourly output is required. If required, limit requests to hourly variables of interest.
• Run on computing environments with 1) fast CPUs, 2) sufficient memory, and 3) enough processors to allow all simulations to run in parallel.

Getting Started

Here is a brief overview on getting setup, running an ERI calculation, and obtaining outputs.

Setup

To get started:

1. Either download OpenStudio 3.1.0 and install the Command Line Interface/EnergyPlus components, or use the nrel/openstudio docker image.
2. Download the latest release release.
3. To obtain all available weather files, run: openstudio workflow/energy_rating_index.rb --download-weather

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.

Running

Run the ERI calculation on a provided sample HPXML file as follows: openstudio workflow/energy_rating_index.rb -x workflow/sample_files/base.xml

Note that the Reference Home, Rated Home and Index Adjustment Home (if applicable) simulations will be executed in parallel on the local machine.

This will generate output as shown below:

You can also request generation of hourly output CSV files as part of the calculation by providing one or more --hourly flags.

To request all possible hourly outputs: openstudio workflow/energy_rating_index.rb -x workflow/sample_files/base.xml --hourly ALL

Or one or more specific hourly output types can be requested, e.g.: openstudio workflow/energy_rating_index.rb -x workflow/sample_files/base.xml --hourly fuels --hourly temperatures

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

Output

Upon completion, ERI is provided in the console (stdout) as well as available in some of the summary output files. See the Workflow Outputs section for a description of all available outputs.

Workflow Inputs

Introduction

OpenStudio-ERI 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.

HPXML Inputs

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, a stricter set of requirements for the HPXML file have been developed for purposes of running an Energy Rating Index calculation.

HPXML files submitted to OpenStudio-ERI should undergo a two step validation process:

1. Validation against the HPXML Schema

The HPXML XSD Schema can be found at hpxml-measures/HPXMLtoOpenStudio/resources/HPXML.xsd. It should be used by the software developer to validate their HPXML file prior to running the workflow. XSD Schemas are used to validate what elements/attributes/enumerations are available, data types for elements/attributes, the number/order of children elements, etc.

OpenStudio-ERI does not validate the HPXML file against the XSD Schema and assumes the file submitted is valid. However, OpenStudio-ERI does automatically check for valid data types (e.g., integer vs string), enumeration choices, and numeric values within min/max.

2. Validation using Schematron

The Schematron document for the ERI use case can be found at rulesets/301EnergyRatingIndexRuleset/resources/301validator.xml. Schematron is a rule-based validation language, expressed in XML using XPath expressions, for validating the presence or absence of inputs in XML files. As opposed to an XSD Schema, a Schematron document validates constraints and requirements based on conditionals and other logical statements. For example, if an element is specified with a particular value, the applicable enumerations of another element may change.

OpenStudio-ERI automatically validates the HPXML file against the Schematron document and reports any validation errors, but software developers may find it beneficial to also integrate Schematron validation into their software.

Important

Usage of both validation approaches (XSD and Schematron) is recommended for developers actively working on creating HPXML files for Energy Rating Index calculations:

• Validation against XSD for general correctness and usage of HPXML
• Validation against Schematron for understanding XML document requirements specific to running ERI calculations

HPXML Software Info

High-level simulation inputs are entered in /HPXML/SoftwareInfo.

HPXML ERI Calculation

The version of the ERI calculation is entered in /HPXML/SoftwareInfo/extension/ERICalculation.

Element	Type	Units	Constraints	Required	Default	Description
Version	string		See [1]	Yes		Version of 301 Standard w/ addenda

[1]

Version choices are “latest”, “2019AB”, “2019A”, “2019”, “2014ADEGL”, “2014ADEG”, “2014ADE”, “2014AD”, “2014A”, or “2014”. For example, a value of “2019AB” tells the workflow to use ANSI/RESNET/ICC© 301-2019 with both Addendum A and Addendum B included. A value of “latest” can be used to always point to the latest version available.

HPXML Building Summary

High-level building summary information is entered in /HPXML/Building/BuildingDetails/BuildingSummary.

HPXML Site

Each fuel type available to the building is entered in /HPXML/Building/BuildingDetails/BuildingSummary/Site/FuelTypesAvailable.

Element	Type	Units	Constraints	Required	Default	Description
Fuel	string		See [2]	Yes		Fuel name

[2]	Fuel choices can be found at the HPXML Toolbox website.

Note

The provided fuels are used to determine whether the home has access to natural gas or fossil fuel delivery (specified by any value other than “electricity”). This information may be used for determining the heating system, as specified by the ERI 301 Standard.

HPXML Building Construction

Building construction is entered in /HPXML/Building/BuildingDetails/BuildingSummary/BuildingConstruction.

Element	Type	Units	Constraints	Required	Default	Notes
ResidentialFacilityType	string		See [3]	Yes		Type of dwelling unit
NumberofConditionedFloors	double		> 0	Yes		Number of conditioned floors (including a basement)
NumberofConditionedFloorsAboveGrade	double		> 0, <= NumberofConditionedFloors	Yes		Number of conditioned floors above grade (including a walkout basement)
NumberofBedrooms	integer		> 0	Yes		Number of bedrooms
ConditionedFloorArea	double	ft2	> 0	Yes		Floor area within conditioned space boundary
ConditionedBuildingVolume	double	ft3 or ft	> 0	Yes		Volume within conditioned space boundary

[3]	ResidentialFacilityType choices are “single-family detached”, “single-family attached”, “apartment unit”, or “manufactured home”.

HPXML Weather Station

Weather information is entered in /HPXML/Building/BuildingDetails/ClimateandRiskZones/WeatherStation.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
Name	string			Yes		Name of weather station
extension/EPWFilePath	string			Yes		Path to the EnergyPlus weather file (EPW) [4]

[4]	A full set of U.S. TMY3 weather files can be downloaded here.

HPXML Climate Zone

The IECC climate zone is entered in /HPXML/Building/BuildingDetails/ClimateandRiskZones/ClimateZoneIECC.

Element	Type	Units	Constraints	Required	Default	Notes
Year	integer		See [5]	Yes		IECC year
ClimateZone	string		See [6]	Yes		IECC zone

[5]	Year choices are 2003, 2006, 2009, or 2012.

[6]	ClimateZone choices are “1A”, “1B”, “1C”, “2A”, “2B”, “2C”, “3A”, “3B”, “3C”, “4A”, “4B”, “4C”, “5A”, “5B”, “5C”, “6A”, “6B”, “6C”, “7”, or “8”.

HPXML Enclosure

The dwelling unit’s enclosure is entered in /HPXML/Building/BuildingDetails/Enclosure.

All surfaces that bound different space types of the dwelling unit (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.

Interior partition surfaces (e.g., walls between rooms inside conditioned space, or the floor between two conditioned stories) can be excluded.

For single-family attached (SFA) or multifamily (MF) buildings, surfaces between unconditioned space and the neighboring unit’s same unconditioned space should set InteriorAdjacentTo and ExteriorAdjacentTo to the same value. For example, a foundation wall between the unit’s vented crawlspace and the neighboring unit’s vented crawlspace would use InteriorAdjacentTo="crawlspace - vented" and ExteriorAdjacentTo="crawlspace - vented".

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.

HPXML Air Infiltration

Building air leakage is entered in /HPXML/Building/BuildingDetails/Enclosure/AirInfiltration/AirInfiltrationMeasurement.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
BuildingAirLeakage/UnitofMeasure	string		See [7]	Yes		Units for air leakage
HousePressure	double	Pa	> 0	See [8]		House pressure with respect to outside [9]
BuildingAirLeakage/AirLeakage	double		> 0	Yes		Value for air leakage
InfiltrationVolume	double	ft3	> 0, >= ConditionedBuildingVolume	Yes		Volume associated with infiltration measurement

[7]	UnitofMeasure choices are “ACH” (air changes per hour at user-specified pressure), “CFM” (cubic feet per minute at user-specified pressure), or “ACHnatural” (natural air changes per hour).

[8]	HousePressure only required if BuildingAirLeakage/UnitofMeasure is not “ACHnatural”.

[9]	HousePressure typical value is 50 Pa.

HPXML Attics

If the dwelling unit has an unvented attic, whether it is within the infiltration volume is entered in /HPXML/Building/BuildingDetails/Enclosure/Attics/Attic[AtticType/Attic[Vented="false"]].

Element	Type	Units	Constraints	Required	Default	Notes
WithinInfiltrationVolume	boolean			Yes		In accordance with ANSI/RESNET/ICC Standard 380

If the dwelling unit has a vented attic, attic ventilation information can be optionally entered in /HPXML/Building/BuildingDetails/Enclosure/Attics/Attic[AtticType/Attic[Vented="true"]]/VentilationRate.

Element	Type	Units	Constraints	Required	Default	Notes
UnitofMeasure	string		See [10]	No	SLA	Units for ventilation rate
Value	double		> 0	No	1/300	Value for ventilation rate

[10]	UnitofMeasure choices are “SLA” (specific leakage area) or “ACHnatural” (natural air changes per hour).

HPXML Foundations

If the dwelling unit has an unconditioned basement, whether it is within the infiltration volume is entered in Enclosure/Foundations/Foundation/FoundationType/Basement[Conditioned='false'].

Element	Type	Units	Constraints	Required	Default	Notes
WithinInfiltrationVolume	boolean			Yes		In accordance with ANSI/RESNET/ICC Standard 380

If the dwelling unit has an unvented crawlspace, whether it is within the infiltration volume is entered in Enclosure/Foundations/Foundation/FoundationType/Crawlspace[Vented='false'].

Element	Type	Units	Constraints	Required	Default	Notes
WithinInfiltrationVolume	boolean			Yes		In accordance with ANSI/RESNET/ICC Standard 380

If the dwelling unit has a vented crawlspace, crawlspace ventilation information can be optionally entered in /HPXML/Building/BuildingDetails/Enclosure/Foundations/Foundation[FoundationType/Crawlspace[Vented="true"]]/VentilationRate.

Element	Type	Units	Constraints	Required	Default	Notes
UnitofMeasure	string		See [11]	No	SLA	Units for ventilation rate
Value	double		> 0	No	1/150	Value for ventilation rate

[11]	UnitofMeasure only choice is “SLA” (specific leakage area).

HPXML Roofs

Each pitched or flat roof surface that is exposed to ambient conditions is entered as an /HPXML/Building/BuildingDetails/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.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
InteriorAdjacentTo	string		See [12]	Yes		Interior adjacent space type
Area	double	ft2	> 0	Yes		Gross area (including skylights)
Azimuth	integer	deg	0 - 359	No	See [13]	Azimuth (clockwise from North)
SolarAbsorptance	double		0 - 1	Yes		Solar absorptance
Emittance	double		0 - 1	Yes		Emittance
Pitch	integer	?:12	>= 0	Yes		Pitch
RadiantBarrier	boolean			Yes		Presence of radiant barrier
RadiantBarrier/RadiantBarrierGrade	integer		1 - 3	See [14]		Radiant barrier installation grade
Insulation/SystemIdentifier	id			Yes		Unique identifier
Insulation/AssemblyEffectiveRValue	double	F-ft2-hr/Btu	> 0	Yes		Assembly R-value [15]

[12]	InteriorAdjacentTo choices are “attic - vented”, “attic - unvented”, “living space”, or “garage”. See HPXML Locations for descriptions.

[13]	If Azimuth not provided, modeled as four surfaces of equal area facing every direction.

[14]	RadiantBarrierGrade only required if RadiantBarrier is provided.

[15]	AssemblyEffectiveRValue includes all material layers, interior/exterior air films, and insulation installation grade.

HPXML Rim Joists

Each rim joist surface (i.e., the perimeter of floor joists typically found between stories of a building or on top of a foundation wall) is entered as an /HPXML/Building/BuildingDetails/Enclosure/RimJoists/RimJoist.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
ExteriorAdjacentTo	string		See [16]	Yes		Exterior adjacent space type
InteriorAdjacentTo	string		See [17]	Yes		Interior adjacent space type
Area	double	ft2	> 0	Yes		Gross area
Azimuth	integer	deg	0 - 359	No	See [18]	Azimuth (clockwise from North)
SolarAbsorptance	double		0 - 1	Yes		Solar absorptance
Emittance	double		0 - 1	Yes		Emittance
Insulation/SystemIdentifier	id			Yes		Unique identifier
Insulation/AssemblyEffectiveRValue	double	F-ft2-hr/Btu	> 0	Yes		Assembly R-value [19]

[16]

ExteriorAdjacentTo choices are “outside”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.

[17]	InteriorAdjacentTo choices are “living space”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, or “garage”. See HPXML Locations for descriptions.

[18]	If Azimuth not provided, modeled as four surfaces of equal area facing every direction.

[19]	AssemblyEffectiveRValue includes all material layers, interior/exterior air films, and insulation installation grade.

HPXML Walls

Each wall that has no contact with the ground and bounds a space type is entered as an /HPXML/Building/BuildingDetails/Enclosure/Walls/Wall.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
ExteriorAdjacentTo	string		See [20]	Yes		Exterior adjacent space type
InteriorAdjacentTo	string		See [21]	Yes		Interior adjacent space type
WallType	element		1 [22]	Yes		Wall type (for thermal mass)
Area	double	ft2	> 0	Yes		Gross area (including doors/windows)
Azimuth	integer	deg	0 - 359	No	See [23]	Azimuth (clockwise from North)
SolarAbsorptance	double		0 - 1	Yes		Solar absorptance
Emittance	double		0 - 1	Yes		Emittance
Insulation/SystemIdentifier	id			Yes		Unique identifier
Insulation/AssemblyEffectiveRValue	double	F-ft2-hr/Btu	> 0	Yes		Assembly R-value [24]

[20]

ExteriorAdjacentTo choices are “outside”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.

[21]	InteriorAdjacentTo choices are “living space”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, or “garage”. See HPXML Locations for descriptions.

[22]	WallType child element choices are WoodStud, DoubleWoodStud, ConcreteMasonryUnit, StructurallyInsulatedPanel, InsulatedConcreteForms, SteelFrame, SolidConcrete, StructuralBrick, StrawBale, Stone, LogWall, or Adobe.

[23]	If Azimuth not provided, modeled as four surfaces of equal area facing every direction.

[24]	AssemblyEffectiveRValue includes all material layers, interior/exterior air films, and insulation installation grade.

HPXML Foundation Walls

Each wall that is in contact with the ground should be specified as an /HPXML/Building/BuildingDetails/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 a Wall and not a FoundationWall.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
ExteriorAdjacentTo	string		See [25]	Yes		Exterior adjacent space type [26]
InteriorAdjacentTo	string		See [27]	Yes		Interior adjacent space type
Height	double	ft	> 0	Yes		Total height
Area	double	ft2	> 0	Yes		Gross area (including doors/windows)
Azimuth	integer	deg	0 - 359	No	See [28]	Azimuth (clockwise from North)
Thickness	double	inches	> 0	Yes		Thickness excluding interior framing
DepthBelowGrade	double	ft	0 - Height	Yes		Depth below grade [29]
Insulation/SystemIdentifier	id			Yes		Unique identifier
Insulation/Layer[InstallationType="continuous - interior"]	element		0 - 1	See [30]		Interior insulation layer
Insulation/Layer[InstallationType="continuous - exterior"]	element		0 - 1	See [31]		Exterior insulation layer
Insulation/AssemblyEffectiveRValue	double	F-ft2-hr/Btu	> 0	See [32]		Assembly R-value [33]

[25]	ExteriorAdjacentTo choices are “ground”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.

[26]	InteriorAdjacentTo choices are “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, or “garage”. See HPXML Locations for descriptions.

[27]	Interior foundation walls (e.g., between basement and crawlspace) should not use “ground” even if the foundation wall has some contact with the ground due to the difference in below-grade depths of the two adjacent spaces.

[28]	If Azimuth not provided, modeled as four surfaces of equal area facing every direction.

[29]

For exterior foundation walls, depth below grade is relative to the ground plane. For interior foundation walls, depth below grade is the vertical span 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.

[30]	Layer[InstallationType=”continuous - interior”] only required if AssemblyEffectiveRValue is not provided.

[31]	Layer[InstallationType=”continuous - exterior”] only required if AssemblyEffectiveRValue is not provided.

[32]	AssemblyEffectiveRValue only required if Layer elements are not provided.

[33]	AssemblyEffectiveRValue includes all material layers, interior air film, and insulation installation grade. R-value should not include exterior air film (for any above-grade exposure) or any soil thermal resistance.

If insulation layers are provided, additional information is entered in each FoundationWall/Insulation/Layer.

Element	Type	Units	Constraints	Required	Default	Notes
NominalRValue	double	F-ft2-hr/Btu	>= 0	Yes		R-value of the foundation wall insulation; use zero if no insulation
extension/DistanceToTopOfInsulation	double	ft	>= 0	Yes		Vertical distance from top of foundation wall to top of insulation
extension/DistanceToBottomOfInsulation	double	ft	DistanceToTopOfInsulation - Height	Yes		Vertical distance from top of foundation wall to bottom of insulation

HPXML Frame Floors

Each horizontal floor/ceiling surface that is not in contact with the ground (Slab) nor adjacent to ambient conditions above (Roof) is entered as an /HPXML/Building/BuildingDetails/Enclosure/FrameFloors/FrameFloor.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
ExteriorAdjacentTo	string		See [34]	Yes		Exterior adjacent space type
InteriorAdjacentTo	string		See [35]	Yes		Interior adjacent space type
Area	double	ft2	> 0	Yes		Gross area
Insulation/SystemIdentifier	id			Yes		Unique identifier
Insulation/AssemblyEffectiveRValue	double	F-ft2-hr/Btu	> 0	Yes		Assembly R-value [36]

[34]

ExteriorAdjacentTo choices are “outside”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.

[35]	InteriorAdjacentTo choices are “living space”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, or “garage”. See HPXML Locations for descriptions.

[36]	AssemblyEffectiveRValue includes all material layers, interior/exterior air films, and insulation installation grade.

For frame floors adjacent to “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”, additional information is entered in FrameFloor.

Element	Type	Units	Constraints	Required	Default	Notes
extension/OtherSpaceAboveOrBelow	string		See [37]	Yes		Specifies if above/below the MF space type

[37]	OtherSpaceAboveOrBelow choices are “above” or “below”.

HPXML Slabs

Each space type that borders the ground (i.e., basements, crawlspaces, garages, and slab-on-grade foundations) should have a slab entered as an /HPXML/Building/BuildingDetails/Enclosure/Slabs/Slab.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
InteriorAdjacentTo	string		See [38]	Yes		Interior adjacent space type
Area	double	ft2	> 0	Yes		Gross area
Thickness	double	inches	>= 0	Yes		Thickness [39]
ExposedPerimeter	double	ft	> 0	Yes		Perimeter exposed to ambient conditions [40]
PerimeterInsulationDepth	double	ft	>= 0	Yes		Depth from grade to bottom of vertical insulation
UnderSlabInsulationWidth	double	ft	>= 0	See [41]		Width from slab edge inward of horizontal insulation
UnderSlabInsulationSpansEntireSlab	boolean			See [42]		Whether horizontal insulation spans entire slab
DepthBelowGrade	double	ft	>= 0	See [43]		Depth from the top of the slab surface to grade
PerimeterInsulation/SystemIdentifier	id			Yes		Unique identifier
PerimeterInsulation/Layer/NominalRValue	double	F-ft2-hr/Btu	>= 0	Yes		R-value of vertical insulation
UnderSlabInsulation/SystemIdentifier	id			Yes		Unique identifier
UnderSlabInsulation/Layer/NominalRValue	double	F-ft2-hr/Btu	>= 0	Yes		R-value of horizontal insulation
extension/CarpetFraction	double	frac	0 - 1	Yes		Fraction of slab covered by carpet
extension/CarpetRValue	double	F-ft2-hr/Btu	>= 0	Yes		Carpet R-value

[38]	InteriorAdjacentTo choices are “living space”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, or “garage”. See HPXML Locations for descriptions.

[39]	For a crawlspace with a dirt floor, enter a thickness of zero.

[40]	ExposedPerimeter includes 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.

[41]	UnderSlabInsulationWidth only required if UnderSlabInsulationSpansEntireSlab=true is not provided.

[42]	UnderSlabInsulationSpansEntireSlab=true only required if UnderSlabInsulationWidth is not provided.

[43]	DepthBelowGrade only required if the attached foundation has no FoundationWalls. For foundation types with walls, the the slab’s position relative to grade is determined by the FoundationWall/DepthBelowGrade value.

HPXML Windows

Each window or glass door area is entered as an /HPXML/Building/BuildingDetails/Enclosure/Windows/Window.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
Area	double	ft2	> 0	Yes		Total area
Azimuth	integer	deg	0 - 359	Yes		Azimuth (clockwise from North)
UFactor	double	Btu/F-ft2-hr	> 0	Yes		Full-assembly NFRC U-factor
SHGC	double		0 - 1	Yes		Full-assembly NFRC solar heat gain coefficient
Overhangs	element		0 - 1	No	<none>	Presence of overhangs (including roof eaves)
FractionOperable	double	frac	0 - 1	Yes		Operable fraction [44]
AttachedToWall	idref		See [45]	Yes		ID of attached wall

[44]

FractionOperable reflects 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).

[45]	AttachedToWall must reference a Wall or FoundationWall.

If overhangs are specified, additional information is entered in Overhangs.

Element	Type	Units	Constraints	Required	Default	Notes
Depth	double	inches	>= 0	Yes		Depth of overhang
DistanceToTopOfWindow	double	ft	>= 0	Yes		Vertical distance from overhang to top of window
DistanceToBottomOfWindow	double	ft	> DistanceToTopOfWindow	Yes		Vertical distance from overhang to bottom of window [46]

[46]	The difference between DistanceToBottomOfWindow and DistanceToTopOfWindow defines the height of the window.

HPXML Skylights

Each skylight is entered as an /HPXML/Building/BuildingDetails/Enclosure/Skylights/Skylight.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
Area	double	ft2	> 0	Yes		Total area
Azimuth	integer	deg	0 - 359	Yes		Azimuth (clockwise from North)
UFactor	double	Btu/F-ft2-hr	> 0	Yes		Full-assembly NFRC U-factor
SHGC	double		0 - 1	Yes		Full-assembly NFRC solar heat gain coefficient
AttachedToRoof	idref		See [47]	Yes		ID of attached roof

[47]	AttachedToRoof must reference a Roof.

HPXML Doors

Each opaque door is entered as an /HPXML/Building/BuildingDetails/Enclosure/Doors/Door.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
AttachedToWall	idref		See [48]	Yes		ID of attached wall
Area	double	ft2	> 0	Yes		Total area
Azimuth	integer	deg	0 - 359	Yes		Azimuth (clockwise from North)
RValue	double	F-ft2-hr/Btu	> 0	Yes		R-value

[48]	AttachedToWall must reference a Wall or FoundationWall.

HPXML Systems

The dwelling unit’s systems are entered in /HPXML/Building/BuildingDetails/Systems.

HPXML Heating Systems

Each heating system (other than a heat pump) is entered as an /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
HeatingSystemType	element		1 [49]	Yes		Type of heating system
FractionHeatLoadServed	double	frac	0 - 1 [50]	Yes		Fraction of heating load served
HeatingSystemFuel	string		See [51]	Yes		Fuel type
HeatingCapacity	double	Btu/hr	>= 0	See [52]		Input heating capacity

[49]	HeatingSystemType child element choices are ElectricResistance, Furnace, WallFurnace, FloorFurnace, Boiler, Stove, PortableHeater, FixedHeater, or Fireplace.

[50]	The sum of all FractionHeatLoadServed (across both HeatingSystems and HeatPumps) must be less than or equal to 1.

[51]	HeatingSystemFuel choices are “natural gas”, “fuel oil”, “propane”, “electricity”, “wood”, or “wood pellets”. For ElectricResistance, “electricity” is required.

[52]	HeatingCapacity required for all systems other than shared boilers.

Electric Resistance

If electric resistance heating is specified, additional information is entered in HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
AnnualHeatingEfficiency[Units="Percent"]/Value	double	frac	0 - 1	Yes		Efficiency

Furnace

If a furnace is specified, additional information is entered in HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
DistributionSystem	idref		See [53]	Yes		ID of attached distribution system
AnnualHeatingEfficiency[Units="AFUE"]/Value	double	frac	0 - 1	Yes		Rated efficiency
extension/FanPowerWattsPerCFM or extension/FanPowerNotTested=true	double or boolean	W/cfm	>= 0	Yes		In accordance with ANSI/RESNET/ACCA 310 [54]
extension/AirflowDefectRatio or extension/AirflowNotTested=true	double or boolean	frac	> -1	Yes		In accordance with ANSI/RESNET/ACCA 310

[53]	HVACDistribution type must be AirDistribution or DSE.

[54]	If there is a cooling system attached to the DistributionSystem, the heating and cooling systems cannot have different values for FanPowerWattsPerCFM.

Wall/Floor Furnace

If a wall furnace or floor furnace is specified, additional information is entered in HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
AnnualHeatingEfficiency[Units="AFUE"]/Value	double	frac	0 - 1	Yes		Rated efficiency
extension/FanPowerWatts	double	W	>= 0	No	0	Fan power

Boiler

If a boiler is specified, additional information is entered in HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units
DistributionSystem	idref		See [55]	Yes		ID of attached distribution system
AnnualHeatingEfficiency[Units="AFUE"]/Value	double	frac	0 - 1	Yes		Rated efficiency
ElectricAuxiliaryEnergy	double	kWh/yr	>= 0	No [56]	See [57]	Electric auxiliary energy

[55]

For in-unit boilers, HVACDistribution type must be HydronicDistribution (type: “radiator”, “baseboard”, “radiant floor”, “radiant ceiling”, or “water loop”) or DSE. For shared boilers, HVACDistribution type must be HydronicDistribution (type: “radiator”, “baseboard”, “radiant floor”, “radiant ceiling”, or “water loop”) or AirDistribution (type: “fan coil”).

[56]

For shared boilers, ElectricAuxiliaryEnergy can alternatively be calculated as: EAE = (SP / N_dweq + aux_in) * HLH where SP = Shared pump power [W] provided as extension/SharedLoopWatts, N_dweq = Number of units served by the shared system provided as NumberofUnitsServed, aux_in = In-unit fan coil power [W] provided as extension/FanCoilWatts, HLH = Annual heating load hours.

[57]	If ElectricAuxiliaryEnergy not provided (nor calculated for shared boilers), defaults as follows: Oil boiler: 330 Gas boiler (in-unit): 170 Gas boiler (shared, w/ baseboard): 220 Gas boiler (shared, w/ water loop heat pump): 265 Gas boiler (shared, w/ fan coil): 438

Stove

If a stove is specified, additional information is entered in HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
AnnualHeatingEfficiency[Units="Percent"]/Value	double	frac	0 - 1	Yes		Efficiency
extension/FanPowerWatts	double	W	>= 0	No	40	Fan power

Portable/Fixed Heater

If a portable heater or fixed heater is specified, additional information is entered in HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
AnnualHeatingEfficiency[Units="Percent"]/Value	double	frac	0 - 1	Yes		Efficiency
extension/FanPowerWatts	double	W	>= 0	No	0	Fan power

Fireplace

If a fireplace is specified, additional information is entered in HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
AnnualHeatingEfficiency[Units="Percent"]/Value	double	frac	0 - 1	Yes		Efficiency
extension/FanPowerWatts	double	W	>= 0	No	0	Fan power

HPXML Cooling Systems

Each cooling system (other than a heat pump) is entered as an /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/CoolingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
CoolingSystemType	string		See [58]	Yes		Type of cooling system
CoolingSystemFuel	string		See [59]	Yes		Fuel type
FractionCoolLoadServed	double	frac	0 - 1 [60]	Yes		Fraction of cooling load served

[58]	CoolingSystemType choices are “central air conditioner”, “room air conditioner”, “evaporative cooler”, “mini-split”, “chiller”, or “cooling tower”.

[59]	CoolingSystemFuel only choice is “electricity”.

[60]	The sum of all FractionCoolLoadServed (across both CoolingSystems and HeatPumps) must be less than or equal to 1.

Central Air Conditioner

If a central air conditioner is specified, additional information is entered in CoolingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
DistributionSystem	idref		See [61]	Yes		ID of attached distribution system
AnnualCoolingEfficiency[Units="SEER"]/Value	double	Btu/Wh	> 0	Yes		Rated efficiency
CoolingCapacity	double	Btu/hr	>= 0	Yes		Cooling capacity
SensibleHeatFraction	double	frac	0 - 1	No		Sensible heat fraction
CompressorType	string		See [62]	No	See [63]	Type of compressor
extension/FanPowerWattsPerCFM or extension/FanPowerNotTested=true	double or boolean	W/cfm	>= 0	Yes		In accordance with ANSI/RESNET/ACCA 310 [64]
extension/AirflowDefectRatio or extension/AirflowNotTested=true	double or boolean	frac	> -1	Yes		In accordance with ANSI/RESNET/ACCA 310
extension/ChargeDefectRatio or extension/ChargeNotTested=true	double or boolean	frac	-0.25, 0, 0.25	Yes		In accordance with ANSI/RESNET/ACCA 310

[61]	HVACDistribution type must be AirDistribution or DSE.

[62]	CompressorType choices are “single stage”, “two stage”, or “variable speed”.

[63]	If CompressorType not provided, defaults to “single stage” if SEER <= 15, else “two stage” if SEER <= 21, else “variable speed”.

[64]	If there is a heating system attached to the DistributionSystem, the heating and cooling systems cannot have different values for FanPowerWattsPerCFM.

Room Air Conditioner

If a room air conditioner is specified, additional information is entered in CoolingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
AnnualCoolingEfficiency[Units="EER"]/Value	double	Btu/Wh	> 0	Yes		Rated efficiency
CoolingCapacity	double	Btu/hr	>= 0	Yes		Cooling capacity
SensibleHeatFraction	double	frac	0 - 1	No		Sensible heat fraction

Evaporative Cooler

If an evaporative cooler is specified, additional information is entered in CoolingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
DistributionSystem	idref		See [65]	No		ID of attached distribution system
CoolingCapacity	double	Btu/hr	>= 0	No	autosized	Cooling capacity

[65]	If provided, HVACDistribution type must be AirDistribution or DSE.

Mini-Split

If a mini-split is specified, additional information is entered in CoolingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
DistributionSystem	idref		See [66]	No		ID of attached distribution system
AnnualCoolingEfficiency[Units="SEER"]/Value	double	Btu/Wh	> 0	Yes		Rated cooling efficiency
CoolingCapacity	double	Btu/hr	>= 0	Yes		Cooling capacity
SensibleHeatFraction	double	frac	0 - 1	No		Sensible heat fraction
extension/ChargeDefectRatio or extension/ChargeNotTested=true	double or boolean	frac	-0.25, 0, 0.25	Yes		In accordance with ANSI/RESNET/ACCA 310

[66]	HVACDistribution type must be AirDistribution or DSE.

If a ducted mini-split is specified (i.e., a DistributionSystem has been entered), additional information is entered in CoolingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
extension/FanPowerWattsPerCFM or extension/FanPowerNotTested=true	double or boolean	W/cfm	>= 0	Yes		In accordance with ANSI/RESNET/ACCA 310
extension/AirflowDefectRatio or extension/AirflowNotTested=true	double or boolean	frac	> -1	Yes		In accordance with ANSI/RESNET/ACCA 310

Chiller

If a chiller is specified, additional information is entered in CoolingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
IsSharedSystem	boolean		true	Yes		Whether it serves multiple dwelling units
DistributionSystem	idref		See [67]	Yes		ID of attached distribution system
NumberofUnitsServed	integer		> 1	Yes		Number of dwelling units served
CoolingCapacity	double	Btu/hr	>= 0	Yes		Total cooling capacity
AnnualCoolingEfficiency[Units="kW/ton"]/Value	double	kW/ton	> 0	Yes		Rated efficiency
extension/SharedLoopWatts	double	W	>= 0	Yes		Pumping and fan power serving the system
extension/FanCoilWatts	double	W	>= 0	See [68]		Fan coil power

[67]	HVACDistribution type must be HydronicDistribution (type: “radiator”, “baseboard”, “radiant floor”, or “radiant ceiling”) or HydronicAndAirDistribution (type: “fan coil” or “water loop heat pump”).

[68]	FanCoilWatts only required if chiller connected to a fan coil.

Cooling Tower

If a cooling tower is specified, additional information is entered in CoolingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
IsSharedSystem	boolean		true	Yes		Whether it serves multiple dwelling units
DistributionSystem	idref		See [69]	Yes		ID of attached distribution system
NumberofUnitsServed	integer		> 1	Yes		Number of dwelling units served
extension/SharedLoopWatts	double	W	>= 0	Yes		Pumping and fan power serving the system

[69]	HVACDistribution type must be HydronicDistribution (type: “water loop”).

HPXML Heat Pumps

Each heat pump is entered as an /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatPump.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
HeatPumpType	string		See [70]	Yes		Type of heat pump
HeatPumpFuel	string		See [71]	Yes		Fuel type
BackupSystemFuel	string		See [72]	No		Fuel type of backup heating, if present

[70]	HeatPumpType choices are “air-to-air”, “mini-split”, “ground-to-air”, or “water-loop-to-air”.

[71]	HeatPumpFuel only choice is “electricity”.

[72]	BackupSystemFuel choices are “electricity”, “natural gas”, “fuel oil”, “propane”, “wood”, or “wood pellets”.

If a backup system fuel is provided, additional information is entered in HeatPump.

Element	Type	Units	Constraints	Required	Default	Notes
BackupAnnualHeatingEfficiency[Units="Percent" or Units="AFUE"]/Value	double	frac	0 - 1	Yes		Backup heating efficiency
BackupHeatingCapacity	double	Btu/hr	>= 0	Yes		Backup heating capacity
BackupHeatingSwitchoverTemperature	double	F		No	<none>	Backup heating switchover temperature [73]

[73]

Provide BackupHeatingSwitchoverTemperature for, e.g., a dual-fuel heat pump, in which there is a discrete outdoor temperature when the heat pump stops operating and the backup heating system starts operating. If not provided, the backup heating system will operate as needed when the heat pump has insufficient capacity.

Air-to-Air Heat Pump

If an air-to-air heat pump is specified, additional information is entered in HeatPump.

Element	Type	Units	Constraints	Required	Default	Notes
DistributionSystem	idref		See [74]	Yes		ID of attached distribution system
CompressorType	string		See [75]	No	See [76]	Type of compressor
HeatingCapacity	double	Btu/hr	>= 0	Yes		Heating capacity (excluding any backup heating)
HeatingCapacity17F	double	Btu/hr	>= 0	No		Heating capacity at 17F, if available
CoolingCapacity	double	Btu/hr	>= 0	Yes		Cooling capacity
CoolingSensibleHeatFraction	double	frac	0 - 1	No		Sensible heat fraction
FractionHeatLoadServed	double	frac	0 - 1 [77]	Yes		Fraction of heating load served
FractionCoolLoadServed	double	frac	0 - 1 [78]	Yes		Fraction of cooling load served
AnnualCoolingEfficiency[Units="SEER"]/Value	double	Btu/Wh	> 0	Yes		Rated cooling efficiency
AnnualHeatingEfficiency[Units="HSPF"]/Value	double	Btu/Wh	> 0	Yes		Rated heating efficiency
extension/FanPowerWattsPerCFM or extension/FanPowerNotTested=true	double or boolean	W/cfm	>= 0	Yes		In accordance with ANSI/RESNET/ACCA 310
extension/AirflowDefectRatio or extension/AirflowNotTested=true	double or boolean	frac	> -1	Yes		In accordance with ANSI/RESNET/ACCA 310
extension/ChargeDefectRatio or extension/ChargeNotTested=true	double or boolean	frac	-0.25, 0, 0.25	Yes		In accordance with ANSI/RESNET/ACCA 310

[74]	HVACDistribution type must be AirDistribution or DSE.

[75]	CompressorType choices are “single stage”, “two stage”, or “variable speed”.

[76]	If CompressorType not provided, defaults to “single stage” if SEER <= 15, else “two stage” if SEER <= 21, else “variable speed”.

[77]	The sum of all FractionHeatLoadServed (across both HeatingSystems and HeatPumps) must be less than or equal to 1.

[78]	The sum of all FractionCoolLoadServed (across both CoolingSystems and HeatPumps) must be less than or equal to 1.

Mini-Split Heat Pump

If a mini-split heat pump is specified, additional information is entered in HeatPump.

Element	Type	Units	Constraints	Required	Default	Notes
DistributionSystem	idref		See [79]	No		ID of attached distribution system, if present
HeatingCapacity	double	Btu/hr	>= 0	Yes		Heating capacity (excluding any backup heating)
HeatingCapacity17F	double	Btu/hr	>= 0	No		Heating capacity at 17F, if available
CoolingCapacity	double	Btu/hr	>= 0	Yes		Cooling capacity
CoolingSensibleHeatFraction	double	frac	0 - 1	No		Sensible heat fraction
FractionHeatLoadServed	double	frac	0 - 1 [80]	Yes		Fraction of heating load served
FractionCoolLoadServed	double	frac	0 - 1 [81]	Yes		Fraction of cooling load served
AnnualCoolingEfficiency[Units="SEER"]/Value	double	Btu/Wh	> 0	Yes		Rated cooling efficiency
AnnualHeatingEfficiency[Units="HSPF"]/Value	double	Btu/Wh	> 0	Yes		Rated heating efficiency
extension/ChargeDefectRatio or extension/ChargeNotTested=true	double or boolean	frac	-0.25, 0, 0.25	Yes		In accordance with ANSI/RESNET/ACCA 310

[79]	If provided, HVACDistribution type must be AirDistribution or DSE.

[80]	The sum of all FractionHeatLoadServed (across both HeatingSystems and HeatPumps) must be less than or equal to 1.

[81]	The sum of all FractionCoolLoadServed (across both CoolingSystems and HeatPumps) must be less than or equal to 1.

If a ducted mini-split is specified (i.e., a DistributionSystem has been entered), additional information is entered in HeatPump.

Element	Type	Units	Constraints	Required	Default	Notes
extension/FanPowerWattsPerCFM or extension/FanPowerNotTested=true	double or boolean	W/cfm	>= 0	Yes		In accordance with ANSI/RESNET/ACCA 310
extension/AirflowDefectRatio or extension/AirflowNotTested=true	double or boolean	frac	> -1	Yes		In accordance with ANSI/RESNET/ACCA 310

Ground-to-Air Heat Pump

If a ground-to-air heat pump is specified, additional information is entered in HeatPump.

Element	Type	Units	Constraints	Required	Default	Notes
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units [82]
DistributionSystem	idref		See [83]	Yes		ID of attached distribution system
HeatingCapacity	double	Btu/hr	>= 0	Yes		Heating capacity (excluding any backup heating)
CoolingCapacity	double	Btu/hr	>= 0	Yes		Cooling capacity
CoolingSensibleHeatFraction	double	frac	0 - 1	No		Sensible heat fraction
FractionHeatLoadServed	double	frac	0 - 1 [84]	Yes		Fraction of heating load served
FractionCoolLoadServed	double	frac	0 - 1 [85]	Yes		Fraction of cooling load served
AnnualCoolingEfficiency[Units="EER"]/Value	double	Btu/Wh	> 0	Yes		Rated cooling efficiency
AnnualHeatingEfficiency[Units="COP"]/Value	double	W/W	> 0	Yes		Rated heating efficiency
NumberofUnitsServed	integer		> 0	See [86]		Number of dwelling units served
extension/PumpPowerWattsPerTon	double	W/ton	>= 0	Yes		Pump efficiency [87]
extension/FanPowerWattsPerCFM or extension/FanPowerNotTested=true	double or boolean	W/cfm	>= 0	Yes		In accordance with ANSI/RESNET/ACCA 310
extension/SharedLoopWatts	double	W	>= 0	See [88]		Shared pump power [89]
extension/AirflowDefectRatio or extension/AirflowNotTested=true	double or boolean	frac	> -1	Yes		In accordance with ANSI/RESNET/ACCA 310
extension/ChargeDefectRatio	double or boolean	frac	0 [90]	Yes		In accordance with ANSI/RESNET/ACCA 310

[82]	IsSharedSystem should be true if the SFA/MF building has multiple ground source heat pumps connected to a shared hydronic circulation loop.

[83]	HVACDistribution type must be AirDistribution or DSE.

[84]	The sum of all FractionHeatLoadServed (across both HeatingSystems and HeatPumps) must be less than or equal to 1.

[85]	The sum of all FractionCoolLoadServed (across both CoolingSystems and HeatPumps) must be less than or equal to 1.

[86]	NumberofUnitsServed only required if IsSharedSystem is true, in which case it must be > 1.

[87]	Pump power is calculated using PumpPowerWattsPerTon and the cooling capacity in tons, unless the system only provides heating, in which case the heating capacity in tons is used instead.

[88]	SharedLoopWatts only required if IsSharedSystem is true.

[89]	Shared loop pump power attributed to the dwelling unit is calculated as SharedLoopWatts / NumberofUnitsServed.

[90]	ChargeDefectRatio currently constrained to zero for ground-to-air heat pumps due to an EnergyPlus limitation; this constraint will be relaxed in the future. Likewise ChargeNotTested is not currently supported because it results in Grade 3 refrigerant charge, which is a non-zero charge defect ratio.

Water-Loop-to-Air Heat Pump

If a water-loop-to-air heat pump is specified, additional information is entered in HeatPump.

Element	Type	Units	Constraints	Required	Default	Notes
DistributionSystem	idref		See [91]	Yes		ID of attached distribution system
HeatingCapacity	double	Btu/hr	> 0	See [92]		Heating capacity
CoolingCapacity	double	Btu/hr	> 0	See [93]		Cooling capacity
AnnualCoolingEfficiency[Units="EER"]/Value	double	Btu/Wh	> 0	See [94]		Rated cooling efficiency
AnnualHeatingEfficiency[Units="COP"]/Value	double	W/W	> 0	See [95]		Rated heating efficiency

[91]	HVACDistribution type must be AirDistribution or DSE.

[92]	HeatingCapacity required if there is a shared boiler with water loop distribution.

[93]	CoolingCapacity required if there is a shared chiller or cooling tower with water loop distribution.

[94]	AnnualCoolingEfficiency required if there is a shared chiller or cooling tower with water loop distribution.

[95]	AnnualHeatingEfficiency required if there is a shared boiler with water loop distribution.

Note

If a water loop heat pump is specified, there must be at least one shared heating system (i.e., boiler) and/or one shared cooling system (i.e., chiller or cooling tower) specified with water loop distribution.

HPXML HVAC Control

If any HVAC systems are specified, a single thermostat is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACControl.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
ControlType	string		See [96]	Yes		Type of thermostat

[96]	ControlType choices are “manual thermostat” or “programmable thermostat”.

HPXML HVAC Distribution

Each separate HVAC distribution system is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACDistribution.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
DistributionSystemType	element		1 [97]	Yes		Type of distribution system
ConditionedFloorAreaServed	double	ft2	> 0	See [98]		Conditioned floor area served

[97]	DistributionSystemType child element choices are AirDistribution, HydronicDistribution, or Other=DSE.

[98]	ConditionedFloorAreaServed is required for AirDistribution type.

Note

There should be at most one heating system and one cooling system attached to a distribution system. See HPXML Heating Systems, HPXML Cooling Systems, and HPXML 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.

Air Distribution

To define an air distribution system, the presence of duct leakage must be entered in one of three ways:

1. Leakage to the Outside

Supply and return leakage to the outside are each entered as a HVACDistribution/DistributionSystemType/AirDistribution/DuctLeakageMeasurement:

Element	Type	Units	Constraints	Required	Default	Notes
DuctType	string		See [99]	Yes		Supply or return ducts
DuctLeakage/Units	string		CFM25	Yes		Duct leakage units
DuctLeakage/Value	double		>= 0	Yes		Duct leakage value [100]
DuctLeakage/TotalOrToOutside	string		to outside	Yes		Type of duct leakage (outside conditioned space vs total)

[99]	DuctType choices are “supply” or “return”.

[100]

If the HVAC system has no return ducts (e.g., a ducted evaporative cooler), use zero for the Value.

2. Total leakage (Version 2014ADEGL or newer)

Total leakage is entered as a HVACDistribution/DistributionSystemType/AirDistribution/DuctLeakageMeasurement:

Element	Type	Units	Constraints	Required	Default	Notes
DuctLeakage/Units	string		CFM25	Yes		Duct leakage units
DuctLeakage/Value	double		>= 0	Yes		Duct leakage value
DuctLeakage/TotalOrToOutside	string		total	Yes		Type of duct leakage (outside conditioned space vs total)

Warning

Total leakage should only be used if the conditions specified in ANSI/RESNET/ICC 301 have been appropriately met.

3. Leakage Testing Exemption (Version 2014AD or newer)

   A duct leakage testing exemption is entered in HVACDistribution/DistributionSystemType/AirDistribution:

Element	Type	Units	Constraints	Required	Default	Notes
extension/DuctLeakageToOutsideTestingExemption=true	boolean		true	Yes		Leakage to outside exemption?

Warning

Leakage testing exemption should only be used if the conditions specified in ANSI/RESNET/ICC 301 have been appropriately met. OpenStudio-ERI does not assess the validity of the duct test exemption claim.

Additionally, each supply/return duct present is entered in a HVACDistribution/DistributionSystemType/AirDistribution/Ducts.

Element	Type	Units	Constraints	Required	Default	Notes
DuctType	string		See [101]	Yes		Supply or return ducts
DuctInsulationRValue	double	F-ft2-hr/Btu	>= 0	Yes		R-value of duct insulation [102]
DuctSurfaceArea	double	ft2	>= 0	Yes		Duct surface area
DuctLocation	string		See [103]	Yes		Duct location

[101]

DuctType choices are “supply” or “return”.

[102]

DuctInsulationRValue should not include air films (i.e., use 0 for an uninsulated duct).

[103]

DuctLocation choices are “living space”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - unvented”, “crawlspace - vented”, “attic - unvented”, “attic - vented”, “garage”, “outside”, “exterior wall”, “under slab”, “roof deck”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.

Hydronic Distribution

To define a hydronic distribution system, additional information is entered in HVACDistribution/DistributionSystemType/HydronicDistribution.

Element	Type	Units	Constraints	Required	Default	Notes
HydronicDistributionType	string		See [104]	Yes		Type of hydronic distribution system

[104]

HydronicDistributionType choices are “radiator”, “baseboard”, “radiant floor”, or “radiant ceiling”.

Distribution System Efficiency (DSE)

Warning

A simplified DSE model is provided for flexibility, but it is strongly recommended to use one of the other detailed distribution system types for better accuracy.

To define a DSE system, additional information is entered in HVACDistribution.

Element	Type	Units	Constraints	Required	Default	Notes
AnnualHeatingDistributionSystemEfficiency	double	frac	0 - 1	Yes		Seasonal distribution system efficiency for heating
AnnualCoolingDistributionSystemEfficiency	double	frac	0 - 1	Yes		Seasonal distribution system efficiency for cooling

DSE values can be calculated from ASHRAE Standard 152.

HPXML Ventilation Fan

Each mechanical ventilation system that provides ventilation to the whole dwelling unit is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
UsedForWholeBuildingVentilation	boolean		true	Yes		Must be set to true
IsSharedSystem	boolean		See [105]	Yes		Whether it serves multiple dwelling units
FanType	string		See [106]	Yes		Type of ventilation system
TestedFlowRate or RatedFlowRate	double	cfm	>= 0	Yes		Flow rate [107]
HoursInOperation	double	hrs/day	0 - 24	Yes		Hours per day of operation
FanPower or extension/FanPowerDefaulted=true	double or boolean	W	>= 0 or true	See [108]		Fan power or whether fan power is unknown

[105]

For central fan integrated supply systems, IsSharedSystem must be false.

[106]

FanType choices are “energy recovery ventilator”, “heat recovery ventilator”, “exhaust only”, “supply only”, “balanced”, or “central fan integrated supply”.

[107]

For a central fan integrated supply system, the flow rate should equal the amount of outdoor air provided to the distribution system.

[108]

FanPower or FanPowerDefaulted=true required if IsSharedSystem is false.

Exhaust/Supply Only

If a supply only or exhaust only system is specified, no additional information is entered.

Balanced

If a balanced system is specified, no additional information is entered.

Heat Recovery Ventilator

If a heat recovery ventilator system is specified, additional information is entered in VentilationFan.

Element	Type	Units	Constraints	Required	Default	Notes
SensibleRecoveryEfficiency or AdjustedSensibleRecoveryEfficiency	double	frac	0 - 1	Yes		(Adjusted) Sensible recovery efficiency

Energy Recovery Ventilator

If an energy recovery ventilator system is specified, additional information is entered in VentilationFan.

Element	Type	Units	Constraints	Required	Default	Notes
TotalRecoveryEfficiency or AdjustedTotalRecoveryEfficiency	double	frac	0 - 1	Yes		(Adjusted) Total recovery efficiency
SensibleRecoveryEfficiency or AdjustedSensibleRecoveryEfficiency	double	frac	0 - 1	Yes		(Adjusted) Sensible recovery efficiency

Central Fan Integrated Supply

If a central fan integrated supply system is specified, additional information is entered in VentilationFan.

Element	Type	Units	Constraints	Required	Default	Notes
AttachedToHVACDistributionSystem	idref		See [109]	Yes		ID of attached distribution system

[109]

HVACDistribution type cannot be HydronicDistribution.

Shared System

If the specified system is a shared system (i.e., serving multiple dwelling units), additional information is entered in VentilationFan.

Element	Type	Units	Constraints	Required	Default	Notes
RatedFlowRate	double	cfm	>= 0	Yes		Total flow rate of shared system
FractionRecirculation	double	frac	0 - 1	Yes		Fraction of supply air that is recirculated [110]
extension/InUnitFlowRate or extension/FlowRateNotTested=true	double or boolean	cfm	>= 0 [111] or true	Yes		Flow rate delivered to the dwelling unit or whether flow rate not measured
extension/PreHeating	element		0 - 1	No	<none>	Supply air preconditioned by heating equipment? [112]
extension/PreCooling	element		0 - 1	No	<none>	Supply air preconditioned by cooling equipment? [113]

[110]

1-FractionRecirculation is assumed to be the fraction of supply air that is provided from outside. The value must be 0 for exhaust only systems.

[111]

InUnitFlowRate must also be > RatedFlowRate.

[112]

PreHeating not allowed for exhaust only systems.

[113]

PreCooling not allowed for exhaust only systems.

If pre-heating is specified, additional information is entered in extension/PreHeating.

Element	Type	Units	Constraints	Required	Default	Notes
Fuel	string		See [114]	Yes		Pre-heating equipment fuel type
AnnualHeatingEfficiency[Units="COP"]/Value	double	W/W	> 0	Yes		Pre-heating equipment annual COP
FractionVentilationHeatLoadServed	double	frac	0 - 1	Yes		Fraction of ventilation heating load served by pre-heating equipment

[114]

Fuel choices are “natural gas”, “fuel oil”, “propane”, “electricity”, “wood”, or “wood pellets”.

If pre-cooling is specified, additional information is entered in extension/PreCooling.

Element	Type	Units	Constraints	Required	Default	Notes
Fuel	string		See [115]	Yes		Pre-cooling equipment fuel type
AnnualCoolingEfficiency[Units="COP"]/Value	double	W/W	> 0	Yes		Pre-cooling equipment annual COP
FractionVentilationCoolLoadServed	double	frac	0 - 1	Yes		Fraction of ventilation cooling load served by pre-cooling equipment

[115]

Fuel only choice is “electricity”.

HPXML Whole House Fan

Each whole house fan that provides cooling load reduction is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
UsedForSeasonalCoolingLoadReduction	boolean		true	Yes		Must be set to true
RatedFlowRate	double	cfm	>= 0	Yes		Flow rate
FanPower	double	W	>= 0	Yes		Fan power

Note

The whole house fan is assumed to operate during hours of favorable outdoor conditions and will take priority over operable windows (natural ventilation).

HPXML Water Heating Systems

Each water heater is entered as a /HPXML/Building/BuildingDetails/Systems/WaterHeating/WaterHeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units or shared laundry room
WaterHeaterType	string		See [116]	Yes		Type of water heater
Location	string		See [117]	Yes		Water heater location
FractionDHWLoadServed	double	frac	0 - 1 [118]	Yes		Fraction of hot water load served [119]
UsesDesuperheater	boolean			No	false	Presence of desuperheater?
NumberofUnitsServed	integer		> 0	See [120]		Number of dwelling units served directly or indirectly

[116]

WaterHeaterType choices are “storage water heater”, “instantaneous water heater”, “heat pump water heater”, “space-heating boiler with storage tank”, or “space-heating boiler with tankless coil”.

[117]

Location choices are “living space”, “basement - unconditioned”, “basement - conditioned”, “attic - unvented”, “attic - vented”, “garage”, “crawlspace - unvented”, “crawlspace - vented”, “other exterior”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.

[118]

The sum of all FractionDHWLoadServed (across all WaterHeatingSystems) must equal to 1.

[119]

FractionDHWLoadServed represents only the fraction of the hot water load associated with the hot water fixtures. Additional hot water load from clothes washers/dishwashers will be automatically assigned to the appropriate water heater(s).

[120]

NumberofUnitsServed only required if IsSharedSystem is true, in which case it must be > 1.

Conventional Storage

If a conventional storage water heater is specified, additional information is entered in WaterHeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
FuelType	string		See [121]	Yes		Fuel type
TankVolume	double	gal	> 0	Yes		Tank volume
HeatingCapacity	double	Btuh	> 0	No	See [122]	Heating capacity
UniformEnergyFactor or EnergyFactor	double	frac	< 1	Yes		EnergyGuide label rated efficiency
FirstHourRating	double	gal/hr	> 0	See [123]		EnergyGuide label first hour rating
RecoveryEfficiency	double	frac	0 - 1	See [124]		Recovery efficiency
WaterHeaterInsulation/Jacket/JacketRValue	double	F-ft2-hr/Btu	>= 0	No	0	R-value of additional tank insulation wrap

[121]

FuelType choices are “natural gas”, “fuel oil”, “propane”, “electricity”, “wood”, or “wood pellets”.

[122]

If HeatingCapacity not provided, defaults based on Table 8 in the 2014 BAHSP.

[123]

FirstHourRating only required if UniformEnergyFactor provided.

[124]

RecoveryEfficiency only required if FuelType is not electricity.

Tankless

If an instantaneous tankless water heater is specified, additional information is entered in WaterHeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
FuelType	string		See [125]	Yes		Fuel type
UniformEnergyFactor or EnergyFactor	double	frac	< 1	Yes		EnergyGuide label rated efficiency

[125]

FuelType choices are “natural gas”, “fuel oil”, “propane”, “electricity”, “wood”, or “wood pellets”.

Heat Pump

If a heat pump water heater is specified, additional information is entered in WaterHeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
FuelType	string		See [126]	Yes		Fuel type
TankVolume	double	gal	> 0	Yes		Tank volume
UniformEnergyFactor or EnergyFactor	double	frac	> 1	Yes		EnergyGuide label rated efficiency
FirstHourRating	double	gal/hr	> 0	See [127]		EnergyGuide label first hour rating
WaterHeaterInsulation/Jacket/JacketRValue	double	F-ft2-hr/Btu	>= 0	No	0	R-value of additional tank insulation wrap

[126]

FuelType only choice is “electricity”.

[127]

FirstHourRating only required if UniformEnergyFactor provided.

Combi Boiler w/ Storage

If a combination boiler w/ storage tank (sometimes referred to as an indirect water heater) is specified, additional information is entered in WaterHeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
RelatedHVACSystem	idref		See [128]	Yes		ID of boiler
TankVolume	double	gal	> 0	Yes		Volume of the storage tank
WaterHeaterInsulation/Jacket/JacketRValue	double	F-ft2-hr/Btu	>= 0	No	0	R-value of additional storage tank insulation wrap
StandbyLoss	double	F/hr	> 0	No	See [129]	Storage tank standby losses

[128]

RelatedHVACSystem must reference a HeatingSystem of type Boiler.

[129]

If StandbyLoss not provided, defaults based on a regression analysis of AHRI Directory of Certified Product Performance.

Combi Boiler w/ Tankless Coil

If a combination boiler w/ tankless coil is specified, additional information is entered in WaterHeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
RelatedHVACSystem	idref		See [130]	Yes		ID of boiler

[130]

RelatedHVACSystem must reference a HeatingSystem (Boiler).

Desuperheater

If the water heater uses a desuperheater, additional information is entered in WaterHeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
RelatedHVACSystem	idref		See [131]	Yes		ID of heat pump or air conditioner

[131]

RelatedHVACSystem must reference a HeatPump (air-to-air, mini-split, or ground-to-air) or CoolingSystem (central air conditioner).

HPXML Hot Water Distribution

If any water heating systems are provided, a single hot water distribution system is entered as a /HPXML/Building/BuildingDetails/Systems/WaterHeating/HotWaterDistribution.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
SystemType	element		1 [132]	Yes		Type of in-unit distribution system serving the dwelling unit
PipeInsulation/PipeRValue	double	F-ft2-hr/Btu	>= 0	Yes		Pipe insulation R-value
DrainWaterHeatRecovery	element		0 - 1	No	<none>	Presence of drain water heat recovery device
extension/SharedRecirculation	element		0 - 1 [133]	No	<none>	Presence of shared recirculation system serving multiple dwelling units

[132]

SystemType child element choices are Standard and Recirculation.

[133]

If SharedRecirculation is provided, SystemType must be Standard. This is because a stacked recirculation system (i.e., shared recirculation loop plus an additional in-unit recirculation system) is more likely to indicate input errors than reflect an actual real-world scenario.

Note

In attached/multifamily buildings, only the hot water distribution system serving the dwelling unit should be defined. The hot water distribution associated with, e.g., a shared laundry room should not be defined.

Standard

If the in-unit distribution system is specified as standard, additional information is entered in SystemType/Standard.

Element	Type	Units	Constraints	Required	Default	Notes
PipingLength	double	ft	> 0	Yes		Length of piping [134]

[134]

PipingLength is the length of hot water piping from the hot water heater (or from a shared recirculation loop serving multiple dwelling units) 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).

Recirculation

If the in-unit distribution system is specified as recirculation, additional information is entered in SystemType/Recirculation.

Element	Type	Units	Constraints	Required	Default	Notes
ControlType	string		See [135]	Yes		Recirculation control type
RecirculationPipingLoopLength	double	ft	> 0	Yes		Recirculation piping loop length [136]
BranchPipingLoopLength	double	ft	> 0	Yes		Branch piping loop length [137]
PumpPower	double	W	>= 0	Yes		Recirculation pump power

[135]

ControlType choices are “manual demand control”, “presence sensor demand control”, “temperature”, “timer”, or “no control”.

[136]

RecirculationPipingLoopLength is the 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.

[137]

BranchPipingLoopLength is the 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.

Shared Recirculation

If a shared recirculation system is specified, additional information is entered in extension/SharedRecirculation.

Element	Type	Units	Constraints	Required	Default	Notes
NumberofUnitsServed	integer		> 1	Yes		Number of dwelling units served
PumpPower	double	W	>= 0	No	220	Shared recirculation pump power
ControlType	string		See [138]	Yes		Shared recirculation control type

[138]

ControlType choices are “manual demand control”, “presence sensor demand control”, “timer”, or “no control”.

Drain Water Heat Recovery

If a drain water heat recovery (DWHR) device is specified, additional information is entered in DrainWaterHeatRecovery.

Element	Type	Units	Constraints	Required	Default	Notes
FacilitiesConnected	string		See [139]	Yes		Specifies which facilities are connected
EqualFlow	boolean			Yes		Specifies how the DHWR is configured [140]
Efficiency	double	frac	0 - 1	Yes		Efficiency according to CSA 55.1

[139]

FacilitiesConnected choices are “one” or “all”. Use “one” if there are multiple showers and only one of them is connected to the DWHR. Use “all” if there is one shower and it’s connected to the DWHR or there are two or more showers connected to the DWHR.

[140]

EqualFlow should be true if the DWHR supplies pre-heated water to both the fixture cold water piping and the hot water heater potable supply piping.

HPXML Water Fixtures

Each water fixture is entered as a /HPXML/Building/BuildingDetails/Systems/WaterHeating/WaterFixture.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
WaterFixtureType	string		See [141]	Yes		Type of water fixture
LowFlow	boolean			Yes		Whether the fixture is considered low-flow [142]

[141]

WaterFixtureType choices are “shower head” or “faucet”.

[142]

LowFlow should be true if the fixture’s flow rate (gpm) is <= 2.0.

HPXML Solar Thermal

A single solar hot water system can be entered as a /HPXML/Building/BuildingDetails/Systems/SolarThermal/SolarThermalSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
SystemType	string		See [143]	Yes		Type of solar thermal system

[143]

SystemType only choice is “hot water”.

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

Simple Inputs

To define a simple solar hot water system, additional information is entered in SolarThermalSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SolarFraction	double	frac	0 - 1	Yes		Solar fraction [144]
ConnectedTo	idref		See [145]	No [146]	<none>	Connected water heater

[144]

Portion of total conventional hot water heating load (delivered energy plus 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.

[145]

ConnectedTo must reference a WaterHeatingSystem. The referenced water heater cannot be a space-heating boiler nor attached to a desuperheater.

[146]

If ConnectedTo not provided, solar fraction will apply to all water heaters in the building.

Detailed Inputs

To define a detailed solar hot water system, additional information is entered in SolarThermalSystem.

Element	Type	Units	Constraints	Required	Default	Notes
CollectorArea	double	ft2	> 0	Yes		Area
CollectorLoopType	string		See [147]	Yes		Loop type
CollectorType	string		See [148]	Yes		System type
CollectorAzimuth	integer	deg	0 - 359	Yes		Azimuth (clockwise from North)
CollectorTilt	double	deg	0 - 90	Yes		Tilt relative to horizontal
CollectorRatedOpticalEfficiency	double	frac	0 - 1	Yes		Rated optical efficiency [149]
CollectorRatedThermalLosses	double	Btu/hr-ft2-R	> 0	Yes		Rated thermal losses [150]
StorageVolume	double	gal	> 0	Yes		Hot water storage volume
ConnectedTo	idref		See [151]	Yes		Connected water heater

[147]

CollectorLoopType choices are “liquid indirect”, “liquid direct”, or “passive thermosyphon”.

[148]

CollectorType choices are “single glazing black”, “double glazing black”, “evacuated tube”, or “integrated collector storage”.

[149]

CollectorRatedOpticalEfficiency is FRTA (y-intercept) from the Directory of SRCC OG-100 Certified Solar Collector Ratings.

[150]

CollectorRatedThermalLosses is FRUL (slope) from the Directory of SRCC OG-100 Certified Solar Collector Ratings.

[151]

ConnectedTo must reference a WaterHeatingSystem that is not of type space-heating boiler nor connected to a desuperheater.

HPXML Photovoltaics

Each solar electric photovoltaic (PV) system is entered as a /HPXML/Building/BuildingDetails/Systems/Photovoltaics/PVSystem.

Many of the inputs are adopted from the PVWatts model.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units
Location	string		See [152]	Yes		Mounting location
ModuleType	string		See [153]	Yes		Type of module
Tracking	string		See [154]	Yes		Type of tracking
ArrayAzimuth	integer	deg	0 - 359	Yes		Direction panels face (clockwise from North)
ArrayTilt	double	deg	0 - 90	Yes		Tilt relative to horizontal
MaxPowerOutput	double	W	>= 0	Yes		Peak power
InverterEfficiency	double	frac	0 - 1	Yes		Inverter efficiency [155]
SystemLossesFraction	double	frac	0 - 1	Yes		System losses [156]
extension/NumberofBedroomsServed	integer		> 1	See [157]		Number of bedrooms served

[152]

Location choices are “ground” or “roof” mounted.

[153]

ModuleType choices are “standard”, “premium”, or “thin film”.

[154]

Tracking choices are “fixed”, “1-axis”, “1-axis backtracked”, or “2-axis”.

[155]

Default from PVWatts is 0.96.

[156]

System losses due to soiling, shading, snow, mismatch, wiring, degradation, etc. Default from PVWatts is 0.14.

[157]

NumberofBedroomsServed only required if IsSharedSystem is true, in which case it must be > NumberofBedrooms. PV generation will be apportioned to the dwelling unit using its number of bedrooms divided by the total number of bedrooms served by the PV system.

HPXML Generators

Each generator that provides on-site power is entered as a /HPXML/Building/BuildingDetails/Systems/extension/Generators/Generator.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units
FuelType	string		See [158]	Yes		Fuel type
AnnualConsumptionkBtu	double	kBtu/yr	> 0	Yes		Annual fuel consumed
AnnualOutputkWh	double	kWh/yr	> 0	Yes		Annual electricity produced
NumberofBedroomsServed	integer		> 1	See [159]		Number of bedrooms served

[158]

FuelType choices are “natural gas” or “propane”.

[159]

NumberofBedroomsServed only required if IsSharedSystem is true, in which case it must be > NumberofBedrooms. Annual consumption and annual production will be apportioned to the dwelling unit using its number of bedrooms divided by the total number of bedrooms served by the generator.

Note

Generators will be modeled as operating continuously (24/7).

HPXML Appliances

Appliances entered in /HPXML/Building/BuildingDetails/Appliances.

HPXML Clothes Washer

A single clothes washer can be entered as a /HPXML/Building/BuildingDetails/Appliances/ClothesWasher.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
IsSharedAppliance	boolean			Yes		Whether it serves multiple dwelling units [160]
Location	string		See [161]	Yes		Location
IntegratedModifiedEnergyFactor or ModifiedEnergyFactor	double	ft3/kWh/cyc	> 0	Yes		EnergyGuide label efficiency [162]
RatedAnnualkWh	double	kWh/yr	> 0	Yes		EnergyGuide label annual consumption
LabelElectricRate	double	$/kWh	> 0	Yes		EnergyGuide label electricity rate
LabelGasRate	double	$/therm	> 0	Yes		EnergyGuide label natural gas rate
LabelAnnualGasCost	double	$	> 0	Yes		EnergyGuide label annual gas cost
LabelUsage	double	cyc/wk	> 0	Yes		EnergyGuide label number of cycles
Capacity	double	ft3	> 0	Yes		Clothes dryer volume

[160]

For example, a clothes washer in a shared laundry room of a MF building.

[161]

Location choices are “living space”, “basement - conditioned”, “basement - unconditioned”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.

[162]

If ModifiedEnergyFactor (MEF) provided instead of IntegratedModifiedEnergyFactor (IMEF), it will be converted using the Interpretation on ANSI/RESNET 301-2014 Clothes Washer IMEF: IMEF = (MEF - 0.503) / 0.95.

If the clothes washer is shared, additional information is entered in /HPXML/Building/BuildingDetails/Appliances/ClothesWasher.

Element	Type	Units	Constraints	Required	Default	Notes
AttachedToWaterHeatingSystem	idref		See [163]	Yes		ID of attached water heater
NumberofUnits	integer			Yes		Number of clothes washers in the shared laundry room
NumberofUnitsServed	integer			Yes		Number of dwelling units served by the shared laundry room

[163]

AttachedToWaterHeatingSystem must reference a WaterHeatingSystem.

Note

If no clothes washer is located within the Rated Home, a clothes washer in the nearest shared laundry room on the project site shall be used if available for daily use by the occupants of the Rated Home. If there are multiple clothes washers, the clothes washer with the highest Label Energy Rating (kWh/yr) shall be used.

HPXML Clothes Dryer

A single clothes dryer can be entered as a /HPXML/Building/BuildingDetails/Appliances/ClothesDryer.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
IsSharedAppliance	boolean			Yes		Whether it serves multiple dwelling units [164]
Location	string		See [165]	Yes		Location
FuelType	string		See [166]	Yes		Fuel type
CombinedEnergyFactor or EnergyFactor	double	lb/kWh	> 0	Yes		EnergyGuide label efficiency [167]
ControlType	string		See [168]	Yes		Type of controls

[164]

For example, a clothes dryer in a shared laundry room of a MF building.

[165]

Location choices are “living space”, “basement - conditioned”, “basement - unconditioned”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.

[166]

FuelType choices are “natural gas”, “fuel oil”, “propane”, “electricity”, “wood”, or “wood pellets”.

[167]

If EnergyFactor (EF) provided instead of CombinedEnergyFactor (CEF), it will be converted using the following equation based on the Interpretation on ANSI/RESNET/ICC 301-2014 Clothes Dryer CEF: CEF = EF / 1.15.

[168]

ControlType choices are “timer” or “moisture”.

If the clothes dryer is shared, additional information is entered in /HPXML/Building/BuildingDetails/Appliances/ClothesDryer.

Element	Type	Units	Constraints	Required	Default	Notes
NumberofUnits	integer			Yes		Number of clothes dryers in the shared laundry room
NumberofUnitsServed integer				Yes		Number of dwelling units served by the shared laundry room

Note

If no clothes dryer is located within the Rated Home, a clothes dryer in the nearest shared laundry room on the project site shall be used if available for daily use by the occupants of the Rated Home. If there are multiple clothes dryers, the clothes dryer with the lowest Energy Factor or Combined Energy Factor shall be used.

HPXML Dishwasher

A single dishwasher can be entered as a /HPXML/Building/BuildingDetails/Appliances/Dishwasher.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
IsSharedAppliance	boolean			Yes		Whether it serves multiple dwelling units [169]
Location	string		See [170]	Yes		Location
RatedAnnualkWh or EnergyFactor	double	kWh/yr or #	> 0	Yes		EnergyGuide label consumption/efficiency [171]
LabelElectricRate	double	$/kWh	> 0	Yes		EnergyGuide label electricity rate
LabelGasRate	double	$/therm	> 0	Yes		EnergyGuide label natural gas rate
LabelAnnualGasCost	double	$	> 0	Yes		EnergyGuide label annual gas cost
LabelUsage	double	cyc/wk	> 0	Yes		EnergyGuide label number of cycles
PlaceSettingCapacity	integer	#	> 0	Yes		Number of place settings

[169]

For example, a dishwasher in a shared mechanical room of a MF building.

[170]

Location choices are “living space”, “basement - conditioned”, “basement - unconditioned”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.

[171]

If EnergyFactor (EF) provided instead of RatedAnnualkWh, it will be converted using the following equation based on ANSI/RESNET/ICC 301-2014: RatedAnnualkWh = 215.0 / EF.

If the dishwasher is shared, additional information is entered in /HPXML/Building/BuildingDetails/Appliances/Dishwasher.

Element	Type	Units	Constraints	Required	Default	Notes
AttachedToWaterHeatingSystem	idref		See [172]	Yes		ID of attached water heater

[172]

AttachedToWaterHeatingSystem must reference a WaterHeatingSystem.

Note

If no dishwasher is located within the Rated Home, a dishwasher in the nearest shared kitchen in the building shall be used only if available for daily use by the occupants of the Rated Home. If there are multiple dishwashers, the dishwasher with the lowest Energy Factor (highest kWh/yr) shall be used.

HPXML Refrigerators

A single refrigerator can be entered as a /HPXML/Building/BuildingDetails/Appliances/Refrigerator.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
Location	string		See [173]	Yes		Location
RatedAnnualkWh	double	kWh/yr	> 0	Yes		Annual consumption

[173]

Location choices are “living space”, “basement - conditioned”, “basement - unconditioned”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.

Note

If there are multiple refrigerators, the total energy consumption of all refrigerators/freezers shall be used along with the location that represents the majority of power consumption.

HPXML Dehumidifier

Each dehumidifier can be entered as a /HPXML/Building/BuildingDetails/Appliances/Dehumidifier.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
Type	string		See [174]	Yes		Type of dehumidifier
Location	string		See [175]	Yes		Location of dehumidifier
Capacity	double	pints/day	> 0	Yes		Dehumidification capacity
IntegratedEnergyFactor or EnergyFactor	double	liters/kWh	> 0	Yes		Rated efficiency
FractionDehumidificationLoadServed	double	frac	0 - 1 [176]	Yes		Fraction of dehumidification load served

[174]

Type choices are “portable” or “whole-home”.

[175]

Location only choice is “living space”.

[176]

The sum of all FractionDehumidificationLoadServed (across all Dehumidifiers) must be less than or equal to 1.

Note

Dehumidifiers only affect ERI scores if Version 2019AB or newer is used, as dehumidifiers were incorporated into the ERI calculation as of 301-2019 Addendum B.

Note

Dehumidifiers are currently modeled as located within conditioned space; the model is not suited for a dehumidifier in, e.g., a wet unconditioned basement or crawlspace. Therefore the dehumidifier Location is currently restricted to “living space”.

HPXML Cooking Range/Oven

A single cooking range can be entered as a /HPXML/Building/BuildingDetails/Appliances/CookingRange.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
Location	string		See [177]	Yes		Location
FuelType	string		See [178]	Yes		Fuel type
IsInduction	boolean			Yes		Induction range?

[177]

Location choices are “living space”, “basement - conditioned”, “basement - unconditioned”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.

[178]

FuelType choices are “natural gas”, “fuel oil”, “propane”, “electricity”, “wood”, or “wood pellets”.

If a cooking range is specified, a single oven is also entered as a /HPXML/Building/BuildingDetails/Appliances/Oven.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
IsConvection	boolean			Yes		Convection oven?

HPXML Lighting & Ceiling Fans

Lighting and ceiling fans are entered in /HPXML/Building/BuildingDetails/Lighting.

HPXML Lighting

Nine /HPXML/Building/BuildingDetails/Lighting/LightingGroup elements must be provided, each of which is the combination of:

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

Use LightEmittingDiode for Tier II qualifying light fixtures; use CompactFluorescent and/or FluorescentTube for Tier I qualifying light fixtures.

Information is entered in each LightingGroup.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
LightingType	element		1 [179]	Yes		Lighting type
Location	string		See [180]	Yes		See [181]
FractionofUnitsInLocation	double	frac	0 - 1 [182]	Yes		Fraction of light fixtures in the location with the specified lighting type

[179]

LightingType child element choices are LightEmittingDiode, CompactFluorescent, or FluorescentTube.

[180]

Location choices are “interior”, “garage”, or “exterior”.

[181]

Garage lighting is ignored if the building has no garage specified elsewhere.

[182]

The sum of FractionofUnitsInLocation for a given Location (e.g., interior) must be less than or equal to 1. If the fractions sum to less than 1, the remainder is assumed to be incandescent lighting.

HPXML Ceiling Fans

Each ceiling fan is entered as a /HPXML/Building/BuildingDetails/Lighting/CeilingFan.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
Airflow[FanSpeed="medium"]/Efficiency	double	cfm/W	> 0	Yes		Efficiency at medium speed
Quantity	integer		> 0	Yes		Number of similar ceiling fans

HPXML Locations

The various locations used in an HPXML file are defined as follows:

Value	Description	Temperature	Building Type
outside	Ambient environment	Weather data	Any
ground		EnergyPlus calculation	Any
living space	Above-grade conditioned floor area	EnergyPlus calculation	Any
attic - vented		EnergyPlus calculation	Any
attic - unvented		EnergyPlus calculation	Any
basement - conditioned	Below-grade conditioned floor area	EnergyPlus calculation	Any
basement - unconditioned		EnergyPlus calculation	Any
crawlspace - vented		EnergyPlus calculation	Any
crawlspace - unvented		EnergyPlus calculation	Any
garage	Single-family (not shared parking)	EnergyPlus calculation	Any
other housing unit	Unrated Conditioned Space	Same as conditioned space	SFA/MF only
other heated space	Unrated Heated Space	Avg of conditioned space/outside; min of 68F	SFA/MF only
other multifamily buffer space	Multifamily Buffer Boundary	Avg of conditioned space/outside; min of 50F	SFA/MF only
other non-freezing space	Non-Freezing Space	Floats with outside; minimum of 40F	SFA/MF only
other exterior	Water heater outside	Weather data	Any
exterior wall	Ducts in exterior wall	Avg of living space/outside	Any
under slab	Ducts under slab (ground)	EnergyPlus calculation	Any
roof deck	Ducts on roof deck (outside)	Weather data	Any

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 ERI Use Case).
2. An unexpected error occurred in the workflow (e.g., applying the ERI 301 ruleset).
3. An unexpected EnergyPlus simulation error occurred.

If, for example, the Rated Home is unsuccessful, first look in the ERIRatedHome/run.log for details. If there are no errors in that log file, then the error may be in the EnergyPlus simulation – see ERIRatedHome/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.

Workflow Outputs

Upon completion of the ERI calculation, summary output files and simulation files are available. See the sample_results directory for examples of these outputs.

Summary Files

Several summary files described below are found in the results directory.

ERI_Results.csv

The ERI_Results.csv file includes the ERI result as well as the high-level components (e.g., REUL, EC_r, EC_x, IAD_Save) that comprise the ERI calculation. The file reflects the format of the Results tab of the HERS Method Test spreadsheet.

Note that multiple comma-separated values will be reported for many of these outputs if there are multiple heating, cooling, or hot water systems.

See the example ERI_Results.csv.

ERI_Worksheet.csv

The ERI_Worksheet.csv file includes more detailed components that feed into the ERI_Results.csv values. The file reflects the format of the Worksheet tab of the HERS Method Test spreadsheet.

Note that multiple comma-separated values will be reported for many of these outputs if there are multiple heating, cooling, or hot water systems.

See the example ERI_Worksheet.csv.

ERI______Home.csv

A CSV file is written for each of the homes simulated (e.g., ERIReferenceHome.csv for the Reference home). The CSV file includes the following sections of output.

See the example ERIRatedHome.csv.

Annual Energy Consumption by Fuel Type

Current fuel types are:

Type	Notes
Electricity: Total (MBtu)
Electricity: Net (MBtu)	Subtracts any power produced by PV or generators.
Natural Gas: Total (MBtu)
Fuel Oil: Total (MBtu)
Propane: Total (MBtu)
Wood: Total (MBtu)	Currently unused for ERI.
Wood Pellets: Total (MBtu)	Currently unused for ERI.

Annual Energy Consumption By Fuel Type and End Use

Current end use/fuel type combinations are:

Type	Notes
Electricity: Heating (MBtu)
Electricity: Heating Fans/Pumps (MBtu)
Electricity: Cooling (MBtu)
Electricity: Cooling Fans/Pumps (MBtu)
Electricity: Hot Water (MBtu)
Electricity: Hot Water Recirc Pump (MBtu)
Electricity: Hot Water Solar Thermal Pump (MBtu)
Electricity: Lighting Interior (MBtu)
Electricity: Lighting Garage (MBtu)
Electricity: Lighting Exterior (MBtu)
Electricity: Mech Vent (MBtu)
Electricity: Mech Vent Preheating (MBtu)	Shared ventilation preconditioning system
Electricity: Mech Vent Precooling (MBtu)	Shared ventilation preconditioning system
Electricity: Whole House Fan (MBtu)
Electricity: Refrigerator (MBtu)
Electricity: Dehumidifier (MBtu)
Electricity: Dishwasher (MBtu)
Electricity: Clothes Washer (MBtu)
Electricity: Clothes Dryer (MBtu)
Electricity: Range/Oven (MBtu)
Electricity: Ceiling Fan (MBtu)
Electricity: Television (MBtu)
Electricity: Plug Loads (MBtu)
Electricity: PV (MBtu)	Negative value for any power produced
Electricity: Generator (MBtu)	Negative value for power produced
Natural Gas: Heating (MBtu)
Natural Gas: Hot Water (MBtu)
Natural Gas: Clothes Dryer (MBtu)
Natural Gas: Range/Oven (MBtu)
Natural Gas: Mech Vent Preheating (MBtu)	Shared ventilation preconditioning system
Natural Gas: Generator (MBtu)	Positive value for any fuel consumed
Fuel Oil: Heating (MBtu)
Fuel Oil: Hot Water (MBtu)
Fuel Oil: Clothes Dryer (MBtu)
Fuel Oil: Range/Oven (MBtu)
Fuel Oil: Mech Vent Preheating (MBtu)	Shared ventilation preconditioning system
Propane: Heating (MBtu)
Propane: Hot Water (MBtu)
Propane: Clothes Dryer (MBtu)
Propane: Range/Oven (MBtu)
Propane: Mech Vent Preheating (MBtu)	Shared ventilation preconditioning system
Propane: Generator (MBtu)	Positive value for any fuel consumed
Wood Cord: Heating (MBtu)
Wood Cord: Hot Water (MBtu)
Wood Cord: Clothes Dryer (MBtu)
Wood Cord: Range/Oven (MBtu)
Wood Cord: Mech Vent Preheating (MBtu)	Shared ventilation preconditioning system
Wood Pellets: Heating (MBtu)
Wood Pellets: Hot Water (MBtu)
Wood Pellets: Clothes Dryer (MBtu)
Wood Pellets: Range/Oven (MBtu)
Wood Pellets: Mech Vent Preheating (MBtu)	Shared ventilation preconditioning system

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)

ERI______Home_Hourly.csv

See the Running section for requesting hourly outputs. When requested, a CSV file of hourly outputs is written for the Reference/Rated Homes (e.g., ERIReferenceHome_Hourly.csv for the Reference home).

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, cooling, and hot water loads (in kBtu) for the building.
Component Loads	Heating and cooling loads (in kBtu) disaggregated by component (e.g., Walls, Windows, Infiltration, Ducts, etc.).
Unmet Loads	Unmet heating and cooling loads (in kBtu) for the building.
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.

Timestamps in the output use the end-of-hour convention. Most outputs will be summed over the hour (e.g., energy) but some will be averaged over the hour (e.g., temperatures, airflows).

See the example ERIRatedHome_Hourly.csv.

ERI______Home.xml

An HPXML file is written for each of the homes simulated (e.g., ERIReferenceHome.xml for the Reference home). The file reflects the configuration of the home after applying the ERI 301 ruleset.

The file will also show HPXML default values that are applied as part of modeling this home. Defaults will be applied for a few different reasons:

1. Optional ERI inputs aren’t provided (e.g., ventilation rate for a vented attic, SHR for an air conditioner, etc.)
2. Modeling assumptions (e.g., 1 hour timestep, Jan 1 - Dec 31 run period, appliance schedules, etc.)
3. HVAC sizing calculations (e.g., autosized HVAC capacities and airflow rates, heating/cooling design loads)

Any HPXML-defaulted values will include the dataSource='software' attribute.

See the example ERIRatedHome.xml.

Simulation Files

In addition, raw EnergyPlus simulation input/output files are available for each simulation (e.g., ERIRatedHome, ERIReferenceHome, etc. directories).

Warning

It is highly discouraged for software tools to read the raw EnergyPlus output files. The EnergyPlus input/output files are made available for inspection, but the outputs for certain situations can be misleading if one does not know how the model was created. If there are additional outputs of interest that are not available in our summary output files, please send us a request.

See the example ERIRatedHome directory.

Testing Framework

A large number of tests are automatically run for every code change in the GitHub repository.

The current set of tests include:

• Successful ERI calculations for all sample files
• RESNET® ANSI/ASHRAE Standard 140-2011, Class II, Tier 1 Tests
• RESNET HERS® Reference Home auto-generation tests
• RESNET HERS Index Adjustment Design auto-generation tests
• RESNET HERS method tests
• RESNET HVAC tests
• RESNET Duct distribution system efficiency tests
• RESNET Hot water system performance tests

If you are seeking to develop RESNET Accredited Rating Software, you will need to submit your final software product to RESNET for accreditation.

Running Tests Locally

All tests can be run locally using: openstudio energy_rating_index_test.rb

Individual tests (any method in workflow/tests/energy_rating_index_test.rb that begins with “test_”) can also be run. For example: openstudio energy_rating_index_test.rb --name=test_resnet_hers_method

Test results in CSV format are created at workflow/tests/test_results. For many RESNET tests, the Excel spreadsheet test criteria are also implemented in code to automate the process of checking for test failures. All simulation/HPXML/etc. files generated from running the tests can be found inside the workflow/tests/test_files directory.

At the completion of the test, there will also be output that denotes the number of failures/errors like so:

Finished in 36.067116s, 0.0277 runs/s, 0.9704 assertions/s. 1 runs, 35 assertions, 0 failures, 0 errors, 0 skips

Software developers may find it convenient to export HPXML files with the same name as the test files included in the repository. This allows issuing the same commands above to generate test results.

Packaging

The OpenStudio-ERI workflow is cross-platform and can be used in web or desktop applications.

Web Applications

Using the OpenStudio-ERI workflow in a web application is very straightforward.

First, OpenStudio must be available. Web applications may wish to use the nrel/openstudio docker image. Alternatively, the OpenStudio installer can be executed on the web server – only the EnergyPlus and Command Line Interface (CLI) components are required.

Then grab the latest OpenStudio-ERI release.

Desktop Applications

The OpenStudio-ERI workflow can also be packaged into a third-party software installer for distribution to desktop users.

First, OpenStudio must be bundled – only the EnergyPlus and Command Line Interface (CLI) components are required. Either the OpenStudio setup file can be automatically run as part of your install, or the OpenStudio application can be installed to a local computer and its contents can be re-bundled in your installer (there are no external dependencies required). The only required OpenStudio contents are the openstudio/bin and openstudio/EnergyPlus directories.

Then grab the latest OpenStudio-ERI release.

Indices and tables

• Index
• Search Page