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 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_schema/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/ES Calculation

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

Element	Type	Units	Constraints	Required	Default	Description
Version	string		See	No		Version of 301 Standard w/ addenda

The version of the ENERGY STAR calculation is entered in /HPXML/SoftwareInfo/extension/EnergyStarCalculation.

Element	Type	Units	Constraints	Required	Default	Description
Version	string		See	No		Version of ENERGY STAR program

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 Zone

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

Element	Type	Units	Constraints	Required	Default	Notes
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 BuildingAirLeakage/UnitofMeasure HousePressure BuildingAirLeakage/AirLeakage InfiltrationVolume	id string double double double	Pa ft3	See > 0 > 0 > 0	Yes Yes See Yes Yes		Unique identifier Units for air leakage House pressure with respect to outside Value for air leakage Volume associated with infiltration measurement
InfiltrationHeight	double	ft	> 0	No	See	Height associated with infiltration measurement

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 FrameFloor 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 Yes Yes Yes Yes	See	Azimuth (clockwise from North) Solar absorptance Emittance Unique identifier Assembly R-value

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 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 Yes Yes Yes Yes	See	Azimuth (clockwise from North) Solar absorptance Emittance Unique identifier Assembly R-value

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 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 Frame 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/FrameFloors/FrameFloor.

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

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	Yes		Specifies if above/below the MF space type

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 InteriorAdjacentTo Area Thickness ExposedPerimeter DepthBelowGrade PerimeterInsulation/SystemIdentifier PerimeterInsulation/Layer/NominalRValue PerimeterInsulation/Layer/InsulationDepth UnderSlabInsulation/SystemIdentifier UnderSlabInsulation/Layer/NominalRValue UnderSlabInsulation/Layer/InsulationWidth UnderSlabInsulation/Layer/InsulationSpansEntireSlab extension/CarpetFraction extension/CarpetRValue	id string double double double double id double double id double double boolean double double	ft2 in ft ft F-ft2-hr/Btu ft F-ft2-hr/Btu ft frac F-ft2-hr/Btu	See > 0 >= 0 >= 0 >= 0 >= 0 >= 0 >= 0 >= 0 0 - 1 >= 0	Yes Yes Yes Yes Yes See Yes Yes Yes Yes Yes See See Yes Yes		Unique identifier Interior adjacent space type Gross area Thickness Perimeter exposed to ambient conditions Depth from the top of the slab surface to grade Unique identifier R-value of vertical insulation Depth from grade 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 Yes Yes	<none>	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

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

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

PTAC Heating

