workflow_inputs.rst

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 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_schema/HPXML.xsd. XSD Schemas are used to validate what elements/attributes/enumerations are available, data types for elements/attributes, the number/order of children elements, etc.

2. Validation using Schematron

The Schematron document for the ERI use case can be found at rulesets/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.

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 software inputs are entered in /HPXML/SoftwareInfo.

HPXML Calculations

The OpenStudio-ERI calculation(s) to be performed are entered in /HPXML/SoftwareInfo/extension.

Element	Type	Units	Constraints	Required	Default	Description
ERICalculation/Version CO2IndexCalculation/Version IECCERICalculation/Version EnergyStarCalculation/Version ZERHCalculation/Version	string string string string string		See See See See See	No No No No No	<none> <none> <none> <none> <none>	Version to perform ERI calculation Version to perform CO2e Index calculation Version to perform IECC ERI calculation Version to perform ENERGY STAR ERI calculation Version to perform DOE ZERH ERI calculation

Warning

For the IECC ERI compliance calculation, OpenStudio-ERI does not perform additional compliance checks beyond calculating the ERI. For example, it does not check the building thermal envelope (2021 IECC, Section R406.3). It is the software tool's responsibility to perform these additional steps. It does impose renewable energy limits (2021 IECC, Section R406.4), as applicable.

Warning

For the ENERGY STAR and Zero Energy Ready Home ERI calculation, OpenStudio-ERI does not perform additional compliance checks beyond comparing the ERI to the ENERGY STAR and Zero Energy Ready Home ERI Target. For example, it does not check that the home meets all ENERGY STAR and Zero Energy Ready Home Mandatory Requirements. It is the software tool's responsibility to perform these additional steps.

HPXML Building Site

Site information is entered in /HPXML/Building/Site.

Element	Type	Units	Constraints	Required	Default	Description
Address/StateCode Address/ZipCode	string string		See See	Yes Yes		State/territory where the home is located ZIP Code where the home is located

HPXML Building Summary

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

HPXML Building Fuels

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	Yes		Fuel name

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 NumberofConditionedFloors NumberofConditionedFloorsAboveGrade NumberofBedrooms ConditionedFloorArea	string double double integer double	ft2	See > 0 > 0, <= NumberofConditionedFloors > 0 > 0	Yes Yes Yes Yes Yes		Type of dwelling unit Number of conditioned floors (including a basement) Number of conditioned floors above grade (including a walkout basement) Number of bedrooms Floor area within conditioned space boundary

HPXML Weather Station

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

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

HPXML Climate Zones

One or more IECC climate zones are each entered as a /HPXML/Building/BuildingDetails/ClimateandRiskZones/ClimateZoneIECC.

Element	Type	Units	Constraints	Required	Default	Description
Year ClimateZone	integer string		See See	Yes Yes		IECC year IECC zone

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 InfiltrationVolume	id double	ft3	> 0	Yes Yes		Unique identifier Volume associated with infiltration measurement
InfiltrationHeight	double	ft	> 0	No	See	Height associated with infiltration measurement

In addition, one of the following air leakage types must also be defined:

• infil_ach_cfm
• infil_natural_ach_cfm
• infil_ela

ACH or CFM

If entering air leakage as ACH or CFM at a user-specific pressure, additional information is entered in /HPXML/Building/BuildingDetails/Enclosure/AirInfiltration/AirInfiltrationMeasurement. For example, ACH50 (ACH at 50 Pascals) is a commonly obtained value from a blower door measurement.

Element	Type	Units	Constraints	Required	Default	Notes
BuildingAirLeakage/UnitofMeasure HousePressure BuildingAirLeakage/AirLeakage	string double double	Pa	See > 0 > 0	Yes Yes Yes		Units for air leakage House pressure with respect to outside Value for air leakage

Natural ACH or CFM

If entering air leakage as natural ACH or CFM, additional information is entered in /HPXML/Building/BuildingDetails/Enclosure/AirInfiltration/AirInfiltrationMeasurement. Natural ACH or CFM represents the annual average infiltration that a building will see.

Element	Type	Units	Constraints	Required	Default	Notes
BuildingAirLeakage/UnitofMeasure BuildingAirLeakage/AirLeakage	string double		See > 0	Yes Yes		Units for air leakage Value for air leakage

Effective Leakage Area

If entering air leakage as Effective Leakage Area (ELA), additional information is entered in /HPXML/Building/BuildingDetails/Enclosure/AirInfiltration/AirInfiltrationMeasurement. Effective Leakage Area is defined as the area of a special nozzle-shaped hole (similar to the inlet of a blower door fan) that would leak the same amount of air as the building does at a pressure difference of 4 Pascals. Note that ELA is different than Equivalent Leakage Area (EqLA), which involves a sharp-edged hole at a pressure difference of 10 Pascals.

