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 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:
- Validation against the HPXML Schema
The HPXML XSD Schema can be found at
hpxml-measures/HPXMLtoOpenStudio/resources/HPXML.xsd
. It should be used by the software developer to validate their HPXML file prior to running the workflow. XSD Schemas are used to validate what elements/attributes/enumerations are available, data types for elements/attributes, the number/order of children elements, etc.OpenStudio-ERI does not validate the HPXML file against the XSD Schema and assumes the file submitted is valid. However, OpenStudio-ERI does automatically check for valid data types (e.g., integer vs string), enumeration choices, and numeric values within min/max.
- 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
High-level simulation inputs are entered in /HPXML/SoftwareInfo
.
The version of the ERI calculation is entered in /HPXML/SoftwareInfo/extension/ERICalculation
.
Element Type Units Constraints Required Default Description Version
string See Yes Version of 301 Standard w/ addenda
High-level building summary information is entered in /HPXML/Building/BuildingDetails/BuildingSummary
.
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.
Building construction is entered in /HPXML/Building/BuildingDetails/BuildingSummary/BuildingConstruction
.
Element Type Units Constraints Required Default Notes
ResidentialFacilityType
NumberofConditionedFloors
NumberofConditionedFloorsAboveGrade
NumberofBedrooms
ConditionedFloorArea
ConditionedBuildingVolume
string double double integer double double
ft2 ft3 or ft
See > 0 > 0, <= NumberofConditionedFloors > 0 > 0 > 0
Yes 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 Volume within conditioned space boundary
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)
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
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.
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, >= ConditionedBuildingVolume
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
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
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
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
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
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
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
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
Height
Area
id string string double double
ft ft2
See See > 0 > 0
Yes Yes Yes Yes Yes
Unique identifier Exterior adjacent space type Interior adjacent space type 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 inches 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
extension/DistanceToTopOfInsulation
extension/DistanceToBottomOfInsulation
double double double
F-ft2-hr/Btu ft ft
>= 0 >= 0 DistanceToTopOfInsulation - Height
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
Each horizontal floor/ceiling surface that is not in contact with the ground (Slab) nor adjacent to ambient conditions above (Roof) is entered as an /HPXML/Building/BuildingDetails/Enclosure/FrameFloors/FrameFloor
.
Element Type Units Constraints Required Default Notes
SystemIdentifier
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
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
PerimeterInsulationDepth
UnderSlabInsulationWidth
UnderSlabInsulationSpansEntireSlab
DepthBelowGrade
PerimeterInsulation/SystemIdentifier
PerimeterInsulation/Layer/NominalRValue
UnderSlabInsulation/SystemIdentifier
UnderSlabInsulation/Layer/NominalRValue
extension/CarpetFraction
extension/CarpetRValue
id string double double double double double boolean double id double id double double double
ft2 inches ft ft ft
ft
F-ft2-hr/Btu
F-ft2-hr/Btu frac F-ft2-hr/Btu
See > 0 >= 0 > 0 >= 0 >= 0
>= 0
>= 0
>= 0 0 - 1 >= 0
Yes Yes Yes Yes Yes Yes See See See Yes Yes Yes Yes Yes Yes
Unique identifier Interior adjacent space type Gross area Thickness Perimeter exposed to ambient conditions Depth from grade to bottom of vertical insulation Width from slab edge inward of horizontal insulation Whether horizontal insulation spans entire slab Depth from the top of the slab surface to grade Unique identifier R-value of vertical insulation Unique identifier R-value of horizontal insulation Fraction of slab covered by carpet Carpet R-value
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
AttachedToWall
id double integer double double element double idref
ft2 deg Btu/F-ft2-hr
frac
> 0 0 - 359 > 0 0 - 1 0 - 1 0 - 1 See
Yes Yes Yes Yes Yes No 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 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
inches ft ft
>= 0 >= 0 > DistanceToTopOfWindow
Yes Yes Yes
Depth of overhang Vertical distance from overhang to top of window Vertical distance from overhang to bottom of window
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
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
The dwelling unit's systems are entered in /HPXML/Building/BuildingDetails/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
FractionHeatLoadServed
HeatingSystemFuel
HeatingCapacity
id element double string double
frac
Btu/hr
1 0 - 1 See >= 0
Yes Yes Yes Yes See
Unique identifier Type of heating system Fraction of heating load served Fuel type Input heating capacity
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
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
orextension/FanPowerNotTested=true
extension/AirflowDefectRatio
orextension/AirflowNotTested=true
idref double double or boolean double or boolean
frac W/cfm frac
See 0 - 1 >= 0 > -1
Yes Yes Yes Yes
ID of attached distribution system Rated efficiency In accordance with ANSI/RESNET/ACCA 310 In accordance with ANSI/RESNET/ACCA 310
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
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
ElectricAuxiliaryEnergy
double kWh/yr >= 0 No See Electric auxiliary energy
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
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
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
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
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
orextension/FanPowerNotTested=true
extension/AirflowDefectRatio
orextension/AirflowNotTested=true
extension/ChargeDefectRatio
orextension/ChargeNotTested=true
idref double double double string double or boolean double or boolean double or boolean
Btu/Wh Btu/hr frac
W/cfm frac frac
See > 0 >= 0 0 - 1 See >= 0 > -1 -0.25, 0, 0.25
Yes Yes Yes No No Yes Yes Yes
See
ID of attached distribution system Rated efficiency Cooling capacity Sensible heat fraction Type of compressor In accordance with ANSI/RESNET/ACCA 310 In accordance with ANSI/RESNET/ACCA 310 In accordance with ANSI/RESNET/ACCA 310
If a room air conditioner is specified, additional information is entered in CoolingSystem
.
Element Type Units Constraints Required Default Notes
AnnualCoolingEfficiency[Units="EER"]/Value
CoolingCapacity
SensibleHeatFraction
double double double
Btu/Wh Btu/hr frac
> 0 >= 0 0 - 1
Yes Yes No
Rated efficiency Cooling capacity Sensible heat fraction
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 capacity
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/ChargeDefectRatio
orextension/ChargeNotTested=true
idref double double double double or boolean
Btu/Wh Btu/hr frac frac
See > 0 >= 0 0 - 1 -0.25, 0, 0.25
No Yes Yes No Yes
ID of attached distribution system Rated cooling efficiency Cooling capacity Sensible heat fraction In accordance with ANSI/RESNET/ACCA 310
If a ducted mini-split is specified (i.e., a DistributionSystem
has been entered), additional information is entered in CoolingSystem
.
Element Type Units Constraints Required Default Notes
extension/FanPowerWattsPerCFM
orextension/FanPowerNotTested=true
extension/AirflowDefectRatio
orextension/AirflowNotTested=true
double or boolean double or boolean
W/cfm frac
>= 0 > -1
Yes Yes
In accordance with ANSI/RESNET/ACCA 310 In accordance with ANSI/RESNET/ACCA 310
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
extension/FanCoilWatts
boolean idref integer double double double double
Btu/hr kW/ton W W
true See > 1 >= 0 > 0 >= 0 >= 0
Yes Yes Yes Yes Yes Yes See
Whether it serves multiple dwelling units ID of attached distribution system Number of dwelling units served Total cooling capacity Rated efficiency Pumping and fan power serving the system Fan coil power
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
Each heat pump is entered as an /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatPump
.
Element Type Units Constraints Required Default Notes
SystemIdentifier
HeatPumpType
HeatPumpFuel
BackupSystemFuel
id string string string
See See See
Yes Yes Yes No
Unique identifier Type of heat pump Fuel type Fuel type of backup heating, if present
If a backup system fuel is provided, additional information is entered in HeatPump
.
Element Type Units Constraints Required Default Notes
BackupAnnualHeatingEfficiency[Units="Percent" or Units="AFUE"]/Value
BackupHeatingCapacity
BackupHeatingSwitchoverTemperature
double double double
frac Btu/hr F
0 - 1 >= 0
Yes Yes No
<none>
Backup heating efficiency Backup heating capacity Backup heating switchover temperature
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
orextension/FanPowerNotTested=true
extension/AirflowDefectRatio
orextension/AirflowNotTested=true
extension/ChargeDefectRatio
orextension/ChargeNotTested=true
idref string double double double double double double double double double or boolean double or boolean double or boolean
Btu/hr Btu/hr Btu/hr frac frac frac Btu/Wh Btu/Wh W/cfm frac frac
See See >= 0 >= 0 >= 0 0 - 1 0 - 1 0 - 1 > 0 > 0 >= 0 > -1 -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 capacity (excluding any backup heating) Heating capacity at 17F, if available Cooling capacity Sensible heat fraction Fraction of heating load served Fraction of cooling load served Rated cooling efficiency Rated heating efficiency In accordance with ANSI/RESNET/ACCA 310 In accordance with ANSI/RESNET/ACCA 310 In accordance with ANSI/RESNET/ACCA 310
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/ChargeDefectRatio
orextension/ChargeNotTested=true
idref double double double double double double double double double or boolean
Btu/hr Btu/hr Btu/hr frac frac frac Btu/Wh Btu/Wh frac
See >= 0 >= 0 >= 0 0 - 1 0 - 1 0 - 1 > 0 > 0 -0.25, 0, 0.25
No Yes No Yes No Yes Yes Yes Yes Yes
ID of attached distribution system, if present Heating capacity (excluding any backup heating) Heating capacity at 17F, if available Cooling capacity Sensible heat fraction Fraction of heating load served Fraction of cooling load served Rated cooling efficiency Rated heating efficiency In accordance with ANSI/RESNET/ACCA 310
If a ducted mini-split is specified (i.e., a DistributionSystem
has been entered), additional information is entered in HeatPump
.
Element Type Units Constraints Required Default Notes
extension/FanPowerWattsPerCFM
orextension/FanPowerNotTested=true
extension/AirflowDefectRatio
orextension/AirflowNotTested=true
double or boolean double or boolean
W/cfm frac
>= 0 > -1
Yes Yes
In accordance with ANSI/RESNET/ACCA 310 In accordance with ANSI/RESNET/ACCA 310
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/FanPowerWattsPerCFM
orextension/FanPowerNotTested=true
extension/SharedLoopWatts
extension/AirflowDefectRatio
orextension/AirflowNotTested=true
extension/ChargeDefectRatio
boolean idref double double double double double double double integer double double or boolean double double or boolean double or boolean
Btu/hr Btu/hr frac frac frac Btu/Wh W/W
W/ton W/cfm W frac frac
See >= 0 >= 0 0 - 1 0 - 1 0 - 1 > 0 > 0 > 0 >= 0 >= 0 >= 0 > -1 0
Yes Yes Yes Yes No Yes Yes Yes Yes See Yes Yes See Yes Yes
Whether it serves multiple dwelling units ID of attached distribution system Heating capacity (excluding any backup heating) Cooling 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 efficiency In accordance with ANSI/RESNET/ACCA 310 Shared pump power In accordance with ANSI/RESNET/ACCA 310 In accordance with ANSI/RESNET/ACCA 310
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 capacity Cooling 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., boiler) and/or one shared cooling system (i.e., chiller or cooling tower) specified with water loop distribution.
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
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.
To define an air distribution system, the presence of duct leakage must be entered in one of three ways:
- Leakage to the Outside
Supply and return leakage to the outside are each entered as a
HVACDistribution/DistributionSystemType/AirDistribution/DuctLeakageMeasurement
:
Element Type Units Constraints Required Default Notes
DuctType
DuctLeakage/Units
DuctLeakage/Value
DuctLeakage/TotalOrToOutside
string string double string
See CFM25 >= 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)
- Total leakage (Version 2014ADEGL or newer)
Total leakage is entered as a
HVACDistribution/DistributionSystemType/AirDistribution/DuctLeakageMeasurement
:
Element Type Units Constraints Required Default Notes
DuctLeakage/Units
DuctLeakage/Value
DuctLeakage/TotalOrToOutside
string double string
CFM25 >= 0 total
Yes Yes Yes
Duct leakage units Duct leakage value Type of duct leakage (outside conditioned space vs total)
Warning
Total leakage should only be used if the conditions specified in ANSI/RESNET/ICC 301 have been appropriately met.
Leakage Testing Exemption (Version 2014AD or newer)
A duct leakage testing exemption is entered in
HVACDistribution/DistributionSystemType/AirDistribution
:
Element Type Units Constraints Required Default Notes extension/DuctLeakageToOutsideTestingExemption=true
boolean true Yes Leakage to outside exemption? Warning
Leakage testing exemption should only be used if the conditions specified in ANSI/RESNET/ICC 301 have been appropriately met. OpenStudio-ERI does not assess the validity of the duct test exemption claim.
Additionally, each supply/return duct present is entered in a HVACDistribution/DistributionSystemType/AirDistribution/Ducts
.
Element Type Units Constraints Required Default Notes
DuctType
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
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
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.
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
TestedFlowRate
orRatedFlowRate
HoursInOperation
FanPower
orextension/FanPowerDefaulted=true
id boolean boolean string double double double or boolean
cfm hrs/day W
true See See >= 0 0 - 24 >= 0 or true
Yes Yes Yes Yes Yes Yes See
Unique identifier Must be set to true Whether it serves multiple dwelling units Type of ventilation system Flow rate Hours per day of operation Fan power or whether fan power is unknown
If a supply only or exhaust only system is specified, no additional information is entered.
If a balanced system is specified, no additional information is entered.
If a heat recovery ventilator system is specified, additional information is entered in VentilationFan
.
Element Type Units Constraints Required Default Notes SensibleRecoveryEfficiency
orAdjustedSensibleRecoveryEfficiency
double frac 0 - 1 Yes (Adjusted) Sensible recovery efficiency
If an energy recovery ventilator system is specified, additional information is entered in VentilationFan
.
Element Type Units Constraints Required Default Notes
TotalRecoveryEfficiency
orAdjustedTotalRecoveryEfficiency
SensibleRecoveryEfficiency
orAdjustedSensibleRecoveryEfficiency
double double
frac frac
0 - 1 0 - 1
Yes Yes
(Adjusted) Total recovery efficiency (Adjusted) Sensible recovery efficiency
If a central fan integrated supply system is specified, additional information is entered in VentilationFan
.
Element Type Units Constraints Required Default Notes AttachedToHVACDistributionSystem
idref See Yes ID of attached distribution 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
orextension/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 not measured 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
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).
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
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
orEnergyFactor
FirstHourRating
RecoveryEfficiency
double double double double
Btuh frac gal/hr frac
> 0 < 1 > 0 0 - 1
No Yes See See
See
Heating 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
If an instantaneous tankless water heater is specified, additional information is entered in WaterHeatingSystem
.
Element Type Units Constraints Required Default Notes
FuelType
UniformEnergyFactor
orEnergyFactor
string double
frac
See < 1
Yes Yes
Fuel type EnergyGuide label rated efficiency
If a heat pump water heater is specified, additional information is entered in WaterHeatingSystem
.
Element Type Units Constraints Required Default Notes
FuelType
TankVolume
UniformEnergyFactor
orEnergyFactor
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
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
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
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
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.
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
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
If a shared recirculation system is specified, additional information is entered in extension/SharedRecirculation
.
Element Type Units Constraints Required Default Notes NumberofUnitsServed
integer > 1 Yes Number of dwelling units served
PumpPower
ControlType
double string
W
>= 0 See
No Yes
220
Shared recirculation pump power Shared recirculation control type
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
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
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.
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
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
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
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).
Appliances entered in /HPXML/Building/BuildingDetails/Appliances
.
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
orModifiedEnergyFactor
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 ft3See > 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 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.
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
orEnergyFactor
ControlType
id boolean string string double string
lb/kWh
See See > 0 See
Yes Yes Yes Yes Yes Yes
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.
A single dishwasher can be entered as a /HPXML/Building/BuildingDetails/Appliances/Dishwasher
.
Element Type Units Constraints Required Default Notes
SystemIdentifier
IsSharedAppliance
Location
RatedAnnualkWh
orEnergyFactor
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 EnergyGuide label natural gas rate EnergyGuide label annual gas cost EnergyGuide label number of cycles 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.
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.
Each dehumidifier can be entered as a /HPXML/Building/BuildingDetails/Appliances/Dehumidifier
.
Element Type Units Constraints Required Default Notes
SystemIdentifier
Type
Location
Capacity
IntegratedEnergyFactor
orEnergyFactor
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".
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?
Lighting and ceiling fans are entered in /HPXML/Building/BuildingDetails/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
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
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
When running HPXML files, errors may occur because:
- An HPXML file provided is invalid (either relative to the HPXML schema or the ERI Use Case).
- An unexpected error occurred in the workflow (e.g., applying the ERI 301 ruleset).
- 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.
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.