If a PTAC with non-heat pump (e.g., 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	No	1.0	Efficiency

Note

A cooling system of type "packaged terminal air conditioner" must be specified in /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/CoolingSystem.

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 AnnualCoolingEfficiency[Units="SEER"]/Value CoolingCapacity SensibleHeatFraction CompressorType extension/FanPowerWattsPerCFM extension/AirflowDefectRatio extension/ChargeDefectRatio	idref double double double string double double double	Btu/Wh Btu/hr frac W/cfm frac frac	See > 0 >= 0 0 - 1 See >= 0 -0.9 - 9 -0.25, 0, 0.25	Yes Yes Yes No No Yes Yes Yes	See	ID of attached distribution system Rated efficiency Cooling output capacity Sensible heat fraction Type of compressor Blower fan efficiency at maximum fan speed Deviation between design/installed airflows Deviation between design/installed 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
AnnualCoolingEfficiency[Units="EER" or Units="CEER"]/Value CoolingCapacity SensibleHeatFraction	double double double	Btu/Wh Btu/hr frac	> 0 >= 0 0 - 1	Yes Yes No		Rated efficiency Cooling output capacity Sensible heat fraction

Packaged Terminal Air Conditioner

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

Element	Type	Units	Constraints	Required	Default	Notes
AnnualCoolingEfficiency[Units="EER" or Units="CEER"]/Value CoolingCapacity SensibleHeatFraction	integer or double double double	# or Btu/Wh Btu/hr frac	> 1600 or > 0 >= 0 0 - 1	Yes Yes No		Rated cooling efficiency Cooling output capacity 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	No		ID of attached distribution system
CoolingCapacity	double	Btu/hr	>= 0	No	autosized	Cooling output capacity

Mini-Split

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

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

Note

Mini-splits do not have a CompressorType input because they are assumed to be inverter driven (variable speed).

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
IsSharedSystem DistributionSystem NumberofUnitsServed CoolingCapacity AnnualCoolingEfficiency[Units="kW/ton"]/Value extension/SharedLoopWatts	boolean idref integer double double double	Btu/hr kW/ton W	true See > 1 >= 0 > 0 >= 0	Yes Yes Yes Yes Yes Yes		Whether it serves multiple dwelling units ID of attached distribution system 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
IsSharedSystem DistributionSystem NumberofUnitsServed extension/SharedLoopWatts	boolean idref integer double	W	true See > 1 >= 0	Yes Yes Yes Yes		Whether it serves multiple dwelling units ID of attached distribution system 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

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	string double double double	frac Btu/hr F	See 0 - 1 >= 0	Yes Yes Yes No	<none>	Integrated backup heating fuel type Integrated backup heating efficiency Integrated backup heating output capacity Integrated backup heating switchover temperature

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

Note

Mini-splits do not have a CompressorType input because they are assumed to be inverter driven (variable speed).

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 CoolingCapacity CoolingSensibleHeatFraction FractionHeatLoadServed FractionCoolLoadServed AnnualCoolingEfficiency[Units="EER" or Units="CEER"]/Value AnnualHeatingEfficiency[Units="COP"]/Value	double double double double double double double	Btu/hr Btu/hr frac frac frac Btu/Wh Btu/Wh	>= 0 >= 0 0 - 1 0 - 1 0 - 1 > 0 > 0	Yes Yes No Yes Yes Yes Yes		Heating output capacity (excluding any backup heating) Cooling output capacity Sensible heat fraction Fraction of heating load served Fraction of cooling load served Rated cooling efficiency Rated heating efficiency

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 CoolingSensibleHeatFraction FractionHeatLoadServed FractionCoolLoadServed AnnualCoolingEfficiency[Units="EER"]/Value AnnualHeatingEfficiency[Units="COP"]/Value NumberofUnitsServed extension/PumpPowerWattsPerTon extension/SharedLoopWatts	boolean idref double double double double double double double integer double double	Btu/hr Btu/hr frac frac frac Btu/Wh W/W W/ton W	See >= 0 >= 0 0 - 1 0 - 1 0 - 1 > 0 > 0 > 0 >= 0 >= 0	Yes Yes Yes Yes No Yes Yes Yes Yes See Yes See		Whether it has a shared hydronic circulation loop ID of attached distribution system Heating output capacity (excluding any backup heating) Cooling output capacity 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 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.

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
DuctType DuctInsulationRValue DuctSurfaceArea DuctLocation	string double double string	F-ft2-hr/Btu ft2	See >= 0 >= 0 See	Yes Yes Yes Yes		Supply or return ducts R-value of duct insulation Duct surface area Duct location

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 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 UsedForWholeBuildingVentilation IsSharedSystem FanType HoursInOperation FanPower or extension/FanPowerDefaulted=true	id boolean boolean string double double or boolean	hrs/day W	true See See 0 - 24 >= 0 or true	Yes Yes Yes Yes Yes Yes		Unique identifier Must be set to true 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 system is specified, additional information is entered in VentilationFan.

Element	Type	Units	Constraints	Required	Default	Notes
AttachedToHVACDistributionSystem extension/VentilationOnlyModeAirflowFraction	idref double		See 0 - 1	Yes Yes		ID of attached distribution system Blower airflow rate fraction during ventilation only mode

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, 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, 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.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier UsedForSeasonalCoolingLoadReduction RatedFlowRate FanPower	id boolean double double	cfm W	true >= 0 >= 0	Yes Yes Yes Yes		Unique identifier Must be set to true 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 Tank volume
HeatingCapacity UniformEnergyFactor or EnergyFactor FirstHourRating RecoveryEfficiency	double double double double	Btu/hr frac gal/hr frac	> 0 < 1 > 0 0 - 1	No Yes See See	See	Heating output capacity EnergyGuide label rated efficiency EnergyGuide label first hour rating 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 > 0	Yes Yes Yes See		Fuel type 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 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	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 BranchPipingLoopLength 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 loop 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 Type of water fixture 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.

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

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 InverterEfficiency SystemLossesFraction extension/NumberofBedroomsServed	id boolean string string string integer double double double double integer	deg deg W frac frac	See See See 0 - 359 0 - 90 >= 0 0 - 1 0 - 1 > 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 Inverter efficiency System losses Number of bedrooms served

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 EnergyGuide label 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 dryer 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 NumberofUnits NumberofUnitsServed	idref integer integer		See	Yes Yes Yes		ID of attached water heater 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
NumberofUnits 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	idref		See	Yes		ID of attached water heater

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 "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 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

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 LightingType Location FractionofUnitsInLocation	id element string double	frac	1 See 0 - 1	Yes Yes Yes Yes		Unique identifier Lighting type See 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 Quantity	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
living 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 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.