Element	Type	Units	Constraints	Required	Default	Notes
EffectiveLeakageArea	double	sq. in.	>= 0	Yes		Effective leakage area value

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 Value	string double		See > 0	No No	SLA 1/300	Units for ventilation rate Value for ventilation rate

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 Value	string double		See > 0	No No	SLA 1/150	Units for ventilation rate Value for ventilation rate

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 Floor and not a Roof.

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

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 ExteriorAdjacentTo InteriorAdjacentTo Area	id string string double	ft2	See See > 0	Yes Yes Yes Yes		Unique identifier Exterior adjacent space type Interior adjacent space type Gross area
Azimuth SolarAbsorptance Emittance Insulation/SystemIdentifier Insulation/AssemblyEffectiveRValue	integer double double id double	deg F-ft2-hr/Btu	0 - 359 0 - 1 0 - 1 > 0	No See See Yes Yes	See	Azimuth (clockwise from North) Solar absorptance Emittance Unique identifier Assembly R-value

HPXML Walls

Each wall surface is entered as an /HPXML/Building/BuildingDetails/Enclosure/Walls/Wall.

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

HPXML Foundation Walls

Each foundation wall surface is entered as an /HPXML/Building/BuildingDetails/Enclosure/FoundationWalls/FoundationWall. Any wall surface in contact with the ground is considered a foundation wall.

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

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

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

HPXML Floors

Each 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/Floors/Floor.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier ExteriorAdjacentTo InteriorAdjacentTo FloorType Area Insulation/SystemIdentifier Insulation/AssemblyEffectiveRValue	id string string element double id double	ft2 F-ft2-hr/Btu	See See 1 > 0 > 0	Yes Yes Yes Yes Yes Yes Yes		Unique identifier Exterior adjacent space type Interior adjacent space type Floor type (for thermal mass) Gross area Unique identifier Assembly R-value

For floors adjacent to "other housing unit", "other heated space", "other multifamily buffer space", or "other non-freezing space", additional information is entered in Floor.

Element	Type	Units	Constraints	Required	Default	Notes
FloorOrCeiling	string		See	Yes		Specifies whether a floor or ceiling from the perspective of the conditioned space

HPXML Slabs

Each space type that borders the ground (i.e., basement, crawlspace, garage, and slab-on-grade foundation) should have a slab entered as an /HPXML/Building/BuildingDetails/Enclosure/Slabs/Slab.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier InteriorAdjacentTo Area Thickness ExposedPerimeter	id string double double double	ft2 in ft	See > 0 >= 0 >= 0	Yes Yes Yes Yes Yes		Unique identifier Interior adjacent space type Gross area Thickness Perimeter exposed to ambient conditions
DepthBelowGrade PerimeterInsulation/SystemIdentifier PerimeterInsulation/Layer/NominalRValue PerimeterInsulation/Layer/InsulationDepth UnderSlabInsulation/SystemIdentifier UnderSlabInsulation/Layer/NominalRValue UnderSlabInsulation/Layer/InsulationWidth UnderSlabInsulation/Layer/InsulationSpansEntireSlab extension/CarpetFraction extension/CarpetRValue	double id double double id double double boolean double double	ft F-ft2-hr/Btu ft F-ft2-hr/Btu ft frac F-ft2-hr/Btu	>= 0 >= 0 >= 0 >= 0 >= 0 0 - 1 >= 0	No Yes Yes Yes Yes Yes See See Yes Yes	See	Depth from the top of the slab surface to grade Unique identifier R-value of vertical insulation Depth from top of slab to bottom of vertical insulation Unique identifier R-value of horizontal insulation Width from slab edge inward of horizontal insulation Whether horizontal insulation spans entire slab Fraction of slab covered by carpet Carpet R-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 Area Azimuth UFactor SHGC Overhangs FractionOperable PerformanceClass AttachedToWall	id double integer double double element double string idref	ft2 deg Btu/F-ft2-hr frac	> 0 0 - 359 > 0 0 - 1 0 - 1 0 - 1 See See	Yes Yes Yes Yes Yes No Yes No Yes	<none> residential	Unique identifier Total area Azimuth (clockwise from North) Full-assembly NFRC U-factor Full-assembly NFRC solar heat gain coefficient Presence of overhangs (including roof eaves) Operable fraction Performance class ID of attached wall

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

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

HPXML Skylights

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

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

HPXML Doors

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

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

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 HeatingSystemType HeatingSystemFuel HeatingCapacity FractionHeatLoadServed	id element string double double	Btu/hr frac	1 See >= 0 0 - 1	Yes Yes Yes Yes Yes		Unique identifier Type of heating system Fuel type Heating output capacity Fraction of heating load served

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 AnnualHeatingEfficiency[Units="AFUE"]/Value extension/FanPowerWattsPerCFM extension/AirflowDefectRatio	idref double double double	frac W/cfm frac	See 0 - 1 >= 0 -0.9 - 9	Yes Yes Yes Yes		ID of attached distribution system Rated efficiency Blower fan efficiency at maximum fan speed Deviation between design/installed airflows

Warning

HVAC installation quality should be provided per the conditions specified in ANSI/RESNET/ACCA 310. OS-ERI does not check that, for example, the total duct leakage requirement has been met or that a Grade I/II input is appropriate per the ANSI 310 process flow; that is currently the responsibility of the software developer.

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 DistributionSystem AnnualHeatingEfficiency[Units="AFUE"]/Value	boolean idref double	frac	See 0 - 1	Yes Yes Yes		Whether it serves multiple dwelling units ID of attached distribution system Rated efficiency

Note

The choice of hydronic distribution type (radiator vs baseboard vs radiant panels) does not affect simulation results; it is currently only used to know if there's an attached water loop heat pump or not.

If an in-unit boiler if specified, additional information is entered in HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
ElectricAuxiliaryEnergy	double	kWh/yr	>= 0	No	See	Electric auxiliary energy

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

Element	Type	Units	Constraints	Required	Default	Notes
NumberofUnitsServed extension/SharedLoopWatts	integer double	W	> 1 >= 0	Yes Yes		Number of dwelling units served Shared loop power
extension/SharedLoopMotorEfficiency extension/FanCoilWatts	double double	frac W	0 - 1 >= 0	No See	0.85	Shared loop motor efficiency Fan coil power

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

Space Heater

If a space heater (portable or fixed) 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 CoolingSystemType CoolingSystemFuel FractionCoolLoadServed	id string string double	frac	See See 0 - 1	Yes Yes Yes Yes		Unique identifier Type of cooling system Fuel type Fraction of cooling load served

Central Air Conditioner

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

Element	Type	Units	Constraints	Required	Default	Notes
DistributionSystem CoolingCapacity CompressorType AnnualCoolingEfficiency[Units="SEER" or Units="SEER2"]/Value	idref double string double	Btu/hr Btu/Wh	See >= 0 See > 0	Yes Yes No Yes	See	ID of attached distribution system Cooling output capacity Type of compressor Rated efficiency
SensibleHeatFraction extension/FanPowerWattsPerCFM extension/AirflowDefectRatio extension/ChargeDefectRatio	double double double double	frac W/cfm frac frac	0 - 1 >= 0 -0.9 - 9 -0.25, 0, 0.25	No Yes Yes Yes	See	Sensible heat fraction Blower fan efficiency at maximum fan speed Deviation between design/installed airflows Deviation between design/installed refrigerant charges

Warning

HVAC installation quality should be provided per the conditions specified in ANSI/RESNET/ACCA 310. OS-ERI does not check that, for example, the total duct leakage requirement has been met or that a Grade I/II input is appropriate per the ANSI 310 process flow; that is currently the responsibility of the software developer.

Room Air Conditioner

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

Element	Type	Units	Constraints	Required	Default	Notes
CoolingCapacity AnnualCoolingEfficiency[Units="EER" or Units="CEER"]/Value	double double	Btu/hr Btu/Wh	>= 0 > 0	Yes Yes		Cooling output capacity Rated efficiency
SensibleHeatFraction IntegratedHeatingSystemFuel	double string	frac	0 - 1 See	No No	0.65 <none>	Sensible heat fraction Fuel type of integrated heater

If the room air conditioner has integrated heating, additional information is entered in CoolingSystem. Note that a room air conditioner with reverse cycle heating should be entered as a heat pump; see room_ac_reverse_cycle.

Element	Type	Units	Constraints	Required	Default	Notes
IntegratedHeatingSystemCapacity IntegratedHeatingSystemAnnualEfficiency[Units="Percent"]/Value IntegratedHeatingSystemFractionHeatLoadServed	double double double	Btu/hr frac frac	>= 0 0 - 1 0 - 1	Yes Yes Yes		Heating output capacity of integrated heater Efficiency of integrated heater Fraction of heating load served

Packaged Terminal Air Conditioner

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

Element	Type	Units	Constraints	Required	Default	Notes
CoolingCapacity AnnualCoolingEfficiency[Units="EER" or Units="CEER"]/Value	double double	Btu/hr Btu/Wh	>= 0 > 0	Yes Yes		Cooling output capacity Rated cooling efficiency
SensibleHeatFraction IntegratedHeatingSystemFuel	double string	frac	0 - 1 See	No No	0.65 <none>	Sensible heat fraction Fuel type of integrated heater

If the PTAC has integrated heating, additional information is entered in CoolingSystem. Note that a packaged terminal heat pump should be entered as a heat pump; see pthp.

Element	Type	Units	Constraints	Required	Default	Notes
IntegratedHeatingSystemCapacity IntegratedHeatingSystemAnnualEfficiency[Units="Percent"]/Value IntegratedHeatingSystemFractionHeatLoadServed	double double double	Btu/hr frac frac	>= 0 0 - 1 0 - 1	Yes Yes Yes		Heating output capacity of integrated heater Efficiency of integrated heater Fraction of heating load served

Evaporative Cooler

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

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

Mini-Split Air Conditioner

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

Element	Type	Units	Constraints	Required	Default	Notes
DistributionSystem CoolingCapacity CompressorType AnnualCoolingEfficiency[Units="SEER" or Units="SEER2"]/Value	idref double string double	Btu/hr Btu/Wh	See >= 0 See > 0	No Yes No Yes	variable speed	ID of attached distribution system Cooling output capacity Type of compressor Rated cooling efficiency
SensibleHeatFraction extension/FanPowerWattsPerCFM extension/AirflowDefectRatio extension/ChargeDefectRatio	double double double double	frac W/cfm frac frac	0 - 1 >= 0 -0.9 - 9 -0.25, 0, 0.25	No Yes Yes Yes	0.73	Sensible heat fraction Blower fan efficiency at maximum fan speed Deviation between design/installed airflows Deviation between design/installed refrigerant charges

Warning

HVAC installation quality should be provided per the conditions specified in ANSI/RESNET/ACCA 310. OS-ERI does not check that, for example, the total duct leakage requirement has been met or that a Grade I/II input is appropriate per the ANSI 310 process flow; that is currently the responsibility of the software developer.

Chiller

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

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

Cooling Tower

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

Element	Type	Units	Constraints	Required	Default	Notes
DistributionSystem IsSharedSystem NumberofUnitsServed extension/SharedLoopWatts	idref boolean integer double	W	See true > 1 >= 0	Yes Yes Yes Yes		ID of attached distribution system Whether it serves multiple dwelling units Number of dwelling units served Pumping and fan power serving the system
extension/SharedLoopMotorEfficiency	double	frac	0 - 1	No	0.85	Shared loop motor efficiency

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 HeatPumpType HeatPumpFuel BackupType	id string string string		See See See	Yes Yes Yes No	<none>	Unique identifier Type of heat pump Fuel type Type of backup heating

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 HeatingCapacity HeatingCapacity17F CoolingCapacity CompressorType CompressorLockoutTemperature	idref double double double string double	Btu/hr Btu/hr Btu/hr F	See >= 0 >= 0, <= HeatingCapacity >= 0 See	Yes Yes No Yes No No	See See	ID of attached distribution system Heating output capacity (excluding any backup heating) Heating output capacity at 17F, if available Cooling output capacity Type of compressor Minimum outdoor temperature for compressor operation
CoolingSensibleHeatFraction FractionHeatLoadServed FractionCoolLoadServed AnnualCoolingEfficiency[Units="SEER" or Units="SEER2"]/Value AnnualHeatingEfficiency[Units="HSPF" or Units="HSPF2"]/Value	double double double double double	frac frac frac Btu/Wh Btu/Wh	0 - 1 0 - 1 0 - 1 > 0 > 0	No Yes Yes Yes Yes	See	Sensible heat fraction Fraction of heating load served Fraction of cooling load served Rated cooling efficiency Rated heating efficiency
extension/HeatingCapacityRetention[Fraction | Temperature] extension/FanPowerWattsPerCFM extension/AirflowDefectRatio extension/ChargeDefectRatio	double double double double	frac | F W/cfm frac frac	>= 0, < 1 | <= 17 >= 0 -0.9 - 9 -0.25, 0, 0.25	No Yes Yes Yes	See	Heating output capacity retention at cold temperature Blower fan efficiency at maximum fan speed Deviation between design/installed airflows Deviation between design/installed refrigerant charges

Warning

HVAC installation quality should be provided per the conditions specified in ANSI/RESNET/ACCA 310. OS-ERI does not check that, for example, the total duct leakage requirement has been met or that a Grade I/II input is appropriate per the ANSI 310 process flow; that is currently the responsibility of the software developer.

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 HeatingCapacity HeatingCapacity17F CoolingCapacity CompressorType CompressorLockoutTemperature	idref double double double string double	Btu/hr Btu/hr Btu/hr F	See >= 0 >= 0, <= HeatingCapacity >= 0 See	No Yes No Yes No No	variable speed See	ID of attached distribution system, if present Heating output capacity (excluding any backup heating) Heating output capacity at 17F, if available Cooling output capacity Type of compressor Minimum outdoor temperature for compressor operation
CoolingSensibleHeatFraction FractionHeatLoadServed FractionCoolLoadServed AnnualCoolingEfficiency[Units="SEER" or Units="SEER2"]/Value AnnualHeatingEfficiency[Units="HSPF" or Units="HSPF2"]/Value	double double double double double	frac frac frac Btu/Wh Btu/Wh	0 - 1 0 - 1 0 - 1 > 0 > 0	No Yes Yes Yes Yes	0.73	Sensible heat fraction Fraction of heating load served Fraction of cooling load served Rated cooling efficiency Rated heating efficiency
extension/HeatingCapacityRetention[Fraction | Temperature] extension/FanPowerWattsPerCFM extension/AirflowDefectRatio extension/ChargeDefectRatio	double double double double	frac | F W/cfm frac frac	>= 0, < 1 | <= 17 >= 0 -0.9 - 9 -0.25, 0, 0.25	No Yes Yes Yes	See	Heating output capacity retention at cold temperature Blower fan efficiency at maximum fan speed Deviation between design/installed airflows Deviation between design/installed refrigerant charges

Warning

HVAC installation quality should be provided per the conditions specified in ANSI/RESNET/ACCA 310. OS-ERI does not check that, for example, the total duct leakage requirement has been met or that a Grade I/II input is appropriate per the ANSI 310 process flow; that is currently the responsibility of the software developer.

Packaged Terminal Heat Pump

If a packaged terminal heat pump is specified, additional information is entered in HeatPump.

Element	Type	Units	Constraints	Required	Default	Notes
HeatingCapacity HeatingCapacity17F CoolingCapacity CompressorLockoutTemperature	double double double double	Btu/hr Btu/hr Btu/hr F	>= 0 >= 0, <= HeatingCapacity >= 0	Yes No Yes No	See	Heating output capacity (excluding any backup heating) Heating output capacity at 17F, if available Cooling output capacity Minimum outdoor temperature for compressor operation
CoolingSensibleHeatFraction FractionHeatLoadServed FractionCoolLoadServed AnnualCoolingEfficiency[Units="EER" or Units="CEER"]/Value AnnualHeatingEfficiency[Units="COP"]/Value	double double double double double	frac frac frac Btu/Wh W/W	0 - 1 0 - 1 0 - 1 > 0 > 0	No Yes Yes Yes Yes	0.65	Sensible heat fraction Fraction of heating load served Fraction of cooling load served Rated cooling efficiency Rated heating efficiency
extension/HeatingCapacityRetention[Fraction | Temperature]	double	frac | F	>= 0, < 1 | <= 17	No	0.425 | 5	Heating output capacity retention at cold temperature

Room Air Conditioner w/ Reverse Cycle

If a room air conditioner with reverse cycle is specified, additional information is entered in HeatPump.

Element	Type	Units	Constraints	Required	Default	Notes
HeatingCapacity HeatingCapacity17F CoolingCapacity CompressorLockoutTemperature	double double double double	Btu/hr Btu/hr Btu/hr F	>= 0 >= 0, <= HeatingCapacity >= 0	Yes No Yes No	See	Heating output capacity (excluding any backup heating) Heating output capacity at 17F, if available Cooling output capacity Minimum outdoor temperature for compressor operation
CoolingSensibleHeatFraction FractionHeatLoadServed FractionCoolLoadServed AnnualCoolingEfficiency[Units="EER" or Units="CEER"]/Value AnnualHeatingEfficiency[Units="COP"]/Value	double double double double double	frac frac frac Btu/Wh W/W	0 - 1 0 - 1 0 - 1 > 0 > 0	No Yes Yes Yes Yes	0.65	Sensible heat fraction Fraction of heating load served Fraction of cooling load served Rated cooling efficiency Rated heating efficiency
extension/HeatingCapacityRetention[Fraction | Temperature]	double	frac | F	>= 0, < 1 | <= 17	No	0.425 | 5	Heating output capacity retention at cold temperature

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 DistributionSystem HeatingCapacity CoolingCapacity	boolean idref double double	Btu/hr Btu/hr	See >= 0 >= 0	Yes Yes Yes Yes		Whether it has a shared hydronic circulation loop ID of attached distribution system Heating output capacity (excluding any backup heating) Cooling output capacity
CoolingSensibleHeatFraction FractionHeatLoadServed FractionCoolLoadServed AnnualCoolingEfficiency[Units="EER"]/Value AnnualHeatingEfficiency[Units="COP"]/Value NumberofUnitsServed extension/PumpPowerWattsPerTon extension/SharedLoopWatts	double double double double double integer double double	frac frac frac Btu/Wh W/W W/ton W	0 - 1 0 - 1 0 - 1 > 0 > 0 > 0 >= 0 >= 0	No Yes Yes Yes Yes See Yes See	0.73	Sensible heat fraction Fraction of heating load served Fraction of cooling load served Rated cooling efficiency Rated heating efficiency Number of dwelling units served Pump power Shared pump power
extension/SharedLoopMotorEfficiency extension/FanPowerWattsPerCFM extension/AirflowDefectRatio extension/ChargeDefectRatio	double double double double	frac W/cfm frac frac	0 - 1 >= 0 -0.9 - 9 -0.25, 0, 0.25	No Yes Yes Yes	0.85	Shared loop motor efficiency Blower fan efficiency at maximum fan speed Deviation between design/installed airflows Deviation between design/installed refrigerant charges

Warning

HVAC installation quality should be provided per the conditions specified in ANSI/RESNET/ACCA 310. OS-ERI does not check that, for example, the total duct leakage requirement has been met or that a Grade I/II input is appropriate per the ANSI 310 process flow; that is currently the responsibility of the software developer.

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 HeatingCapacity CoolingCapacity AnnualCoolingEfficiency[Units="EER"]/Value AnnualHeatingEfficiency[Units="COP"]/Value	idref double double double double	Btu/hr Btu/hr Btu/Wh W/W	See > 0 > 0 > 0 > 0	Yes See See See See		ID of attached distribution system Heating output capacity Cooling output capacity Rated cooling efficiency Rated heating efficiency

Note

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

Backup

If a backup type of "integrated" is provided, additional information is entered in HeatPump.

Element	Type	Units	Constraints	Required	Default	Notes
BackupSystemFuel BackupAnnualHeatingEfficiency[Units="Percent" or Units="AFUE"]/Value BackupHeatingCapacity BackupHeatingSwitchoverTemperature or CompressorLockoutTemperature	string double double double	frac Btu/hr F	See 0 - 1 >= 0	Yes Yes Yes No	See	Integrated backup heating fuel type Integrated backup heating efficiency Integrated backup heating output capacity Minimum outdoor temperature for compressor operation
BackupHeatingSwitchoverTemperature or BackupHeatingLockoutTemperature	double	F	See	No	See	Maximum outdoor temperature for backup operation

Note

Provide BackupHeatingSwitchoverTemperature for a situation where there is a discrete outdoor temperature below which the heat pump stops operating and above which the backup heating system stops operating.

Alternatively, provide A) CompressorLockoutTemperature to specify the outdoor temperature below which the heat pump stops operating and/or B) BackupHeatingLockoutTemperature to specify the outdoor temperature above which the heat pump backup system stops operating. If both are provided, the compressor and backup system can both operate between the two temperatures (e.g., simultaneous operation or cycling). If both are provided using the same temperature, it is equivalent to using BackupHeatingSwitchoverTemperature.

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 ControlType	id string		See	Yes Yes		Unique identifier Type of 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 DistributionSystemType ConditionedFloorAreaServed	id element double	ft2	1 > 0	Yes Yes See		Unique identifier Type of distribution system Conditioned floor area served

Note

There should be at most one heating system and one cooling system attached to a distribution system. See hvac_heating, hvac_cooling, and hvac_heatpump 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, additional information is entered in HVACDistribution/DistributionSystemType/AirDistribution.

Element	Type	Units	Constraints	Required	Default	Notes
AirDistributionType NumberofReturnRegisters	string integer		See >= 0	Yes See		Type of air distribution Number of return registers

For the air distribution system, duct leakage inputs are required if AirDistributionType is "regular velocity" or "gravity" and optional if AirDistributionType is "fan coil".

When provided, supply and return leakage to the outside are each entered as a HVACDistribution/DistributionSystemType/AirDistribution/DuctLeakageMeasurement:

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

Note

ANSI/RESNET/ICC 301 allows for various duct leakage exemptions, including not testing a distribution system or measuring total duct leakage in lieu of leakage to the outside. OS-ERI does not automatically handle these exemptions. Any software tool that offers these options to their end users must incorporate the necessary logic and pass the appropriate inputs to OS-ERI (i.e., leakage to the outside or distribution system efficiency (DSE)).

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier DuctType DuctInsulationRValue DuctBuriedInsulationLevel DuctLocation DuctSurfaceArea	id string double string string double	F-ft2-hr/Btu ft2	See >= 0 See See >= 0	Yes Yes Yes No Yes Yes	not buried	Unique identifier Supply or return ducts R-value of duct insulation Duct buried insulation level Duct location Duct surface area

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	Yes		Type of hydronic distribution system

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 AnnualCoolingDistributionSystemEfficiency	double double	frac frac	0 - 1 0 - 1	Yes Yes		Seasonal distribution system efficiency for heating Seasonal distribution system efficiency for cooling

DSE values can be calculated from ASHRAE Standard 152.

HPXML Ventilation Fan

Each ventilation fan system is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier UsedForWholeBuildingVentilation or UsedForLocalVentilation or UsedForSeasonalCoolingLoadReduction or UsedForGarageVentilation	id boolean		See	Yes See		Unique identifier Ventilation fan use case

Whole 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[UsedForWholeBuildingVentilation=true].

Element	Type	Units	Constraints	Required	Default	Notes
IsSharedSystem FanType HoursInOperation FanPower or extension/FanPowerDefaulted=true	boolean string double double or boolean	hrs/day W	See See 0 - 24 >= 0 or true	Yes Yes See Yes		Whether it serves multiple dwelling units Type of ventilation system Hours per day of operation Fan power or whether fan power is unknown

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 SensibleRecoveryEfficiency or AdjustedSensibleRecoveryEfficiency	double double	frac frac	0 - 1 0 - 1	Yes Yes		(Adjusted) Total recovery efficiency (Adjusted) Sensible recovery efficiency

Central Fan Integrated Supply

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

Element	Type	Units	Constraints	Required	Default	Notes
CFISControls/AdditionalRuntimeOperatingMode CFISControls/SupplementalFan AttachedToHVACDistributionSystem extension/VentilationOnlyModeAirflowFraction	string idref idref double		See See See 0 - 1	Yes See Yes Yes		How additional ventilation is provided (beyond when the HVAC system is running) The supplemental fan providing additional ventilation ID of attached distribution system Blower airflow rate fraction during ventilation only mode

Note

CFIS systems are automated controllers that use the HVAC system's air handler fan to draw in outdoor air to meet an hourly ventilation target. CFIS systems are modeled as assuming they A) maximize the use of normal heating/cooling runtime operation to meet the hourly ventilation target, B) block the flow of outdoor air when the hourly ventilation target has been met, and C) provide additional runtime operation (via air handler fan or supplemental fan) to meet the remainder of the hourly ventilation target when space heating/cooling runtime alone is not sufficient.

In-Unit System

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

Element	Type	Units	Constraints	Required	Default	Notes
TestedFlowRate or extension/FlowRateNotTested=true	double or boolean	cfm	>= 0 or true	Yes		Flow rate or whether flow rate unmeasured

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 FractionRecirculation extension/InUnitFlowRate or extension/FlowRateNotTested=true extension/PreHeating extension/PreCooling	double double double or boolean element element	cfm frac cfm	>= 0 0 - 1 >= 0 or true 0 - 1 0 - 1	Yes Yes Yes No No	<none> <none>	Total flow rate of shared system Fraction of supply air that is recirculated Flow rate delivered to the dwelling unit or whether flow rate unmeasured Supply air preconditioned by heating equipment? Supply air preconditioned by cooling equipment?

If pre-heating is specified for the shared system, additional information is entered in extension/PreHeating.

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

If pre-cooling is specified for the shared system, additional information is entered in extension/PreCooling.

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

HPXML Whole House Fan

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

Element	Type	Units	Constraints	Required	Default	Notes
RatedFlowRate FanPower	double double	cfm W	>= 0 >= 0	Yes Yes		Flow rate 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 IsSharedSystem WaterHeaterType Location FractionDHWLoadServed UsesDesuperheater NumberofUnitsServed	id boolean string string double boolean integer	frac	See See 0 - 1 > 0	Yes Yes Yes Yes Yes No See	false	Unique identifier Whether it serves multiple dwelling units or shared laundry room Type of water heater Water heater location Fraction of hot water load served Presence of desuperheater? Number of dwelling units served directly or indirectly

Conventional Storage

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

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

Tankless

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

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

Heat Pump

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

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

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 TankVolume	idref double	gal	See > 0	Yes Yes		ID of boiler Nominal 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[Units="F/hr"]/Value	double	F/hr	> 0	No	See	Storage tank standby losses

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	Yes		ID of 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	Yes		ID of heat pump or 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 SystemType PipeInsulation/PipeRValue DrainWaterHeatRecovery extension/SharedRecirculation	id element double element element	F-ft2-hr/Btu	1 >= 0 0 - 1 0 - 1	Yes Yes Yes No No	<none> <none>	Unique identifier Type of in-unit distribution system serving the dwelling unit Pipe insulation R-value Presence of drain water heat recovery device Presence of shared recirculation system serving multiple dwelling units

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

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 RecirculationPipingLoopLength BranchPipingLength PumpPower	string double double double	ft ft W	See > 0 > 0 >= 0	Yes Yes Yes Yes		Recirculation control type Recirculation piping loop length Branch piping length Recirculation pump power

Shared Recirculation

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

Element	Type	Units	Constraints	Required	Default	Notes
NumberofUnitsServed PumpPower	integer double	W	> 1 >= 0	Yes Yes		Number of dwelling units served Shared recirculation pump power
MotorEfficiency ControlType	double string	frac	0 - 1 See	No Yes	0.85	Shared recirculation motor efficiency Shared recirculation control type

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 EqualFlow Efficiency	string boolean double	frac	See 0 - 1	Yes Yes Yes		Specifies which facilities are connected Specifies how the DHWR is configured Efficiency according to CSA 55.1

HPXML Water Fixtures

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier WaterFixtureType LowFlow	id string boolean		See	Yes Yes Yes		Unique identifier Bathroom faucet or shower Whether the fixture is considered low-flow

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 SystemType	id string		See	Yes Yes		Unique identifier Type of solar thermal system

Solar hot water systems can be described with either simple or detailed inputs. It is recommended to use detailed inputs and allow EnergyPlus to calculate the solar contribution to the hot water load; the simple inputs are provided if equivalent calculations are performed in another software tool.

Simple Inputs

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

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

Warning

The solar fraction will reduce the hot water load equally for every EnergyPlus timestep (even during nights and cloudy events).

Detailed Inputs

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

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

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 IsSharedSystem Location ModuleType Tracking ArrayAzimuth ArrayTilt MaxPowerOutput SystemLossesFraction AttachedToInverter extension/NumberofBedroomsServed	id boolean string string string integer double double double idref integer	deg deg W frac	See See See 0 - 359 0 - 90 >= 0 0 - 1 See > 1	Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes See		Unique identifier Whether it serves multiple dwelling units Mounting location Type of module Type of tracking Direction panels face (clockwise from North) Tilt relative to horizontal Peak power System losses ID of attached inverter Number of bedrooms served

In addition, an inverter must be entered as a /HPXML/Building/BuildingDetails/Systems/Photovoltaics/Inverter.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier InverterEfficiency	id double	frac	0 - 1	Yes Yes		Unique identifier Inverter efficiency

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 IsSharedSystem FuelType AnnualConsumptionkBtu AnnualOutputkWh NumberofBedroomsServed	id boolean string double double integer	kBtu/yr kWh/yr	See > 0 > 0 > 1	Yes Yes Yes Yes Yes See		Unique identifier Whether it serves multiple dwelling units Fuel type Annual fuel consumed Annual electricity produced Number of bedrooms served

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 IsSharedAppliance Location IntegratedModifiedEnergyFactor or ModifiedEnergyFactor RatedAnnualkWh LabelElectricRate LabelGasRate LabelAnnualGasCost LabelUsage Capacity	id boolean string double double double double double double double	ft3/kWh/cyc kWh/yr $/kWh $/therm $ cyc/wk ft3	See > 0 > 0 > 0 > 0 > 0 > 0 > 0	Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes		Unique identifier Whether it serves multiple dwelling units Location Efficiency EnergyGuide label annual consumption EnergyGuide label electricity rate EnergyGuide label natural gas rate EnergyGuide label annual gas cost EnergyGuide label number of cycles (not used if 301 version < 2019A) Clothes washer volume

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

Element	Type	Units	Constraints	Required	Default	Notes
AttachedToWaterHeatingSystem or AttachedToHotWaterDistribution Count NumberofUnitsServed	idref integer integer		See	Yes Yes Yes		ID of attached water heater or distribution system Number of clothes washers in the shared laundry room Number of dwelling units served by the shared laundry room

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 IsSharedAppliance Location FuelType CombinedEnergyFactor or EnergyFactor ControlType	id boolean string string double string	lb/kWh	See See > 0 See	Yes Yes Yes Yes Yes See		Unique identifier Whether it serves multiple dwelling units Location Fuel type EnergyGuide label efficiency Type of controls

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

Element	Type	Units	Constraints	Required	Default	Notes
Count NumberofUnitsServed	integer integer			Yes Yes		Number of clothes dryers in the shared laundry room 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 IsSharedAppliance Location RatedAnnualkWh or EnergyFactor LabelElectricRate LabelGasRate LabelAnnualGasCost LabelUsage PlaceSettingCapacity	id boolean string double double double double double integer	kWh/yr or # $/kWh $/therm $ cyc/wk #	See > 0 > 0 > 0 > 0 > 0 > 0	Yes Yes Yes Yes Yes Yes Yes Yes Yes		Unique identifier Whether it serves multiple dwelling units Location EnergyGuide label consumption/efficiency EnergyGuide label electricity rate (not used if 301 version < 2019A) EnergyGuide label natural gas rate (not used if 301 version < 2019A) EnergyGuide label annual gas cost (not used if 301 version < 2019A) EnergyGuide label number of cycles (not used if 301 version < 2019A) Number of place settings

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

Element	Type	Units	Constraints	Required	Default	Notes
AttachedToWaterHeatingSystem or AttachedToHotWaterDistribution	idref		See	Yes		ID of attached water heater or distribution system

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 Location RatedAnnualkWh	id string double	kWh/yr	See > 0	Yes Yes Yes		Unique identifier Location Annual consumption

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 Type Location Capacity IntegratedEnergyFactor or EnergyFactor FractionDehumidificationLoadServed	id string string double double double	pints/day liters/kWh frac	See See > 0 > 0 0 - 1	Yes Yes Yes Yes Yes Yes		Unique identifier Type of dehumidifier Location of dehumidifier Dehumidification capacity Rated efficiency Fraction of dehumidification load served

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 "conditioned 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 Location FuelType IsInduction	id string string boolean		See See	Yes Yes Yes Yes		Unique identifier Location Fuel type Induction range?

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 IsConvection	id boolean			Yes Yes		Unique identifier Convection oven?

HPXML Lighting & Ceiling Fans

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

HPXML Lighting

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

• LightingType: 'LightEmittingDiode', 'CompactFluorescent', and 'FluorescentTube'
• Location: 'interior', 'exterior', and 'garage' (garage lighting groups only required if a garage is present)

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 LightingType Location FractionofUnitsInLocation	id element string double	frac	1 See 0 - 1	Yes Yes Yes Yes		Unique identifier Lighting type Lighting location Fraction of light fixtures in the location with the specified lighting type

HPXML Ceiling Fans

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier Airflow[FanSpeed="medium"]/Efficiency Count	id double integer	cfm/W	> 0 > 0	Yes Yes Yes		Unique identifier Efficiency at medium speed 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 ground	Ambient environment	Weather data EnergyPlus calculation	Any Any
conditioned space attic - vented attic - unvented	Above-grade conditioned floor area	EnergyPlus calculation EnergyPlus calculation EnergyPlus calculation	Any Any Any
basement - conditioned basement - unconditioned crawlspace - vented crawlspace - unvented	Below-grade conditioned floor area	EnergyPlus calculation EnergyPlus calculation EnergyPlus calculation EnergyPlus calculation	Any Any Any 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 conditioned 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.