Workflow Inputs

Introduction

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

HPXML Inputs

HPXML is an flexible and extensible format, where nearly all elements in the schema are optional and custom elements can be included. Because of this, a stricter set of requirements for the HPXML file have been developed for purposes of running an Energy Rating Index calculation.

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

1. Validation against the HPXML Schema

The HPXML XSD Schema can be found at hpxml-measures/HPXMLtoOpenStudio/resources/hpxml_schema/HPXML.xsd. XSD Schemas are used to validate what elements/attributes/enumerations are available, data types for elements/attributes, the number/order of children elements, etc.

2. Validation using Schematron

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

Important

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

• Validation against XSD for general correctness and usage of HPXML

• Validation against Schematron for understanding XML document requirements specific to running ERI calculations

HPXML Software Info

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

HPXML Calculations

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

Element	Type	Units	Constraints	Required	Default	Description
ERICalculation/Version	string		See [1]	No	<none>	Version(s) to perform ERI calculation; multiple allowed
CO2IndexCalculation/Version	string		See [2]	No	<none>	Version(s) to perform CO2e Index calculation; multiple allowed
IECCERICalculation/Version	string		See [3]	No	<none>	Version(s) to perform IECC ERI calculation; multiple allowed
EnergyStarCalculation/Version	string		See [4]	No	<none>	Version(s) to perform ENERGY STAR ERI calculation; multiple allowed
DENHCalculation/Version	string		See [5]	No	<none>	Version(s) to perform DOE Efficient New Homes ERI calculation; multiple allowed

[1]

ERICalculation/Version choices are “latest”, “2022CE”, “2022C”, “2022”, “2019ABCD”, “2019ABC”, “2019AB”, “2019A”, “2019”, “2014AEG”, “2014AE”, “2014A”, or “2014”. For example, a value of “2019AB” tells the workflow to use ANSI/RESNET/ICC 301-2019 with both Addendum A and Addendum B included. A value of “latest” can be used to always point to the latest version available, including any RESNET HERS addenda not yet incorporated in ANSI/RESNET/ICC 301 at the time of release.

[2]

CO2IndexCalculation/Version choices are “latest”, “2022CE”, “2022C”, “2022”, or “2019ABCD”. A value of “latest” can be used to always point to the latest version available, including any RESNET HERS addenda not yet incorporated in ANSI/RESNET/ICC 301 at the time of release. If HERS Diagnostic Output is requested, a single CO2IndexCalculation/Version and a single ERICalculation/Version must be provided and use the same version.

[3]

IECCERICalculation/Version choices are “2024”, “2021”, “2018”, or “2015”.

[4]

EnergyStarCalculation/Version choices are “SF_National_3.3”, “SF_National_3.2”, “SF_National_3.1”, “SF_National_3.0”, “SF_Pacific_3.0”, “SF_Florida_3.1”, “SF_OregonWashington_3.2”, “MF_National_1.3”, “MF_National_1.2”, “MF_National_1.1”, “MF_National_1.0”, or “MF_OregonWashington_1.2”.

[5]

DENHCalculation/Version choices are “SF_2.0”, “MF_2.0” or “1.0”. DOE Efficient New Homes (DENH) was formerly known as Zero Energy Ready Homes (ZERH).

Warning

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

Warning

For the ENERGY STAR and DOE Efficient New Homes ERI calculation, OpenStudio-ERI does not perform additional compliance checks beyond comparing the ERI to the ERI Target. For example, it does not check that the home meets all ENERGY STAR and DOE Efficient New Homes Mandatory Requirements. It is the software tool’s responsibility to perform these additional steps.

HPXML Utility Bill Scenarios

One or more utility bill scenarios can be entered as an /HPXML/SoftwareInfo/extension/UtilityBillScenarios/UtilityBillScenario. If not entered, utility bills will not be calculated.

Element	Type	Units	Constraints	Required	Default	Notes
Name	string			Yes		Name of the scenario (which shows up in the output file)
UtilityRate	element			No		Utility rate(s) for a given fuel type; multiple are allowed
PVCompensation	element			No		PV compensation information

See Home Utility Bills (CSV) for a description of how the calculated utility bills appear in the output files.

Electricity Rates

For each scenario, electricity rates can be optionally entered as an /HPXML/SoftwareInfo/extension/UtilityBillScenarios/UtilityBillScenario/UtilityRate. Electricity rates can be entered using Simple inputs or Detailed inputs.

Simple

For simple utility rate structures, inputs can be entered using a fixed charge and a marginal rate.

Element	Type	Units	Constraints	Required	Default	Notes
FuelType	string		electricity	Yes		Fuel type
FixedCharge	double	$/month	>= 0	No	12.0	Monthly fixed charge
MarginalRate	double	$/kWh	>= 0	No	See [6]	Marginal flat rate

[6]

If MarginalRate not provided, it defaults to state-level value based on EIA SEDS data, available at hpxml-measures/ReportUtilityBills/resources/simple_rates/eia_fuel_rates_by_state.csv.

Detailed

For detailed utility rate structures, inputs can be entered using a tariff JSON file.

Element	Type	Units	Constraints	Required	Default	Notes
FuelType	string		electricity	Yes		Fuel type
TariffFilePath	string			Yes		Path to tariff JSON file [7]

[7]

TariffFilePath must point to a JSON file with utility rate structure information. Tariff files can describe flat, tiered, time-of-use, tiered time-of-use, or real-time pricing rates. Sources of tariff files include OpenEI’s U.S. Utility Rate Database (URDB); a large set of residential OpenEI URDB rates for U.S. utilities are included at hpxml-measures/ReportUtilityBills/resources/detailed_rates/openei_rates.zip. Additional sample tariff files can be found in hpxml-measures/ReportUtilityBills/resources/detailed_rates. Tariff files are formatted based on OpenEI API version 7.

Fuel Rates

For each scenario, fuel rates can be optionally entered as an /HPXML/SoftwareInfo/extension/UtilityBillScenarios/UtilityBillScenario/UtilityRate.

Element	Type	Units	Constraints	Required	Default	Notes
FuelType	string		See [8]	Yes		Fuel type
FixedCharge	double	$/month	>= 0	No	See [9]	Monthly fixed charge
MarginalRate	double	See [10]	>= 0	No	See [11]	Marginal flat rate

[8]

FuelType choices are “natural gas”, “propane”, “fuel oil”, “coal”, “wood”, and “wood pellets”.

[9]

FixedCharge defaults to $12/month for natural gas and $0/month for other fuels.

[10]

MarginalRate units are $/therm for natural gas, $/gallon for propane and fuel oil, and $/kBtu for other fuels.

[11]

If MarginalRate not provided, it defaults to state-level value based on EIA SEDS data, available at hpxml-measures/ReportUtilityBills/resources/simple_rates/eia_fuel_rates_by_state.csv.

PV Compensation

For each scenario, PV compensation information can be optionally entered in /HPXML/SoftwareInfo/extension/UtilityBillScenarios/UtilityBillScenario/PVCompensation.

Element	Type	Units	Constraints	Required	Default	Notes
CompensationType[NetMetering | FeedInTariff]	element			No	NetMetering	PV compensation type
MonthlyGridConnectionFee[Units="$/kW" or Units="$"]/Value	double			No	0	PV monthly grid connection fee

Net-Metering

If the PV compensation type is net-metering, additional information can be entered in /HPXML/SoftwareInfo/extension/UtilityBillScenarios/UtilityBillScenario/PVCompensation/CompensationType/NetMetering.

Element	Type	Units	Constraints	Required	Default	Notes
AnnualExcessSellbackRateType	string		See [12]	No	User-Specified	Net metering annual excess sellback rate type [13]
AnnualExcessSellbackRate	double	$/kWh	>= 0	No [14]	0.03	User-specified net metering annual excess sellback rate [15]

[12]

AnnualExcessSellbackRateType choices are “User-Specified” and “Retail Electricity Cost”.

[13]

When annual PV production exceeds the annual building electricity consumption, this rate, which is often significantly below the retail rate, determines the value of the excess electricity sold back to the utility. This may happen to offset gas consumption, for example.

[14]

AnnualExcessSellbackRate is only used when AnnualExcessSellbackRateType=”User-Specified”.

[15]

Since modeled electricity consumption will not change from one year to the next, “indefinite rollover” of annual excess generation credit is best approximated by setting “User-Specified” and entering a rate of zero.

Feed-in Tariff

If the PV compensation type is feed-in tariff, additional information can be entered in /HPXML/SoftwareInfo/extension/UtilityBillScenarios/UtilityBillScenario/PVCompensation/CompensationType/FeedInTariff.

Element	Type	Units	Constraints	Required	Default	Notes
FeedInTariffRate	double	$/kWh	>= 0	No	0.12	Feed-in tariff rate [16]

[16]

FeedInTariffRate applies to full (not excess) PV production. Some utilities/regions may have a feed-in tariff policy where compensation occurs for excess PV production (i.e., PV-generated electricity sent to the grid that is not immediately consumed by the building), rather than full PV production. OpenStudio-ERI is currently unable to calculate utility bills for such a feed-in tariff policy.

HPXML Building Site

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

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

[17]

For ENERGY STAR calculations, allowed StateCode choices depend on the ENERGY STAR version:

- National: <anything>

- Pacific: HI, GU, MP

- Florida: FL

- OregonWashington: OR, WA

[18]

ZipCode can be defined as the standard 5 number postal code, or it can have the additional 4 number code separated by a hyphen.

[19]

ZipCode is used to look up the eGrid subregion (see rulesets/data/egrid/ZIP_mappings.csv) and Cambium region (see rulesets/data/cambium/ZIP_mappings.csv) for emissions calculations and the CO2e Index. It may also be used to choose a default TMY3 weather station when not provided in HPXML Weather Station.

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 [20]	Yes		Fuel name

[20]

Fuel choices can be found at the HPXML Toolbox website.

Note

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

HPXML Building Construction

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

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

[21]

ResidentialFacilityType choices are “single-family detached”, “single-family attached”, or “apartment unit”. For ENERGY STAR and DENH, “single-family detached” and “single-family attached” may only be used for SF versions and “apartment unit” may only be used for MF versions.

HPXML Weather Station

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

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

[22]

If EPWFilePath not provided, defaults based on the U.S. TMY3 weather station closest to the zip code centroid. The mapping can be found at hpxml-measures/HPXMLtoOpenStudio/resources/data/zipcode_weather_stations.csv.

[23]

The full set of U.S. TMY3 weather files can be downloaded here.

HPXML Climate Zones

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

Element	Type	Units	Constraints	Required	Default	Description
Year	integer		See [24]	Yes [25]		IECC year
ClimateZone	string		See [26]	Yes		IECC zone

[24]

Year choices are 2003, 2006, 2009, 2012, 2015, 2018, 2021, or 2024.

[25]

The IECC climate zone for 2006 is always required. IECC climate zone years other than 2006 are optional; for programs that use specific IECC climate zone years (e.g., 2021 for DENH SF 2.0), that year is used if provided, otherwise the next earliest provided year will be used with the assumption that the climate zone has not changed across the years. See below for the list of climate zone years used by different programs:

- ENERGY STAR SF_National_3.3, SF_National_3.2, MF_National_1.3, MF_National_1.2: 2021

- ENERGY STAR SF_National_3.1, MF_National_1.1, SF_OregonWashington_3.2, MF_OregonWashington_1.2: 2012

- DENH SF_2.0, MF_2.0: 2021

- DENH 1.0: 2015

- IECC ERI 20XX: 20XX

[26]

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

HPXML Enclosure

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

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

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

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

Warning

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

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

HPXML Air Infiltration

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
InfiltrationVolume	double	ft3	> 0	Yes		Volume associated with infiltration measurement [27]
InfiltrationHeight	double	ft	> 0	No	See [28]	Height associated with infiltration measurement [29]

[27]

InfiltrationVolume can be thought of as the volume of space most impacted by a blower door test. Note that InfiltrationVolume can be larger than ConditionedBuildingVolume as it can include, e.g., attics or basements with access doors/hatches that are open during the blower door test.

[28]

If InfiltrationHeight not provided, it is estimated from other inputs (e.g., ConditionedFloorArea, NumberofConditionedFloorsAboveGrade, attics/foundations with WithinInfiltrationVolume=true, etc.).

[29]

InfiltrationHeight is defined as the vertical distance between the lowest and highest above-grade points within the pressure boundary, per ASHRAE 62.2.

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

• ACH or CFM

• Natural ACH or CFM

• Effective Leakage Area

ACH or CFM

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

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

[30]

HousePressure typical value is 50 Pa.

[31]

UnitofMeasure choices are “ACH” or “CFM”.

[32]

For attached dwelling units, BuildingAirLeakage/AirLeakage should be a compartmentalization test value and not adjusted by the Aext reduction factor specified in ANSI/RESNET/ICC 301. OpenStudio-ERI will automatically calculate and apply the Aext adjustment (and the Aext value can be found in, e.g., the ERIRatedHome.xml output file). Note that all attached surfaces, even adiabatic surfaces, must be defined in the HPXML file.

Natural ACH or CFM

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

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

[33]

UnitofMeasure choices are “ACHnatural” or “CFMnatural”.

[34]

For attached dwelling units, BuildingAirLeakage/AirLeakage should not be adjusted by the Aext reduction factor specified in ANSI/RESNET/ICC 301. OpenStudio-ERI will automatically calculate and apply the Aext adjustment (and the Aext value can be found in, e.g., the ERIRatedHome.xml output file).

Effective Leakage Area

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

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

[35]

For attached dwelling units, BuildingAirLeakage/AirLeakage should not be adjusted by the Aext reduction factor specified in ANSI/RESNET/ICC 301. OpenStudio-ERI will automatically calculate and apply the Aext adjustment (and the Aext value can be found in, e.g., the ERIRatedHome.xml output file).

HPXML Attics

If the dwelling unit has an unvented attic, additional information is entered in /HPXML/Building/BuildingDetails/Enclosure/Attics/Attic[AtticType/Attic[Vented="false"]].

Element	Type	Units	Constraints	Required	Default	Notes
WithinInfiltrationVolume	boolean		See [36]	Yes		Whether door/hatch to conditioned space open during blower door test [37]

[36]

If there are multiple unvented attics, they must all have the same value.

[37]

See ANSI/RESNET/ICC 380-2022 for more information.

If the dwelling unit has a vented attic, additional information is entered in /HPXML/Building/BuildingDetails/Enclosure/Attics/Attic[AtticType/Attic[Vented="true"]].

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

[38]

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

[39]

If there are multiple vented attics, they must all have the same value.

HPXML Foundations

If the dwelling unit has a conditioned basement, additional information is entered in /HPXML/Building/BuildingDetails/Enclosure/Foundations/Foundation/FoundationType/Basement[Conditioned='true'].

Element	Type	Units	Constraints	Required	Default	Notes
WithinInfiltrationVolume	boolean		See [40]	No	true	Whether door/hatch to conditioned space open during blower door test [41]

[40]

If there are multiple conditioned basements, they must all have the same value.

[41]

See ANSI/RESNET/ICC 380-2022 for more information.

If the dwelling unit has an unconditioned basement, additional information is entered in /HPXML/Building/BuildingDetails/Enclosure/Foundations/Foundation[FoundationType/Basement[Conditioned='false']].

Element	Type	Units	Constraints	Required	Default	Notes
WithinInfiltrationVolume	boolean		See [42]	Yes		Whether door/hatch to conditioned space open during blower door test [43]

[42]

If there are multiple unconditioned basements, they must all have the same value.

[43]

See ANSI/RESNET/ICC 380-2022 for more information.

If the dwelling unit has an unvented crawlspace, additional information is entered in /HPXML/Building/BuildingDetails/Enclosure/Foundations/Foundation[FoundationType/Crawlspace[Vented='false']].

Element	Type	Units	Constraints	Required	Default	Notes
WithinInfiltrationVolume	boolean		See [44]	Yes		Whether door/hatch to conditioned space open during blower door test [45]

[44]

If there are multiple unvented crawlspaces, they must all have the same value.

[45]

See ANSI/RESNET/ICC 380-2022 for more information.

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

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

[46]

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

[47]

If there are multiple vented crawlspaces, they must all have the same value.

HPXML Roofs

Each pitched or flat roof surface that is exposed to ambient conditions is entered as a /HPXML/Building/BuildingDetails/Enclosure/Roofs/Roof.

For a multifamily building where the dwelling unit has another dwelling unit above it, the surface between the two dwelling units should be considered a Floor and not a Roof.

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

[48]

InteriorAdjacentTo choices are “attic - vented”, “attic - unvented”, “conditioned space”, or “garage”. See HPXML Locations for descriptions.

[49]

If Azimuth not provided, and it’s a pitched roof, modeled as four surfaces of equal area facing every direction. Azimuth is irrelevant for flat roofs.

[50]

Pitch is entered as vertical rise in inches for every 12 inches of horizontal run. For example, 6.0 means a 6/12 roof, which has a 26.57-degree roof slope.

[51]

RadiantBarrierGrade only required if RadiantBarrier=true.

[52]

AssemblyEffectiveRValue includes all material layers and interior/exterior air films.

Warning

It is currently the software developer’s responsibility to ensure the AssemblyEffectiveRValue includes the effects of insulation gaps (installation grading) and/or compressed insulation in cavities per ANSI/RESNET/ICC 301-2022.

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 a /HPXML/Building/BuildingDetails/Enclosure/RimJoists/RimJoist.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
ExteriorAdjacentTo	string		See [53]	Yes		Exterior adjacent space type
InteriorAdjacentTo	string		See [54]	Yes		Interior adjacent space type
Area	double	ft2	> 0	Yes		Gross area
Azimuth	integer	deg	>= 0, <= 359	No	See [55]	Azimuth (clockwise from North)
SolarAbsorptance	double		>= 0, <= 1	See [56]		Solar absorptance of outermost material
Emittance	double		>= 0, <= 1	See [57]		Emittance of outermost material
Insulation/SystemIdentifier	id			Yes		Unique identifier
Insulation/AssemblyEffectiveRValue	double	F-ft2-hr/Btu	> 0	Yes		Assembly R-value [58]

[53]

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

[54]

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

[55]

If Azimuth not provided, and it’s an exterior rim joist, modeled as four surfaces of equal area facing every direction. Azimuth is irrelevant for interior rim joists.

[56]

SolarAbsorptance only required for exterior rim joists (i.e., ExteriorAdjacentTo=outside).

[57]

Emittance only required for exterior rim joists (i.e., ExteriorAdjacentTo=outside).

[58]

AssemblyEffectiveRValue includes all material layers and interior/exterior air films.

Warning

It is currently the software developer’s responsibility to ensure the AssemblyEffectiveRValue includes the effects of insulation gaps (installation grading) and/or compressed insulation in cavities per ANSI/RESNET/ICC 301-2022.

HPXML Walls

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

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

[59]

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

[60]

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

[61]

WallType child element choices are WoodStud, DoubleWoodStud, ConcreteMasonryUnit, StructuralInsulatedPanel, InsulatedConcreteForms, SteelFrame, SolidConcrete, StructuralBrick, StrawBale, Stone, LogWall, or Adobe.

[62]

If Azimuth not provided, and it’s an exterior wall, modeled as four surfaces of equal area facing every direction. Azimuth is irrelevant for interior walls (e.g., between conditioned space and garage).

[63]

SolarAbsorptance only required for exterior walls (i.e., ExteriorAdjacentTo=outside).

[64]

Emittance only required for exterior walls (i.e., ExteriorAdjacentTo=outside).

[65]

AssemblyEffectiveRValue includes all material layers and interior/exterior air films.

Warning

It is currently the software developer’s responsibility to ensure the AssemblyEffectiveRValue includes the effects of insulation gaps (installation grading) and/or compressed insulation in cavities per ANSI/RESNET/ICC 301-2022.

HPXML Foundation Walls

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

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

[66]

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

[67]

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

[68]

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

[69]

Type choices are “solid concrete”, “concrete block”, “concrete block foam core”, “concrete block vermiculite core”, “concrete block perlite core”, “concrete block solid core”, “double brick”, or “wood”.

[70]

If Azimuth not provided, and it’s an exterior foundation wall, modeled as four surfaces of equal area facing every direction. Azimuth is irrelevant for interior foundation walls (e.g., between basement and garage).

[71]

For exterior foundation walls, depth below grade is relative to the ground plane. For interior foundation walls, depth below grade is the vertical span of foundation wall in contact with the ground. For example, an interior foundation wall between an 8 ft conditioned basement and a 3 ft crawlspace has a height of 8 ft and a depth below grade of 5 ft. Alternatively, an interior foundation wall between an 8 ft conditioned basement and an 8 ft unconditioned basement has a height of 8 ft and a depth below grade of 0 ft.

[72]

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

[73]

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

[74]

AssemblyEffectiveRValue only required if Layer elements are not provided.

[75]

AssemblyEffectiveRValue includes all material layers and the interior air film; it should not include the exterior air film (for any above-grade exposure) or any soil thermal resistance.

Warning

It is currently the software developer’s responsibility to ensure the AssemblyEffectiveRValue includes the effects of insulation gaps (installation grading) and/or compressed insulation in cavities per ANSI/RESNET/ICC 301-2022.

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

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

[76]

When NominalRValue is non-zero, DistanceToBottomOfInsulation must be greater than DistanceToTopOfInsulation and less than or equal to FoundationWall/Height.

HPXML Floors

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
ExteriorAdjacentTo	string		See [77]	Yes		Exterior adjacent space type
InteriorAdjacentTo	string		See [78]	Yes		Interior adjacent space type
FloorOrCeiling	string		See [79]	See [80]		Floor or ceiling from the perspective of the conditioned space
FloorType	element		See [81]	Yes		Floor type (for thermal mass)
Area	double	ft2	> 0	Yes		Gross area (including skylights for ceilings)
Insulation/SystemIdentifier	id			Yes		Unique identifier
Insulation/AssemblyEffectiveRValue	double	F-ft2-hr/Btu	> 0	Yes		Assembly R-value [82]

[77]

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

[78]

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

[79]

FloorOrCeiling choices are “floor” or “ceiling”.

[80]

FloorOrCeiling only required for floors adjacent to “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”.

[81]

FloorType child element choices are WoodFrame, StructuralInsulatedPanel, SteelFrame, or SolidConcrete.

[82]

AssemblyEffectiveRValue includes all material layers and interior/exterior air films.

Warning

It is currently the software developer’s responsibility to ensure the AssemblyEffectiveRValue includes the effects of insulation gaps (installation grading), compressed insulation in cavities, and/or reduced attic floor insulation thickness at the eaves per ANSI/RESNET/ICC 301-2022.

HPXML Slabs

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
InteriorAdjacentTo	string		See [83]	Yes		Interior adjacent space type
Area	double	ft2	> 0	Yes		Gross area
Thickness	double	in	>= 0	No	See [84]	Thickness [85]
ExposedPerimeter	double	ft	>= 0	Yes		Perimeter exposed to ambient conditions [86]
DepthBelowGrade	double	ft	>= 0	No	See [87]	Depth from the top of the slab surface to grade
PerimeterInsulation/SystemIdentifier	id			Yes		Unique identifier
PerimeterInsulation/Layer/NominalRValue	double	F-ft2-hr/Btu	>= 0	Yes		R-value of vertical insulation (see figure below)
PerimeterInsulation/Layer/InsulationDepth	double	ft	>= 0	Yes		Depth from top of slab to bottom of vertical insulation
UnderSlabInsulation/SystemIdentifier	id			Yes		Unique identifier
UnderSlabInsulation/Layer/NominalRValue	double	F-ft2-hr/Btu	>= 0	Yes		R-value of horizontal insulation (see figure below)
UnderSlabInsulation/Layer/InsulationWidth	double	ft	>= 0	See [88]		Width from slab edge inward of horizontal insulation
UnderSlabInsulation/Layer/InsulationSpansEntireSlab	boolean			See [89]		Whether horizontal insulation spans entire slab
extension/GapInsulationRValue	double	F-ft2-hr/Btu	>= 0	No	See [90]	R-value of gap insulation (see figure below)
extension/CarpetFraction	double	frac	>= 0, <= 1	Yes		Fraction of slab covered by carpet
extension/CarpetRValue	double	F-ft2-hr/Btu	>= 0	Yes		Carpet R-value

[83]

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

[84]

If Thickness not provided, defaults to 0 when adjacent to crawlspace and 4 inches for all other cases.

[85]

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

[86]

ExposedPerimeter includes any slab length that falls along the perimeter of the building’s footprint (i.e., is exposed to ground or outdoor air conditions). See the figure below for an example of calculating slab exposed perimeter.

[87]

If DepthBelowGrade not provided, defaults to zero for foundation types without walls. For foundation types with walls, DepthBelowGrade is ignored as the slab’s position relative to grade is determined by the FoundationWall/DepthBelowGrade value(s).

[88]

InsulationWidth only required if InsulationSpansEntireSlab=true is not provided.

[89]

InsulationSpansEntireSlab=true only required if InsulationWidth is not provided.

[90]

If GapInsulationRValue not provided, defaults to 5.0 if there is under slab (horizontal) insulation, otherwise 0.0.

An example of calculating slab exposed perimeter is shown below:

As illustrated above, basement slab edge adjacent to a garage slab or crawlspace is not considered exposed perimeter. It is quite uncommon for a slab to have an exposed perimeter of zero. Heat transfer is only calculated for the length of exposed perimeter; the rest of the perimeter is assumed to have minimal heat transfer.

Slab insulation locations can be visualized in the figure below:

HPXML Windows

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

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

[91]

For bay or garden windows, this should represent the total area, not just the primary flat exposure. The ratio of total area to primary flat exposure is typically around 1.15 for bay windows and 2.0 for garden windows.

[92]

FractionOperable reflects whether the windows are operable (can be opened), not how they are used by the occupants. If a Window represents a single window, the value should be 0 or 1. If a Window represents multiple windows, the value is calculated as the total window area for any operable windows divided by the total window area.

[93]

PerformanceClass choices are “residential” (e.g., Class R) or “architectural” (e.g., Class AW).

[94]

AttachedToWall must reference a Wall or FoundationWall.

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

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

[95]

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

[96]

When Depth is non-zero, DistanceToBottomOfWindow must be greater than DistanceToTopOfWindow.

HPXML Skylights

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
Area	double	ft2	> 0	Yes		Total area [97]
Azimuth	integer	deg	>= 0, <= 359	Yes		Azimuth (clockwise from North)
UFactor	double	Btu/F-ft2-hr	> 0	Yes		Full-assembly NFRC U-factor
SHGC	double		> 0, < 1	Yes		Full-assembly NFRC solar heat gain coefficient
AttachedToRoof	idref		See [98]	Yes		ID of attached roof
AttachedToFloor	idref		See [99]	See [100]		ID of attached attic floor for a skylight with a shaft or sun tunnel
extension/Curb	element			No	<none>	Presence of curb (skylight wall above the roof deck) [101]
extension/Shaft	element			No	<none>	Presence of shaft (skylight wall below the roof deck) [102]

[97]

For dome skylights, this should represent the total area, not just the primary flat exposure. The ratio of total area to primary flat exposure is typically around 1.25 for dome skylights.

[98]

AttachedToRoof must reference a Roof.

[99]

AttachedToFloor must reference a Floor.

[100]

AttachedToFloor required if the attached roof is not adjacent to conditioned space (i.e., there is a skylight shaft).

[101]

If extension/Curb is provided, additional inputs are described in Skylight Curb.

[102]

If extension/Shaft is provided, additional inputs are described in Skylight Shaft. The skylight shaft will be modeled similar to an attic knee wall.

Skylight Curb

If the skylight has a curb, additional information is entered in Skylight.

Element	Type	Units	Constraints	Required	Default	Notes
extension/Curb/Area	double	ft2	> 0	Yes		Total area including all sides
extension/Curb/AssemblyEffectiveRValue	double	F-ft2-hr/Btu	> 0	Yes		Assembly R-value [103]

[103]

AssemblyEffectiveRValue includes all material layers and interior/exterior air films.

Skylight Shaft

If the skylight has a shaft, additional information is entered in Skylight.

Element	Type	Units	Constraints	Required	Default	Notes
extension/Shaft/Area	double	ft2	> 0	Yes		Total area including all sides
extension/Shaft/AssemblyEffectiveRValue	double	F-ft2-hr/Btu	> 0	Yes		Assembly R-value [104]

[104]

AssemblyEffectiveRValue includes all material layers and interior/exterior air films.

HPXML Doors

Each door with opaque area is entered as a /HPXML/Building/BuildingDetails/Enclosure/Doors/Door.

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

[105]

AttachedToWall must reference a Wall or FoundationWall.

[106]

Any glass area in the door should be modeled using HPXML Windows. For example, if a 30 ft2 door has 10 ft2 of glass, the door area should be entered as 20 ft2 (with a separate Window for the remaining 10 ft2).

[107]

RValue includes interior/exterior air films and presence of any storm door.

HPXML Systems

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

HPXML Heating Systems

The following heating system types can be modeled:

• Electric Resistance

• Furnace

• Wall Furnace

• Floor Furnace

• Boiler (In-Unit)

• Boiler (Shared)

• Stove

• Space Heater

• Fireplace

Electric Resistance

Each electric resistance heating system is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
HeatingSystemType/ElectricResistance	element			Yes		Type of heating system
HeatingSystemFuel	string		electricity	Yes		Fuel type
HeatingCapacity	double	Btu/hr	>= 0 [108]	Yes		Heating output capacity
AnnualHeatingEfficiency[Units="Percent"]/Value	double	frac	> 0, <= 1	Yes		Heating efficiency
FractionHeatLoadServed	double	frac	>= 0, <= 1 [109]	Yes		Fraction of heating load served

[108]

HeatingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[109]

The sum of all FractionHeatLoadServed (across all HVAC systems) must be less than or equal to 1.

Furnace

Each central furnace is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
DistributionSystem	idref		See [110]	Yes		ID of attached distribution system
HeatingSystemType/Furnace	element			Yes		Type of heating system
HeatingSystemFuel	string		See [111]	Yes		Fuel type
HeatingCapacity	double	Btu/hr	>= 0 [112]	Yes		Heating output capacity
AnnualHeatingEfficiency[Units="AFUE"]/Value	double	frac	> 0, <= 1	Yes		Rated heating efficiency
FractionHeatLoadServed	double	frac	>= 0, <= 1 [113]	Yes		Fraction of heating load served
extension/FanMotorType	string		See [114]	No	See [115]	Blower fan model type
extension/FanPowerWattsPerCFM	double	W/cfm	>= 0 [116]	Yes		Blower fan efficiency at maximum fan speed [117]
extension/HeatingDesignAirflowCFM	double	cfm	>= 0	No	240 cfm/ton	Blower fan heating design airflow rate [118]
extension/AirflowDefectRatio	double	frac	>= -0.9, <= 9	Yes		Deviation between design/installed airflow rates [119]

[110]

HVACDistribution type must be Air Distribution (type: “regular velocity” or “gravity”) or Distribution System Efficiency (DSE).

[111]

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

[112]

HeatingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[113]

The sum of all FractionHeatLoadServed (across all HVAC systems) must be less than or equal to 1.

[114]

FanMotorType choices are “PSC” (Permanent Split Capacitor) and “BPM” (Brushless Permanent Magnet). If there is a cooling system attached to the DistributionSystem, the heating and cooling systems cannot have different values for FanMotorType.

[115]

If FanMotorType is not provided and if there is a cooling system attached to the DistributionSystem, defaults to “PSC” if the attached cooling system CompressorType is “single stage”, else “BPM”; If there’s no cooling system attached, defaults to “PSC” if AFUE <= 0.9, else “BPM”.

[116]

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

[117]

If the fan power is not measured, a value of 0.58 W/cfm should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

[118]

When the home’s blower fan airflow is measured according to ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems, the design airflow rate should be provided for either the heating mode (HeatingDesignAirflowCFM) or cooling mode (CoolingDesignAirflowCFM of cooling system attached to the DistributionSystem).

[119]

AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect. A non-zero airflow defect can only be applied for systems attached to a distribution system. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information. If the airflow rate is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

Warning

HVAC installation grading inputs (i.e., FanPowerWattsPerCFM and AirflowDefectRatio) should be provided per the conditions specified in ANSI/RESNET/ACCA 310-2020. 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 Furnace

Each wall furnace is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
HeatingSystemType/WallFurnace	element			Yes		Type of heating system
HeatingSystemFuel	string		See [120]	Yes		Fuel type
HeatingCapacity	double	Btu/hr	>= 0 [121]	Yes		Heating output capacity
AnnualHeatingEfficiency[Units="AFUE"]/Value	double	frac	> 0, <= 1	Yes		Rated heating efficiency
FractionHeatLoadServed	double	frac	>= 0, <= 1 [122]	Yes		Fraction of heating load served
extension/FanPowerWatts	double	W	>= 0	No	0	Fan power

[120]

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

[121]

HeatingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[122]

The sum of all FractionHeatLoadServed (across all HVAC systems) must be less than or equal to 1.

Floor Furnace

Each floor furnace is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
HeatingSystemType/FloorFurnace	element			Yes		Type of heating system
HeatingSystemFuel	string		See [123]	Yes		Fuel type
HeatingCapacity	double	Btu/hr	>= 0 [124]	Yes		Heating output capacity
AnnualHeatingEfficiency[Units="AFUE"]/Value	double	frac	> 0, <= 1	Yes		Rated heating efficiency
FractionHeatLoadServed	double	frac	>= 0, <= 1 [125]	Yes		Fraction of heating load served
extension/FanPowerWatts	double	W	>= 0	No	0	Fan power

[123]

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

[124]

HeatingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[125]

The sum of all FractionHeatLoadServed (across all HVAC systems) must be less than or equal to 1.

Boiler (In-Unit)

Each in-unit boiler is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
DistributionSystem	idref		See [126]	Yes		ID of attached distribution system
HeatingSystemType/Boiler	element			Yes		Type of heating system
HeatingSystemFuel	string		See [127]	Yes		Fuel type
HeatingCapacity	double	Btu/hr	>= 0 [128]	Yes		Heating output capacity
AnnualHeatingEfficiency[Units="AFUE"]/Value	double	frac	> 0, <= 1	Yes		Rated heating efficiency
FractionHeatLoadServed	double	frac	>= 0, <= 1 [129]	Yes		Fraction of heating load served

[126]

HVACDistribution type must be Hydronic Distribution (type: “radiator”, “baseboard”, “radiant floor”, or “radiant ceiling”) or Distribution System Efficiency (DSE). Note: The choice of hydronic distribution type does not currently affect simulation results.

[127]

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

[128]

HeatingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[129]

The sum of all FractionHeatLoadServed (across all HVAC systems) must be less than or equal to 1.

Boiler (Shared)

Each shared boiler (serving multiple dwelling units) is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units
NumberofUnitsServed	integer		> 1	Yes		Number of dwelling units served
DistributionSystem	idref		See [130]	Yes		ID of attached distribution system
HeatingSystemType/Boiler	element			Yes		Type of heating system
HeatingSystemFuel	string		See [131]	Yes		Fuel type
HeatingCapacity	double	Btu/hr	>= 0	Yes		Heating output capacity
AnnualHeatingEfficiency[Units="AFUE"]/Value	double	frac	> 0, <= 1	Yes		Rated heating efficiency
FractionHeatLoadServed	double	frac	>= 0, <= 1 [132]	Yes		Fraction of heating load served
extension/SharedLoopWatts	double	W	>= 0	Yes		Shared loop power
extension/SharedLoopMotorEfficiency	double	frac	> 0, < 1	No	0.85	Shared loop motor efficiency
extension/FanCoilWatts	double	W	>= 0	See [133]		Fan coil power

[130]

HVACDistribution type must be Hydronic Distribution (type: “radiator”, “baseboard”, “radiant floor”, “radiant ceiling”, or “water loop”) or Air Distribution (type: “fan coil”). If the shared boiler has “water loop” distribution, a Water-Loop-to-Air Heat Pump must also be specified. Note: The choice of hydronic distribution type does not currently affect simulation results.

[131]

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

[132]

The sum of all FractionHeatLoadServed (across all HVAC systems) must be less than or equal to 1.

[133]

FanCoilWatts only required if boiler connected to fan coil.

Stove

Each stove is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
HeatingSystemType/Stove	element			Yes		Type of heating system
HeatingSystemFuel	string		See [134]	Yes		Fuel type
HeatingCapacity	double	Btu/hr	>= 0 [135]	Yes		Heating output capacity
AnnualHeatingEfficiency[Units="Percent"]/Value	double	frac	> 0, <= 1	Yes		Heating efficiency
FractionHeatLoadServed	double	frac	>= 0, <= 1 [136]	Yes		Fraction of heating load served
extension/FanPowerWatts	double	W	>= 0	No	40	Fan power

[134]

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

[135]

HeatingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[136]

The sum of all FractionHeatLoadServed (across all HVAC systems) must be less than or equal to 1.

Space Heater

Each space heater is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
HeatingSystemType/SpaceHeater	element			Yes		Type of heating system
HeatingSystemFuel	string		See [137]	Yes		Fuel type
HeatingCapacity	double	Btu/hr	>= 0 [138]	Yes		Heating output capacity
AnnualHeatingEfficiency[Units="Percent"]/Value	double	frac	> 0, <= 1	Yes		Heating efficiency
FractionHeatLoadServed	double	frac	>= 0, <= 1 [139]	Yes		Fraction of heating load served
extension/FanPowerWatts	double	W	>= 0	No	0	Fan power

[137]

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

[138]

HeatingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[139]

The sum of all FractionHeatLoadServed (across all HVAC systems) must be less than or equal to 1.

Fireplace

Each fireplace is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
HeatingSystemType/Fireplace	element			Yes		Type of heating system
HeatingSystemFuel	string		See [140]	Yes		Fuel type
HeatingCapacity	double	Btu/hr	>= 0 [141]	Yes		Heating output capacity
AnnualHeatingEfficiency[Units="Percent"]/Value	double	frac	> 0, <= 1	Yes		Heating efficiency
FractionHeatLoadServed	double	frac	>= 0, <= 1 [142]	Yes		Fraction of heating load served
extension/FanPowerWatts	double	W	>= 0	No	0	Fan power

[140]

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

[141]

HeatingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[142]

The sum of all FractionHeatLoadServed (across all HVAC systems) must be less than or equal to 1.

HPXML Cooling Systems

The following cooling system types can be modeled:

• Central Air Conditioner

• Room Air Conditioner

• Packaged Terminal Air Conditioner

• Evaporative Cooler

• Mini-Split Air Conditioner

• Chiller (Shared)

• Cooling Tower (Shared)

Central Air Conditioner

Each central air conditioner is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/CoolingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
DistributionSystem	idref		See [143]	Yes		ID of attached distribution system
CoolingSystemType	string		central air conditioner	Yes		Type of cooling system
CoolingSystemFuel	string		electricity	Yes		Fuel type
CoolingCapacity	double	Btu/hr	>= 0 [144]	Yes		Cooling output capacity
CompressorType	string		See [145]	Yes		Type of compressor
FractionCoolLoadServed	double	frac	>= 0, <= 1 [146]	Yes		Fraction of cooling load served
AnnualCoolingEfficiency[Units="SEER2" or Units="SEER"]/Value	double	Btu/Wh	> 0	Yes		Rated cooling efficiency [147]
AnnualCoolingEfficiency[Units="EER2" or Units="EER"]/Value	double	Btu/Wh	> 0 [148]	Yes		Rated cooling efficiency [149]
extension/FanMotorType	string		See [150]	No	See [151]	Blower fan model type
extension/FanPowerWattsPerCFM	double	W/cfm	>= 0 [152]	Yes		Blower fan efficiency at maximum fan speed [153]
extension/CoolingDesignAirflowCFM	double	cfm	>= 0	No	360 cfm/ton	Blower fan cooling design airflow rate [154]
extension/AirflowDefectRatio	double	frac	>= -0.9, <= 9	Yes		Deviation between design/installed airflow rates [155]
extension/ChargeDefectRatio	double	frac	-0.25, 0, 0.25	Yes		Deviation between design/installed refrigerant charges [156]
extension/EquipmentType	string		See [157]	No	split system	Equipment type only used for SEER/SEER2 and EER/EER2 conversions

[143]

HVACDistribution type must be Air Distribution (type: “regular velocity”) or Distribution System Efficiency (DSE).

[144]

CoolingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[145]

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

[146]

The sum of all FractionCoolLoadServed (across all HVAC systems) must be less than or equal to 1.

[147]

If SEER provided, converted to SEER2 using ANSI/RESNET/ICC 301-2022 Addendum C. For example, SEER2 = SEER * 0.95 if EquipmentType is “split system”.

[148]

In addition, EER2 must be <= SEER2; EER must be < SEER.

[149]

If EER provided, converted to EER2 using ANSI/RESNET/ICC 301-2022 Addendum C. For example, EER2 = EER * 0.95 if EquipmentType is “split system”.

[150]

FanMotorType choices are “PSC” (Permanent Split Capacitor) and “BPM” (Brushless Permanent Magnet). If there is a heating system attached to the DistributionSystem, the heating and cooling systems cannot have different values for FanMotorType.

[151]

If FanMotorType is not provided, defaults to using attached furnace FanMotorType if available, else “PSC” if CompressorType is “single stage”, else “BPM”.

[152]

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

[153]

If the fan power is not measured, a value of 0.58 W/cfm should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

[154]

When the home’s blower fan airflow is measured according to ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems, the design airflow rate should be provided for either the cooling mode (CoolingDesignAirflowCFM) or heating mode (HeatingDesignAirflowCFM of heating system attached to the DistributionSystem).

[155]

AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect. A non-zero airflow defect can only be applied for systems attached to a distribution system. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information. If the airflow rate is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

[156]

ChargeDefectRatio is defined as (InstalledCharge - DesignCharge) / DesignCharge; a value of zero means no refrigerant charge defect. A non-zero charge defect should typically only be applied for systems that are charged on site, not for systems that have pre-charged line sets. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information. If the charge is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

[157]

EquipmentType choices are “split system”, “packaged system”, “small duct high velocity system”, or “space constrained system”.

Warning

HVAC installation grading inputs (i.e., FanPowerWattsPerCFM, AirflowDefectRatio, and ChargeDefectRatio) should be provided per the conditions specified in ANSI/RESNET/ACCA 310-2020. 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

Each room air conditioner is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/CoolingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
CoolingSystemType	string		room air conditioner	Yes		Type of cooling system
CoolingSystemFuel	string		electricity	Yes		Fuel type
CoolingCapacity	double	Btu/hr	>= 0 [158]	Yes		Cooling output capacity
FractionCoolLoadServed	double	frac	>= 0, <= 1 [159]	Yes		Fraction of cooling load served
AnnualCoolingEfficiency[Units="CEER" or Units="EER"]/Value	double	Btu/Wh	> 0	Yes		Rated cooling efficiency
IntegratedHeatingSystemFuel	string		See [160]	No	<none>	Fuel type of integrated heater

[158]

CoolingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[159]

The sum of all FractionCoolLoadServed (across all HVAC systems) must be less than or equal to 1.

[160]

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

If the room air conditioner has integrated heating, additional information is entered in CoolingSystem. Note that a room air conditioner with reverse cycle heating should be entered as a heat pump; see Room Air Conditioner w/ Reverse Cycle.

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

[161]

IntegratedHeatingSystemCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[162]

The sum of all FractionHeatLoadServed (across all HVAC systems) must be less than or equal to 1.

Packaged Terminal Air Conditioner

Each packaged terminal air conditioner (PTAC) is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/CoolingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
CoolingSystemType	string		packaged terminal air conditioner	Yes		Type of cooling system
CoolingSystemFuel	string		electricity	Yes		Fuel type
CoolingCapacity	double	Btu/hr	>= 0 [163]	Yes		Cooling output capacity
FractionCoolLoadServed	double	frac	>= 0, <= 1 [164]	Yes		Fraction of cooling load served
AnnualCoolingEfficiency[Units="CEER" or Units="EER"]/Value	double	Btu/Wh	> 0	Yes		Rated cooling efficiency
IntegratedHeatingSystemFuel	string		See [165]	No	<none>	Fuel type of integrated heater

[163]

CoolingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[164]

The sum of all FractionCoolLoadServed (across all HVAC systems) must be less than or equal to 1.

[165]

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

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

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

[166]

IntegratedHeatingSystemCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[167]

The sum of all FractionHeatLoadServed (across all HVAC systems) must be less than or equal to 1.

Evaporative Cooler

Each evaporative cooler is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/CoolingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
DistributionSystem	idref		See [168]	No		ID of attached distribution system
CoolingSystemType	string		evaporative cooler	Yes		Type of cooling system
CoolingSystemFuel	string		electricity	Yes		Fuel type
CoolingCapacity	double	Btu/hr	>= 0 [169]	Yes		Cooling output capacity
FractionCoolLoadServed	double	frac	>= 0, <= 1 [170]	Yes		Fraction of cooling load served

[168]

If DistributionSystem provided, HVACDistribution type must be Air Distribution (type: “regular velocity”) or Distribution System Efficiency (DSE).

[169]

CoolingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[170]

The sum of all FractionCoolLoadServed (across all HVAC systems) must be less than or equal to 1.

Mini-Split Air Conditioner

Each mini-split air conditioner is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/CoolingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
DistributionSystem	idref		See [171]	No		ID of attached distribution system
CoolingSystemType	string		mini-split	Yes		Type of cooling system
CoolingSystemFuel	string		electricity	Yes		Fuel type
CoolingCapacity	double	Btu/hr	>= 0 [172]	Yes		Cooling output capacity
CompressorType	string		variable speed	Yes		Type of compressor
FractionCoolLoadServed	double	frac	>= 0, <= 1 [173]	Yes		Fraction of cooling load served
AnnualCoolingEfficiency[Units="SEER2" or Units="SEER"]/Value	double	Btu/Wh	> 0	Yes		Rated cooling efficiency [174]
AnnualCoolingEfficiency[Units="EER2" or Units="EER"]/Value	double	Btu/Wh	> 0 [175]	Yes		Rated cooling efficiency [176]
extension/FanMotorType	string		See [177]	No	BPM	Blower fan model type
extension/FanPowerWattsPerCFM	double	W/cfm	>= 0 [178]	Yes		Blower fan efficiency at maximum fan speed [179]
extension/CoolingDesignAirflowCFM	double	cfm	>= 0	No	360 cfm/ton	Blower fan cooling design airflow rate [180]
extension/AirflowDefectRatio	double	frac	>= -0.9, <= 9	Yes		Deviation between design/installed airflow rates [181]
extension/ChargeDefectRatio	double	frac	-0.25, 0, 0.25	Yes		Deviation between design/installed refrigerant charges [182]

[171]

If provided, HVACDistribution type must be Air Distribution (type: “regular velocity”) or Distribution System Efficiency (DSE).

[172]

CoolingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[173]

The sum of all FractionCoolLoadServed (across all HVAC systems) must be less than or equal to 1.

[174]

If SEER provided, converted to SEER2 using ANSI/RESNET/ICC 301-2022 Addendum C, where SEER2 = SEER * 0.95 if ducted and SEER2 = SEER if ductless.

[175]

In addition, EER2 must be <= SEER2; EER must be < SEER.

[176]

If EER provided, converted to EER2 using ANSI/RESNET/ICC 301-2022 Addendum C, where EER2 = EER * 0.95 if ducted and EER2 = EER if ductless.

[177]

FanMotorType choices are “PSC” (Permanent Split Capacitor) and “BPM” (Brushless Permanent Magnet). If there is a heating system attached to the DistributionSystem, the heating and cooling systems cannot have different values for FanMotorType.

[178]

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

[179]

If the fan power is not measured, a value of 0.58 W/cfm should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

[180]

When the home’s blower fan airflow is measured according to ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems, the design airflow rate should be provided for either the cooling mode (CoolingDesignAirflowCFM) or heating mode (HeatingDesignAirflowCFM of heating system attached to the DistributionSystem).

[181]

AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect. A non-zero airflow defect can only be applied for systems attached to a distribution system. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information. If the airflow rate is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

[182]

ChargeDefectRatio is defined as (InstalledCharge - DesignCharge) / DesignCharge; a value of zero means no refrigerant charge defect. A non-zero charge defect should typically only be applied for systems that are charged on site, not for systems that have pre-charged line sets. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information. If the charge is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

Warning

HVAC installation grading inputs (i.e., FanPowerWattsPerCFM, AirflowDefectRatio, and ChargeDefectRatio) should be provided per the conditions specified in ANSI/RESNET/ACCA 310-2020. 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 (Shared)

Each shared chiller (serving multiple dwelling units) is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/CoolingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
DistributionSystem	idref		See [183]	Yes		ID of attached distribution system
IsSharedSystem	boolean		true	Yes		Whether it serves multiple dwelling units
NumberofUnitsServed	integer		> 1	Yes		Number of dwelling units served
CoolingSystemType	string		chiller	Yes		Type of cooling system
CoolingSystemFuel	string		electricity	Yes		Fuel type
CoolingCapacity	double	Btu/hr	>= 0	Yes		Total cooling output capacity
FractionCoolLoadServed	double	frac	>= 0, <= 1 [184]	Yes		Fraction of cooling load served
AnnualCoolingEfficiency[Units="kW/ton"]/Value	double	kW/ton	> 0	Yes		Rated cooling efficiency
extension/SharedLoopWatts	double	W	>= 0	Yes		Pumping and fan power serving the system
extension/SharedLoopMotorEfficiency	double	frac	> 0, < 1	No	0.85	Shared loop motor efficiency
extension/FanCoilWatts	double	W	>= 0	See [185]		Fan coil power

[183]

HVACDistribution type must be Hydronic Distribution (type: “radiator”, “baseboard”, “radiant floor”, “radiant ceiling”, or “water loop”) or Air Distribution (type: “fan coil”). If the chiller has “water loop” distribution, a Water-Loop-to-Air Heat Pump must also be specified.

[184]

The sum of all FractionCoolLoadServed (across all HVAC systems) must be less than or equal to 1.

[185]

FanCoilWatts only required if chiller connected to fan coil.

Cooling Tower (Shared)

Each shared cooling tower (serving multiple dwelling units) is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/CoolingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
DistributionSystem	idref		See [186]	Yes		ID of attached distribution system
IsSharedSystem	boolean		true	Yes		Whether it serves multiple dwelling units
NumberofUnitsServed	integer		> 1	Yes		Number of dwelling units served
CoolingSystemType	string		cooling tower	Yes		Type of cooling system
CoolingSystemFuel	string		electricity	Yes		Fuel type
FractionCoolLoadServed	double	frac	>= 0, <= 1 [187]	Yes		Fraction of cooling load served
extension/SharedLoopWatts	double	W	>= 0	Yes		Pumping and fan power serving the system
extension/SharedLoopMotorEfficiency	double	frac	> 0, < 1	No	0.85	Shared loop motor efficiency

[186]

HVACDistribution type must be Hydronic Distribution (type: “water loop”). A Water-Loop-to-Air Heat Pump must also be specified.

[187]

The sum of all FractionCoolLoadServed (across all HVAC systems) must be less than or equal to 1.

HPXML Heat Pumps

The following heat pump types can be modeled:

• Air-to-Air Heat Pump

• Mini-Split Heat Pump

• Packaged Terminal Heat Pump

• Room Air Conditioner w/ Reverse Cycle

• Ground-to-Air Heat Pump

• Water-Loop-to-Air Heat Pump

Air-to-Air Heat Pump

Each air-to-air heat pump is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatPump.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
DistributionSystem	idref		See [188]	Yes		ID of attached distribution system
HeatPumpType	string		air-to-air	Yes		Type of heat pump
HeatPumpFuel	string		electricity	Yes		Fuel type
HeatingCapacity	double	Btu/hr	>= 0 [189]	Yes		Heating output capacity at 47F
HeatingCapacity17F	double	Btu/hr	>= 0, <= HeatingCapacity	Yes		Heating output capacity at 17F
CoolingCapacity	double	Btu/hr	>= 0	Yes		Cooling output capacity
CompressorType	string		See [190]	Yes		Type of compressor
CompressorLockoutTemperature	double	F		No	See [191]	Minimum outdoor temperature for compressor operation
BackupType	string		integrated	No	<none>	Type of backup heating [192]
FractionHeatLoadServed	double	frac	>= 0, <= 1 [193]	Yes		Fraction of heating load served
FractionCoolLoadServed	double	frac	>= 0, <= 1 [194]	Yes		Fraction of cooling load served
AnnualCoolingEfficiency[Units="SEER2" or Units="SEER"]/Value	double	Btu/Wh	> 0	Yes		Rated cooling efficiency [195]
AnnualCoolingEfficiency[Units="EER2" or Units="EER"]/Value	double	Btu/Wh	> 0 [196]	Yes		Rated cooling efficiency [197]
AnnualHeatingEfficiency[Units="HSPF2" or Units="HSPF"]/Value	double	Btu/Wh	> 0	Yes		Rated heating efficiency [198]
extension/FanMotorType	string		See [199]	No	See [200]	Blower fan model type
extension/FanPowerWattsPerCFM	double	W/cfm	>= 0	Yes		Blower fan efficiency at maximum fan speed [201]
extension/HeatingDesignAirflowCFM	double	cfm	>= 0	No	See [202]	Blower fan heating design airflow rate [203]
extension/CoolingDesignAirflowCFM	double	cfm	>= 0	No	See [204]	Blower fan cooling design airflow rate [205]
extension/AirflowDefectRatio	double	frac	>= -0.9, <= 9	Yes		Deviation between design/installed airflow rates [206]
extension/ChargeDefectRatio	double	frac	-0.25, 0, 0.25	Yes		Deviation between design/installed refrigerant charges [207]
extension/EquipmentType	string		See [208]	No	split system	Equipment type only used for SEER/SEER2, EER/EER2, and HSPF/HSPF2 conversions

[188]

HVACDistribution type must be Air Distribution (type: “regular velocity”) or Distribution System Efficiency (DSE).

[189]

HeatingCapacity=-1 and CoolingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[190]

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

[191]

CompressorLockoutTemperature input is only allowed if BackupSystemFuel is “electricity” or not provided (i.e., it is not allowed for dual-fuel heat pumps). If not provided, CompressorLockoutTemperature defaults to -10F if CompressorType is “variable speed” otherwise 5F.

[192]

Additional backup inputs are described in Backup.

[193]

The sum of all FractionHeatLoadServed (across all HVAC systems) must be less than or equal to 1.

[194]

The sum of all FractionCoolLoadServed (across all HVAC systems) must be less than or equal to 1.

[195]

If SEER provided, converted to SEER2 using ANSI/RESNET/ICC 301-2022 Addendum C. For example, SEER2 = SEER * 0.95 if EquipmentType is “split system”.

[196]

In addition, EER2 must be <= SEER2; EER must be < SEER.

[197]

If EER provided, converted to EER2 using ANSI/RESNET/ICC 301-2022 Addendum C. For example, EER2 = EER * 0.95 if EquipmentType is “split system”.

[198]

If HSPF provided, converted to HSPF2 using ANSI/RESNET/ICC 301-2022 Addendum C. For example, HSPF2 = HSPF * 0.85 if EquipmentType is “split system”.

[199]

FanMotorType choices are “PSC” (Permanent Split Capacitor) and “BPM” (Brushless Permanent Magnet).

[200]

If FanMotorType is not provided, defaults to “PSC” if CompressorType is “single stage”, else “BPM”.

[201]

If the fan power is not measured, a value of 0.58 W/cfm should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

[202]

If HeatingDesignAirflowCFM not provided, defaults to cfm/ton based on CoolingDesignAirflowCFM if provided, else 360 cfm/ton.

[203]

When the home’s blower fan airflow is measured according to ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems, the design airflow rate should be provided for either the heating mode (HeatingDesignAirflowCFM) or cooling mode (CoolingDesignAirflowCFM).

[204]

If CoolingDesignAirflowCFM not provided, defaults to cfm/ton based on HeatingDesignAirflowCFM if provided, else 360 cfm/ton.

[205]

When the home’s blower fan airflow is measured according to ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems, the design airflow rate should be provided for either the cooling mode (CoolingDesignAirflowCFM) or heating mode (HeatingDesignAirflowCFM).

[206]

AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect. A non-zero airflow defect can only be applied for systems attached to a distribution system. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information. If the airflow rate is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

[207]

ChargeDefectRatio is defined as (InstalledCharge - DesignCharge) / DesignCharge; a value of zero means no refrigerant charge defect. A non-zero charge defect should typically only be applied for systems that are charged on site, not for systems that have pre-charged line sets. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information. If the charge is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

[208]

EquipmentType choices are “split system”, “packaged system”, “small duct high velocity system”, or “space constrained system”.

Warning

HVAC installation grading inputs (i.e., FanPowerWattsPerCFM, AirflowDefectRatio, and ChargeDefectRatio) should be provided per the conditions specified in ANSI/RESNET/ACCA 310-2020. 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

Each mini-split heat pump is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatPump. Each HeatPump should represent a single outdoor unit, whether connected to one indoor head or multiple indoor heads.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
DistributionSystem	idref		See [209]	No		ID of attached distribution system, if present
HeatPumpType	string		mini-split	Yes		Type of heat pump
HeatPumpFuel	string		electricity	Yes		Fuel type
HeatingCapacity	double	Btu/hr	>= 0 [210]	Yes		Heating output capacity at 47F
HeatingCapacity17F	double	Btu/hr	>= 0, <= HeatingCapacity	Yes		Heating output capacity at 17F
CoolingCapacity	double	Btu/hr	>= 0	Yes		Cooling output capacity
CompressorType	string		variable speed	Yes		Type of compressor
CompressorLockoutTemperature	double	F		No	See [211]	Minimum outdoor temperature for compressor operation
BackupType	string		integrated	No	<none>	Type of backup heating [212]
FractionHeatLoadServed	double	frac	>= 0, <= 1 [213]	Yes		Fraction of heating load served
FractionCoolLoadServed	double	frac	>= 0, <= 1 [214]	Yes		Fraction of cooling load served
AnnualCoolingEfficiency[Units="SEER2" or Units="SEER"]/Value	double	Btu/Wh	> 0	Yes		Rated cooling efficiency [215]
AnnualCoolingEfficiency[Units="EER2" or Units="EER"]/Value	double	Btu/Wh	> 0 [216]	Yes		Rated cooling efficiency [217]
AnnualHeatingEfficiency[Units="HSPF2" or Units="HSPF"]/Value	double	Btu/Wh	> 0	Yes		Rated heating efficiency [218]
extension/FanMotorType	string		See [219]	No	BPM	Blower fan model type
extension/FanPowerWattsPerCFM	double	W/cfm	>= 0	Yes		Blower fan efficiency at maximum fan speed [220]
extension/HeatingDesignAirflowCFM	double	cfm	>= 0	No	See [221]	Blower fan heating design airflow rate [222]
extension/CoolingDesignAirflowCFM	double	cfm	>= 0	No	See [223]	Blower fan cooling design airflow rate [224]
extension/AirflowDefectRatio	double	frac	>= -0.9, <= 9	Yes		Deviation between design/installed airflow rates [225]
extension/ChargeDefectRatio	double	frac	-0.25, 0, 0.25	Yes		Deviation between design/installed refrigerant charges [226]

[209]

If DistributionSystem provided, HVACDistribution type must be Air Distribution (type: “regular velocity”) or Distribution System Efficiency (DSE).

[210]

HeatingCapacity=-1 and CoolingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[211]

CompressorLockoutTemperature input is only allowed if BackupSystemFuel is “electricity” or not provided (i.e., it is not allowed for dual-fuel heat pumps). If not provided, CompressorLockoutTemperature defaults to -10F.

[212]

Additional backup inputs are described in Backup.

[213]

The sum of all FractionHeatLoadServed (across all HVAC systems) must be less than or equal to 1.

[214]

The sum of all FractionCoolLoadServed (across all HVAC systems) must be less than or equal to 1.

[215]

If SEER provided, converted to SEER2 using ANSI/RESNET/ICC 301-2022 Addendum C, where SEER2 = SEER * 0.95 if ducted and SEER2 = SEER if ductless.

[216]

In addition, EER2 must be <= SEER2; EER must be < SEER.

[217]

If EER provided, converted to EER2 using ANSI/RESNET/ICC 301-2022 Addendum C, where EER2 = EER * 0.95 if ducted and EER2 = EER if ductless.

[218]

If HSPF provided, converted to HSPF2 using ANSI/RESNET/ICC 301-2022 Addendum C, where HSPF2 = HSPF * 0.85 if ducted and HSPF2 = HSPF * 0.90 if ductless.

[219]

FanMotorType choices are “PSC” (Permanent Split Capacitor) and “BPM” (Brushless Permanent Magnet).

[220]

If the fan power is not measured, a value of 0.58 W/cfm should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

[221]

If HeatingDesignAirflowCFM not provided, defaults to cfm/ton based on CoolingDesignAirflowCFM if provided, else 360 cfm/ton.

[222]

When the home’s blower fan airflow is measured according to ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems, the design airflow rate should be provided for either the heating mode (HeatingDesignAirflowCFM) or cooling mode (CoolingDesignAirflowCFM).

[223]

If CoolingDesignAirflowCFM not provided, defaults to cfm/ton based on HeatingDesignAirflowCFM if provided, else 360 cfm/ton.

[224]

When the home’s blower fan airflow is measured according to ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems, the design airflow rate should be provided for either the cooling mode (CoolingDesignAirflowCFM) or heating mode (HeatingDesignAirflowCFM).

[225]

AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect. A non-zero airflow defect can only be applied for systems attached to a distribution system. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information. If the airflow rate is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

[226]

ChargeDefectRatio is defined as (InstalledCharge - DesignCharge) / DesignCharge; a value of zero means no refrigerant charge defect. A non-zero charge defect should typically only be applied for systems that are charged on site, not for systems that have pre-charged line sets. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information. If the charge is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

Warning

HVAC installation grading inputs (i.e., FanPowerWattsPerCFM, AirflowDefectRatio, and ChargeDefectRatio) should be provided per the conditions specified in ANSI/RESNET/ACCA 310-2020. 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

Each packaged terminal heat pump is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatPump.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
HeatPumpType	string		packaged terminal heat pump	Yes		Type of heat pump
HeatPumpFuel	string		electricity	Yes		Fuel type
HeatingCapacity	double	Btu/hr	>= 0 [227]	Yes		Heating output capacity at 47F
HeatingCapacity17F	double	Btu/hr	>= 0, <= HeatingCapacity	No		Heating output capacity at 17F
CoolingCapacity	double	Btu/hr	>= 0	Yes		Cooling output capacity
CompressorLockoutTemperature	double	F		No	See [228]	Minimum outdoor temperature for compressor operation
BackupType	string		integrated	No	<none>	Type of backup heating [229]
FractionHeatLoadServed	double	frac	>= 0, <= 1 [230]	Yes		Fraction of heating load served
FractionCoolLoadServed	double	frac	>= 0, <= 1 [231]	Yes		Fraction of cooling load served
AnnualCoolingEfficiency[Units="CEER" or Units="EER"]/Value	double	Btu/Wh	> 0	Yes		Rated cooling efficiency
AnnualHeatingEfficiency[Units="COP"]/Value	double	W/W	> 0	Yes		Rated heating efficiency

[227]

HeatingCapacity=-1 and CoolingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[228]

CompressorLockoutTemperature input is only allowed if BackupSystemFuel is “electricity” or not provided (i.e., it is not allowed for dual-fuel heat pumps). If not provided, CompressorLockoutTemperature defaults to 5F.

[229]

Additional backup inputs are described in Backup.

[230]

The sum of all FractionHeatLoadServed (across all HVAC systems) must be less than or equal to 1.

[231]

The sum of all FractionCoolLoadServed (across all HVAC systems) must be less than or equal to 1.

Room Air Conditioner w/ Reverse Cycle

Each room air conditioner with reverse cycle is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatPump.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
HeatPumpType	string		room air conditioner with reverse cycle	Yes		Type of heat pump
HeatPumpFuel	string		electricity	Yes		Fuel type
HeatingCapacity	double	Btu/hr	>= 0 [232]	Yes		Heating output capacity at 47F
HeatingCapacity17F	double	Btu/hr	>= 0, <= HeatingCapacity	No		Heating output capacity at 17F
CoolingCapacity	double	Btu/hr	>= 0	Yes		Cooling output capacity
CompressorLockoutTemperature	double	F		No	See [233]	Minimum outdoor temperature for compressor operation
BackupType	string		integrated	No	<none>	Type of backup heating [234]
FractionHeatLoadServed	double	frac	>= 0, <= 1 [235]	Yes		Fraction of heating load served
FractionCoolLoadServed	double	frac	>= 0, <= 1 [236]	Yes		Fraction of cooling load served
AnnualCoolingEfficiency[Units="CEER" or Units="EER"]/Value	double	Btu/Wh	> 0	Yes		Rated cooling efficiency
AnnualHeatingEfficiency[Units="COP"]/Value	double	W/W	> 0	Yes		Rated heating efficiency

[232]

HeatingCapacity=-1 and CoolingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[233]

CompressorLockoutTemperature input is only allowed if BackupSystemFuel is “electricity” or not provided (i.e., it is not allowed for dual-fuel heat pumps). If not provided, CompressorLockoutTemperature defaults to 5F.

[234]

Additional backup inputs are described in Backup.

[235]

The sum of all FractionHeatLoadServed (across all HVAC systems) must be less than or equal to 1.

[236]

The sum of all FractionCoolLoadServed (across all HVAC systems) must be less than or equal to 1.

Ground-to-Air Heat Pump

Each ground-to-air heat pump is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatPump.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
IsSharedSystem	boolean			Yes		Whether it has a shared hydronic circulation loop [237]
HeatPumpType	string		ground-to-air	Yes		Type of heat pump
HeatPumpFuel	string		electricity	Yes		Fuel type
DistributionSystem	idref		See [238]	Yes		ID of attached distribution system
HeatingCapacity	double	Btu/hr	>= 0 [239]	Yes		Heating output capacity
CoolingCapacity	double	Btu/hr	>= 0	Yes		Cooling output capacity
BackupType	string		integrated	No	<none>	Type of backup heating [240]
FractionHeatLoadServed	double	frac	>= 0, <= 1 [241]	Yes		Fraction of heating load served
FractionCoolLoadServed	double	frac	>= 0, <= 1 [242]	Yes		Fraction of cooling load served
AnnualCoolingEfficiency[Units="EER"]/Value	double	Btu/Wh	> 0	Yes		Rated cooling efficiency
AnnualHeatingEfficiency[Units="COP"]/Value	double	W/W	> 0	Yes		Rated heating efficiency
NumberofUnitsServed	integer		> 0	See [243]		Number of dwelling units served
extension/PumpPowerWattsPerTon	double	W/ton	>= 0	Yes		Pump power [244]
extension/SharedLoopWatts	double	W	>= 0	See [245]		Shared pump power [246]
extension/SharedLoopMotorEfficiency	double	frac	> 0, < 1	No	0.85 [247]	Shared loop motor efficiency
extension/FanMotorType	string		See [248]	No	See [249]	Blower fan model type
extension/FanPowerWattsPerCFM	double	W/cfm	>= 0	Yes		Blower fan efficiency at maximum fan speed [250]
extension/HeatingDesignAirflowCFM	double	cfm	>= 0	No	See [251]	Blower fan heating design airflow rate
extension/CoolingDesignAirflowCFM	double	cfm	>= 0	No	See [252]	Blower fan cooling design airflow rate
extension/AirflowDefectRatio	double	frac	>= -0.9, <= 9	Yes		Deviation between design/installed airflow rates [253]
extension/ChargeDefectRatio	double	frac	-0.25, 0, 0.25	Yes		Deviation between design/installed refrigerant charges [254]

[237]

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

[238]

HVACDistribution type must be Air Distribution (type: “regular velocity”) or Distribution System Efficiency (DSE).

[239]

HeatingCapacity=-1 and CoolingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

[240]

Additional backup inputs are described in Backup.

[241]

The sum of all FractionHeatLoadServed (across all HVAC systems) must be less than or equal to 1.

[242]

The sum of all FractionCoolLoadServed (across all HVAC systems) must be less than or equal to 1.

[243]

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

[244]

Pump power is calculated using PumpPowerWattsPerTon and the cooling capacity in tons, unless the system only provides heating, in which case the heating capacity in tons is used instead. Any pump power that is shared by multiple dwelling units should be included in SharedLoopWatts, not PumpPowerWattsPerTon, so that shared loop pump power attributed to the dwelling unit is calculated.

[245]

SharedLoopWatts only required if IsSharedSystem is true.

[246]

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

[247]

SharedLoopMotorEfficiency only used if IsSharedSystem is true.

[248]

FanMotorType choices are “PSC” (Permanent Split Capacitor) and “BPM” (Brushless Permanent Magnet).

[249]

If FanMotorType is not provided, defaults to “PSC” if COP <= 8.75/3.2, else “BPM”.

[250]

If the fan power is not measured, a value of 0.58 W/cfm should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

[251]

If HeatingDesignAirflowCFM not provided, defaults to cfm/ton based on CoolingDesignAirflowCFM if provided, else 360 cfm/ton.

[252]

If CoolingDesignAirflowCFM not provided, defaults to cfm/ton based on HeatingDesignAirflowCFM if provided, else 360 cfm/ton.

[253]

AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect. A non-zero airflow defect can only be applied for systems attached to a distribution system. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information. If the airflow rate is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

[254]

ChargeDefectRatio is defined as (InstalledCharge - DesignCharge) / DesignCharge; a value of zero means no refrigerant charge defect. A non-zero charge defect should typically only be applied for systems that are charged on site, not for systems that have pre-charged line sets. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information. If the charge is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC 301-2019 Addendum B.

Warning

HVAC installation grading inputs (i.e., FanPowerWattsPerCFM, AirflowDefectRatio, and ChargeDefectRatio) should be provided per the conditions specified in ANSI/RESNET/ACCA 310-2020. 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

Each water-loop-to-air heat pump is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatPump.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
DistributionSystem	idref		See [255]	Yes		ID of attached distribution system
HeatPumpType	string		water-loop-to-air	Yes		Type of heat pump
HeatPumpFuel	string		electricity	Yes		Fuel type
HeatingCapacity	double	Btu/hr	> 0	See [256]		Heating output capacity
CoolingCapacity	double	Btu/hr	> 0	See [257]		Cooling output capacity
BackupType	string		integrated	No	<none>	Type of backup heating [258]
AnnualCoolingEfficiency[Units="EER"]/Value	double	Btu/Wh	> 0	See [259]		Rated cooling efficiency
AnnualHeatingEfficiency[Units="COP"]/Value	double	W/W	> 0	See [260]		Rated heating efficiency

[255]

HVACDistribution type must be Air Distribution (type: “regular velocity”) or Distribution System Efficiency (DSE).

[256]

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

[257]

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

[258]

Additional backup inputs are described in Backup.

[259]

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

[260]

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

Note

If a water loop heat pump is specified, there must be at least one shared heating system (i.e., Boiler (In-Unit)) and/or one shared cooling system (i.e., Chiller (Shared) or Cooling Tower (Shared)) specified with water loop distribution.

Backup

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

Element	Type	Units	Constraints	Required	Default	Notes
BackupSystemFuel	string		See [261]	Yes		Integrated backup heating fuel type
BackupAnnualHeatingEfficiency[Units="Percent" or Units="AFUE"]/Value	double	frac	> 0, <= 1	Yes		Integrated backup heating efficiency
BackupHeatingCapacity	double	Btu/hr	>= 0 [262]	Yes		Integrated backup heating output capacity

[261]

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

[262]

BackupHeatingCapacity=-1 can be used to autosize the equipment for research purposes or to run tests (it should not be used for a real home).

HPXML HVAC Control

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

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

[263]

ControlType choices are “manual thermostat” or “programmable thermostat”.

HPXML HVAC Distribution

• Air Distribution

• Hydronic Distribution

• Distribution System Efficiency (DSE)

Note

There can be at most one heating system and one cooling system attached to a distribution system. See HPXML Heating Systems, HPXML Cooling Systems, and HPXML Heat Pumps for information on which distribution system type 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

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
DistributionSystemType/AirDistribution	element			Yes		Type of distribution system
DistributionSystemType/AirDistribution/AirDistributionType	string		See [264]	Yes		Type of air distribution
DistributionSystemType/AirDistribution/DuctLeakageMeasurement[DuctType="supply"]	element			See [265]		Supply duct leakage value
DistributionSystemType/AirDistribution/DuctLeakageMeasurement[DuctType="return"]	element			See [266]		Return duct leakage value
DistributionSystemType/AirDistribution/Ducts	element			No		Supply/return ducts; multiple are allowed [267]
DistributionSystemType/AirDistribution/NumberofReturnRegisters	integer		>= 0	See [268]		Number of return registers
ConditionedFloorAreaServed	double	ft2	> 0	See [269]		Conditioned floor area served

[264]

AirDistributionType choices are “regular velocity”, “gravity”, or “fan coil” and are further restricted based on attached HVAC system type (e.g., only “regular velocity” or “gravity” for a furnace, only “fan coil” for a shared boiler, etc.).

[265]

Supply duct leakage required if AirDistributionType is “regular velocity” or “gravity” and optional if AirDistributionType is “fan coil”.

[266]

Return duct leakage required if AirDistributionType is “regular velocity” or “gravity” and optional if AirDistributionType is “fan coil”.

[267]

Provide a Ducts element for each supply duct and each return duct.

[268]

NumberofReturnRegisters required only if AirDistribution/Ducts are present.

[269]

ConditionedFloorAreaServed required only if AirDistribution/Ducts are present.

Additional information is entered in each DuctLeakageMeasurement.

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

[270]

Units choices are “CFM25” or “CFM50”.

[271]

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

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

Additional information is entered in each Ducts.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
DuctType	string		See [272]	Yes		Supply or return ducts
DuctInsulationRValue	double	F-ft2-hr/Btu	>= 0	Yes		R-value of duct insulation [273]
DuctBuriedInsulationLevel	string		See [274]	No	not buried	Duct buried insulation level [275]
DuctLocation	string		See [276]	Yes		Duct location
FractionDuctArea and/or DuctSurfaceArea	double	frac or ft2	0-1 or >= 0 [277]	Yes [278]	See [279]	Duct fraction/surface area in location

[272]

DuctType choices are “supply” or “return”.

[273]

DuctInsulationRValue represents the nominal insulation R-value and should not include interior/exterior air films (i.e., use 0 for an uninsulated duct). For ducts buried in insulation (i.e., DuctBuriedInsulationLevel is any value but “not buried”), DuctInsulationRValue should only represent any surrounding insulation duct wrap and not the entire attic insulation R-value.

[274]

DuctBuriedInsulationLevel choices are “not buried”, “partially buried”, “fully buried”, or “deeply buried”.

[275]

Whether the ducts are buried in, e.g., attic loose-fill insulation. Partially buried ducts have insulation that does not cover the top of the ducts. Fully buried ducts have insulation that just covers the top of the ducts. Deeply buried ducts have insulation that continues above the top of the ducts. See the Building America Solution Center for more information.

[276]

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

[277]

The sum of all FractionDuctArea must each equal to 1, both for the supply side and return side.

[278]

If both are provided, DuctSurfaceArea will be used in the model.

[279]

If DuctSurfaceArea not provided, duct surface areas will be calculated based on ANSI/RESNET/ICC 301-2022:

- Supply duct area: 0.27 * ConditionedFloorAreaServed

- Return duct area: (if NumberofReturnRegisters < 6, 0.05 * NumberofReturnRegisters, 0.25 otherwise) * ConditionedFloorAreaServed

where each duct surface area will be FractionDuctArea multiplied by supply, or return, duct area.

Hydronic Distribution

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
DistributionSystemType/HydronicDistribution	element			Yes		Type of distribution system
DistributionSystemType/HydronicDistribution/HydronicDistributionType	string		See [280]	Yes		Type of hydronic distribution system

[280]

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

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. The DSE input is simply applied to heating/cooling energy use for every hour of the year.

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
DistributionSystemType/Other	string		DSE	Yes		Type of distribution system
AnnualHeatingDistributionSystemEfficiency	double	frac	> 0, <= 1	Yes		Seasonal distribution system efficiency for heating
AnnualCoolingDistributionSystemEfficiency	double	frac	> 0, <= 1	Yes		Seasonal distribution system efficiency for cooling

DSE values can be calculated from ASHRAE Standard 152.

HPXML Mechanical Ventilation Fans

The following mechanical ventilation fan types that provide ventilation to the whole dwelling unit can be modeled:

• Exhaust Only

• Supply Only

• Balanced

• Heat Recovery Ventilator (HRV)

• Energy Recovery Ventilator (ERV)

• Central Fan Integrated Supply (CFIS)

Exhaust Only

Each exhaust only fan is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
FanType	string		exhaust only	Yes		Type of ventilation system
TestedFlowRate or extension/FlowRateNotTested=true	double or boolean	cfm	>= 0 or true	See [281]		Flow rate or whether flow rate unmeasured
HoursInOperation	double	hrs/day	>= 0, <= 24	See [282]		Hours per day of operation
UsedForWholeBuildingVentilation	boolean		true	Yes		Ventilation fan use case [283]
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units [284]
FanPower or extension/FanPowerDefaulted=true	double or boolean	W	>= 0 or true	Yes		Fan power or whether fan power is unknown

[281]

Flow rate input required only if IsSharedSystem=false.

[282]

HoursInOperation required unless the VentilationFan refers to the supplemental fan of a Central Fan Integrated Supply (CFIS) system, in which case it is not allowed because the runtime is automatically calculated for each hour to maintain the hourly target ventilation rate.

[283]

All other UsedFor… elements (i.e., UsedForLocalVentilation, UsedForSeasonalCoolingLoadReduction, UsedForGarageVentilation) must be omitted or false.

[284]

Additional shared inputs are described in Shared System.

Supply Only

Each supply only fan is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
FanType	string		supply only	Yes		Type of ventilation system
TestedFlowRate or extension/FlowRateNotTested=true	double or boolean	cfm	>= 0 or true	See [285]		Flow rate or whether flow rate unmeasured
HoursInOperation	double	hrs/day	>= 0, <= 24	See [286]		Hours per day of operation
UsedForWholeBuildingVentilation	boolean		true	Yes		Ventilation fan use case [287]
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units [288]
FanPower or extension/FanPowerDefaulted=true	double or boolean	W	>= 0 or true	Yes		Fan power or whether fan power is unknown

[285]

Flow rate input required only if IsSharedSystem=false.

[286]

HoursInOperation required unless the VentilationFan refers to the supplemental fan of a Central Fan Integrated Supply (CFIS) system, in which case it is not allowed because the runtime is automatically calculated for each hour to maintain the hourly target ventilation rate.

[287]

All other UsedFor… elements (i.e., UsedForLocalVentilation, UsedForSeasonalCoolingLoadReduction, UsedForGarageVentilation) must be omitted or false.

[288]

Additional shared inputs are described in Shared System.

Balanced

Each balanced (supply and exhaust) fan is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
FanType	string		balanced	Yes		Type of ventilation system
TestedFlowRate or extension/FlowRateNotTested=true	double or boolean	cfm	>= 0 or true	See [289]		Flow rate or whether flow rate unmeasured
HoursInOperation	double	hrs/day	>= 0, <= 24	See [290]		Hours per day of operation
UsedForWholeBuildingVentilation	boolean		true	Yes		Ventilation fan use case [291]
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units [292]
FanPower or extension/FanPowerDefaulted=true	double or boolean	W	>= 0 or true	Yes		Fan power or whether fan power is unknown

[289]

Flow rate input required only if IsSharedSystem=false.

[290]

HoursInOperation required unless the VentilationFan refers to the supplemental fan of a Central Fan Integrated Supply (CFIS) system, in which case it is not allowed because the runtime is automatically calculated for each hour to maintain the hourly target ventilation rate.

[291]

All other UsedFor… elements (i.e., UsedForLocalVentilation, UsedForSeasonalCoolingLoadReduction, UsedForGarageVentilation) must be omitted or false.

[292]

Additional shared inputs are described in Shared System.

Heat Recovery Ventilator (HRV)

Each heat recovery ventilator (HRV) is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
FanType	string		heat recovery ventilator	Yes		Type of ventilation system
TestedFlowRate or extension/FlowRateNotTested=true	double or boolean	cfm	>= 0 or true	See [293]		Flow rate or whether flow rate unmeasured
HoursInOperation	double	hrs/day	>= 0, <= 24	See [294]		Hours per day of operation
UsedForWholeBuildingVentilation	boolean		true	Yes		Ventilation fan use case [295]
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units [296]
SensibleRecoveryEfficiency or AdjustedSensibleRecoveryEfficiency	double	frac	> 0, <= 1	Yes		(Adjusted) Sensible recovery efficiency [297]
FanPower or extension/FanPowerDefaulted=true	double or boolean	W	>= 0 or true	Yes		Fan power or whether fan power is unknown

[293]

Flow rate input required only if IsSharedSystem=false.

[294]

HoursInOperation required unless the VentilationFan refers to the supplemental fan of a Central Fan Integrated Supply (CFIS) system, in which case it is not allowed because the runtime is automatically calculated for each hour to maintain the hourly target ventilation rate.

[295]

All other UsedFor… elements (i.e., UsedForLocalVentilation, UsedForSeasonalCoolingLoadReduction, UsedForGarageVentilation) must be omitted or false.

[296]

Additional shared inputs are described in Shared System.

[297]

AdjustedSensibleRecoveryEfficiency (ASRE) is similar to SensibleRecoveryEfficiency (SRE), in that it reflects heating season performance, but excludes fan electric consumption. Since OpenStudio-ERI separately models fan electric consumption, ASRE is a preferable input to SRE because it can be directly used in the energy model.

Energy Recovery Ventilator (ERV)

Each energy recovery ventilator (ERV) is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
FanType	string		energy recovery ventilator	Yes		Type of ventilation system
TestedFlowRate or extension/FlowRateNotTested=true	double or boolean	cfm	>= 0 or true	See [298]		Flow rate or whether flow rate unmeasured
HoursInOperation	double	hrs/day	>= 0, <= 24	See [299]		Hours per day of operation
UsedForWholeBuildingVentilation	boolean		true	Yes		Ventilation fan use case [300]
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units [301]
TotalRecoveryEfficiency or AdjustedTotalRecoveryEfficiency	double	frac	> 0, <= 1	Yes		(Adjusted) Total recovery efficiency [302]
SensibleRecoveryEfficiency or AdjustedSensibleRecoveryEfficiency	double	frac	> 0, <= 1	Yes		(Adjusted) Sensible recovery efficiency [303]
FanPower or extension/FanPowerDefaulted=true	double or boolean	W	>= 0 or true	Yes		Fan power or whether fan power is unknown

[298]

Flow rate input required only if IsSharedSystem=false.

[299]

HoursInOperation required unless the VentilationFan refers to the supplemental fan of a Central Fan Integrated Supply (CFIS) system, in which case it is not allowed because the runtime is automatically calculated for each hour to maintain the hourly target ventilation rate.

[300]

All other UsedFor… elements (i.e., UsedForLocalVentilation, UsedForSeasonalCoolingLoadReduction, UsedForGarageVentilation) must be omitted or false.

[301]

Additional shared inputs are described in Shared System.

[302]

AdjustedTotalRecoveryEfficiency (ATRE) is similar to TotalRecoveryEfficiency (TRE), in that it reflects cooling season performance, but excludes fan electric consumption. Since OpenStudio-ERI separately models fan electric consumption, ATRE is a preferable input to TRE because it can be directly used in the energy model.

[303]

AdjustedSensibleRecoveryEfficiency (ASRE) is similar to SensibleRecoveryEfficiency (SRE), in that it reflects heating season performance, but excludes fan electric consumption. Since OpenStudio-ERI separately models fan electric consumption, ASRE is a preferable input to SRE because it can be directly used in the energy model.

Central Fan Integrated Supply (CFIS)

Each central fan integrated supply (CFIS) system is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan. A CFIS system is a supply ventilation system with an outdoor air inlet duct on the return side of a forced-air HVAC system.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
FanType	string		central fan integrated supply	Yes		Type of ventilation system
CFISControls/HasOutdoorAirControl	boolean			Yes		Presence of controls to block outdoor air when not ventilating [304]
CFISControls/AdditionalRuntimeOperatingMode	string		See [305]	Yes		How additional ventilation is provided (beyond when the HVAC system is running)
CFISControls/SupplementalFan	idref		See [306]	See [307]		The supplemental fan providing additional ventilation
CFISControls/extension/ControlType	string		See [308]	Yes		Primary air handler fan control strategy [309]
CFISControls/extension/SupplementalFanRunsWithAirHandlerFan	boolean			No [310]	false	Whether the supplemental fan also runs with the air handler fan [311]
TestedFlowRate or extension/FlowRateNotTested=true	double or boolean	cfm	>= 0 or true	Yes		Flow rate [312] or whether flow rate unmeasured
HoursInOperation	double	hrs/day	>= 0, <= 24	Yes		Hours per day of operation [313]
UsedForWholeBuildingVentilation	boolean		true	Yes		Ventilation fan use case [314]
AttachedToHVACDistributionSystem	idref		See [315]	Yes		ID of attached distribution system

[304]

For example, an electronically-controlled mechanical damper, or an in-line fan that substantially blocks the flow when not running.

[305]

AdditionalRuntimeOperatingMode choices are “air handler fan”, “supplemental fan”, or “none”.

[306]

SupplementalFan must reference another VentilationFan where UsedForWholeBuildingVentilation=true, IsSharedSystem=false, and FanType=”exhaust only” or “supply only”.

[307]

SupplementalFan only required if AdditionalRuntimeOperatingMode is “supplemental fan”.

[308]

ControlType choices are “optimized” or “timer; “timer” is only allowed if AdditionalRuntimeOperatingMode=”air handler fan”.

[309]

If ControlType=”optimized”, ventilation operation is assumed to take advantage of normal HVAC operation as much as possible, resulting in the lowest possible air handler fan energy use. If ControlType=”timer”, ventilation operation occurs at a fixed interval and may fully, partially, or not coincide with HVAC operation for a given hour, resulting in higher air handler fan energy use.

[310]

SupplementalFanRunsWithAirHandlerFan only applies when AdditionalRuntimeOperatingMode=”supplemental fan”.

[311]

If SupplementalFanRunsWithAirHandlerFan is true, in addition to its normal operation, the supplemental fan will also run simultaneously with the air handler fan when outdoor air is being brought in. This is typically used with a supplemental exhaust fan to provide balanced (supply + exhaust) airflow, though any additional runtime where the supplemental fan runs by itself will still be imbalanced.

[312]

The flow rate should equal the amount of outdoor air provided to the distribution system, not the total airflow through the distribution system.

[313]

HoursInOperation is combined with the flow rate to form the hourly target ventilation rate (e.g., inputs of 90 cfm and 8 hrs/day produce an hourly target ventilation rate of 30 cfm). In addition, if AdditionalRuntimeOperatingMode=”air handler fan”, it defines the minutes per hour that the air handler must provide ventilation (e.g., 8 hrs/day is treated as 20 mins/hr).

[314]

All other UsedFor… elements (i.e., UsedForLocalVentilation, UsedForSeasonalCoolingLoadReduction, UsedForGarageVentilation) must be omitted or false.

[315]

HVACDistribution type cannot be Hydronic Distribution.

Shared System

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

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

[316]

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

[317]

InUnitFlowRate must also be < RatedFlowRate.

[318]

PreHeating not allowed for exhaust only systems.

[319]

PreCooling not allowed for exhaust only systems.

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

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

[320]

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

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

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

[321]

Fuel only choice is “electricity”.

HPXML Whole House Fans

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
UsedForSeasonalCoolingLoadReduction	boolean		true	Yes		Ventilation fan use case [322]
RatedFlowRate	double	cfm	>= 0	Yes		Flow rate
FanPower	double	W	>= 0	Yes		Fan power

[322]

All other UsedFor… elements (i.e., UsedForWholeBuildingVentilation, UsedForLocalVentilation, UsedForGarageVentilation) must be omitted or false.

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

The following water heater types can be modeled:

• Conventional Storage

• Tankless

• Heat Pump

• Combi Boiler w/ Storage

• Combi Boiler w/ Tankless Coil

Conventional Storage

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
FuelType	string		See [323]	Yes		Fuel type
WaterHeaterType	string		storage water heater	Yes		Type of water heater
Location	string		See [324]	Yes		Water heater location
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units or shared laundry room
TankVolume	double	gal	> 0	Yes		Nominal tank volume
FractionDHWLoadServed	double	frac	>= 0, <= 1 [325]	Yes		Fraction of hot water load served [326]
HeatingCapacity	double	Btu/hr	> 0	No	See [327]	Heating output capacity
UniformEnergyFactor or EnergyFactor	double	frac	< 1	Yes		EnergyGuide label rated efficiency
FirstHourRating	double	gal/hr	> 0	See [328]		EnergyGuide label first hour rating
RecoveryEfficiency	double	frac	> 0, <= 1 [329]	No	See [330]	Recovery efficiency
WaterHeaterInsulation/Jacket/JacketRValue	double	F-ft2-hr/Btu	>= 0	No	0	R-value of additional tank insulation wrap
UsesDesuperheater	boolean			No	false	Presence of desuperheater? [331]
extension/NumberofBedroomsServed	integer		> NumberofBedrooms	See [332]		Number of bedrooms served directly or indirectly

[323]

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

[324]

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

[325]

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

[326]

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

[327]

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

[328]

FirstHourRating only required if UniformEnergyFactor provided.

[329]

RecoveryEfficiency must also be greater than the EnergyFactor (or UniformEnergyFactor).

[330]

If RecoveryEfficiency not provided, defaults as follows based on a regression analysis of AHRI certified water heaters:

- Electric: 0.98

- Non-electric, EnergyFactor < 0.75: 0.252 * EnergyFactor + 0.608

- Non-electric, EnergyFactor >= 0.75: 0.561 * EnergyFactor + 0.439

[331]

Additional desuperheater inputs are described in Desuperheater.

[332]

NumberofBedroomsServed only required if IsSharedSystem is true. Tank losses will be apportioned to the dwelling unit using its number of bedrooms divided by the total number of bedrooms served by the water heating system per ANSI/RESNET/ICC 301-2022. Each dwelling unit w/zero bedrooms should be counted as 1 bedroom – e.g., a value of 3 should be entered for a shared system serving 3 studio (zero bedroom) apartments.

Tankless

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
FuelType	string		See [333]	Yes		Fuel type
WaterHeaterType	string		instantaneous water heater	Yes		Type of water heater
Location	string		See [334]	Yes		Water heater location
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units or shared laundry room
FractionDHWLoadServed	double	frac	>= 0, <= 1 [335]	Yes		Fraction of hot water load served [336]
UniformEnergyFactor or EnergyFactor	double	frac	< 1	Yes		EnergyGuide label rated efficiency
UsesDesuperheater	boolean			No	false	Presence of desuperheater? [337]
extension/NumberofBedroomsServed	integer		> NumberofBedrooms	See [338]		Number of bedrooms served directly or indirectly

[333]

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

[334]

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

[335]

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

[336]

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

[337]

Additional desuperheater inputs are described in Desuperheater.

[338]

NumberofBedroomsServed only required if IsSharedSystem is true. Each dwelling unit w/zero bedrooms should be counted as 1 bedroom – e.g., a value of 3 should be entered for a shared system serving 3 studio (zero bedroom) apartments.

Heat Pump

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
FuelType	string		electricity	Yes		Fuel type
WaterHeaterType	string		heat pump water heater	Yes		Type of water heater
Location	string		See [339]	Yes		Water heater location
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units or shared laundry room
TankVolume	double	gal	> 0	Yes		Nominal tank volume
FractionDHWLoadServed	double	frac	>= 0, <= 1 [340]	Yes		Fraction of hot water load served [341]
UniformEnergyFactor or EnergyFactor	double	frac	> 1, <= 5	Yes		EnergyGuide label rated efficiency
FirstHourRating	double	gal/hr	> 0	See [342]		EnergyGuide label first hour rating
WaterHeaterInsulation/Jacket/JacketRValue	double	F-ft2-hr/Btu	>= 0	No	0	R-value of additional tank insulation wrap
UsesDesuperheater	boolean			No	false	Presence of desuperheater? [343]
extension/NumberofBedroomsServed	integer		> NumberofBedrooms	See [344]		Number of bedrooms served directly or indirectly
extension/HPWHInConfinedSpaceWithoutMitigation	boolean			Yes		Whether HPWH is installed in confined space without mitigation [345]
extension/HPWHContainmentVolume	double	ft3	> 0	See [346]		Containment volume of the space where HPWH is installed

[339]

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

[340]

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

[341]

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

[342]

FirstHourRating only required if UniformEnergyFactor provided.

[343]

Additional desuperheater inputs are described in Desuperheater.

[344]

NumberofBedroomsServed only required if IsSharedSystem is true. Tank losses will be apportioned to the dwelling unit using its number of bedrooms divided by the total number of bedrooms served by the water heating system per ANSI/RESNET/ICC 301-2022. Each dwelling unit w/zero bedrooms should be counted as 1 bedroom – e.g., a value of 3 should be entered for a shared system serving 3 studio (zero bedroom) apartments.

[345]

Mitigation approaches include sufficient enclosed volume or connection to conditioned space with, e.g, ducting, grills, door undercuts, or louvers per RESNET HERS Addendum 77. If true, a COP adjustment based on extension/HPWHContainmentVolume will be applied.

[346]

HPWHContainmentVolume only required if HPWHInConfinedSpaceWithoutMitigation is true.

Combi Boiler w/ Storage

Each combination boiler w/ storage tank (sometimes referred to as an indirect water heater) is entered as a /HPXML/Building/BuildingDetails/Systems/WaterHeating/WaterHeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
WaterHeaterType	string		space-heating boiler with storage tank	Yes		Type of water heater
Location	string		See [347]	Yes		Water heater location
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units or shared laundry room
TankVolume	double	gal	> 0	Yes		Nominal volume of the storage tank
FractionDHWLoadServed	double	frac	>= 0, <= 1 [348]	Yes		Fraction of hot water load served [349]
WaterHeaterInsulation/Jacket/JacketRValue	double	F-ft2-hr/Btu	>= 0	No	0	R-value of additional storage tank insulation wrap
StandbyLoss[Units="F/hr"]/Value	double	F/hr	> 0	No	See [350]	Storage tank standby losses
RelatedHVACSystem	idref		See [351]	Yes		ID of boiler
extension/NumberofBedroomsServed	integer		> NumberofBedrooms	See [352]		Number of bedrooms served directly or indirectly

[347]

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

[348]

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

[349]

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

[350]

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

[351]

RelatedHVACSystem must reference a HeatingSystem of type Boiler.

[352]

NumberofBedroomsServed only required if IsSharedSystem is true. Tank losses will be apportioned to the dwelling unit using its number of bedrooms divided by the total number of bedrooms served by the water heating system per ANSI/RESNET/ICC 301-2022. Each dwelling unit w/zero bedrooms should be counted as 1 bedroom – e.g., a value of 3 should be entered for a shared system serving 3 studio (zero bedroom) apartments.

Combi Boiler w/ Tankless Coil

Each combination boiler w/ tankless coil is entered as a /HPXML/Building/BuildingDetails/Systems/WaterHeating/WaterHeatingSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
WaterHeaterType	string		space-heating boiler with tankless coil	Yes		Type of water heater
Location	string		See [353]	Yes		Water heater location
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units or shared laundry room
FractionDHWLoadServed	double	frac	>= 0, <= 1 [354]	Yes		Fraction of hot water load served [355]
RelatedHVACSystem	idref		See [356]	Yes		ID of boiler
extension/NumberofBedroomsServed	integer		> NumberofBedrooms	See [357]		Number of bedrooms served directly or indirectly

[353]

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

[354]

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

[355]

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

[356]

RelatedHVACSystem must reference a HeatingSystem (Boiler).

[357]

NumberofBedroomsServed only required if IsSharedSystem is true. Each dwelling unit w/zero bedrooms should be counted as 1 bedroom – e.g., a value of 3 should be entered for a shared system serving 3 studio (zero bedroom) apartments.

Desuperheater

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

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

[358]

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

HPXML Hot Water Distribution

A single hot water distribution system must be described:

• Standard

• Recirculation (In-Unit)

• Recirculation (Shared)

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

A standard hot water distribution system is entered as a /HPXML/Building/BuildingDetails/Systems/WaterHeating/HotWaterDistribution.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
SystemType/Standard	element			Yes		Type of in-unit distribution system serving the dwelling unit
SystemType/Standard/PipingLength	double	ft	> 0	Yes		Length of piping [359]
PipeInsulation/PipeRValue	double	F-ft2-hr/Btu	>= 0	Yes		Pipe insulation R-value
DrainWaterHeatRecovery	element			No	<none>	Presence of drain water heat recovery device [360]

[359]

PipingLength is the length of hot water piping from the hot water heater (or from a shared recirculation loop serving multiple dwelling units) to the farthest hot water fixture, measured longitudinally from plans, assuming the hot water piping does not run diagonally, plus 10 feet of piping for each floor level, plus 5 feet of piping for unconditioned basements (if any).

[360]

Additional drain water heat recovery inputs are described in Drain Water Heat Recovery.

Recirculation (In-Unit)

An in-unit recirculation hot water distribution system is entered as a /HPXML/Building/BuildingDetails/Systems/WaterHeating/HotWaterDistribution.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
SystemType/Recirculation	element			Yes		Type of in-unit distribution system serving the dwelling unit
SystemType/Recirculation/ControlType	string		See [361]	Yes		Recirculation control type
SystemType/Recirculation/RecirculationPipingLoopLength	double	ft	> 0	Yes		Recirculation piping loop length [362]
SystemType/Recirculation/BranchPipingLength	double	ft	> 0	Yes		Branch piping length [363]
SystemType/Recirculation/PumpPower	double	W	>= 0	Yes		Recirculation pump power
PipeInsulation/PipeRValue	double	F-ft2-hr/Btu	>= 0	Yes		Pipe insulation R-value
DrainWaterHeatRecovery	element			No	<none>	Presence of drain water heat recovery device [364]

[361]

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

- manual demand control: The pump only runs when a user presses a button indicating they are about to use hot water.

- presence sensor demand control: The pump only runs when a sensor detects someone is present at the faucet.

- temperature: The pump runs based on monitoring temperature at some point in the system.

- timer: The pump is controlled by a timer.

- no control: The pump runs continuously.

[362]

RecirculationPipingLoopLength is the recirculation loop length including both supply and return sides, measured longitudinally from plans, assuming the hot water piping does not run diagonally, plus 20 feet of piping for each floor level greater than one plus 10 feet of piping for unconditioned basements.

[363]

BranchPipingLength is the length of the branch hot water piping from the recirculation loop to the farthest hot water fixture from the recirculation loop, measured longitudinally from plans, assuming the branch hot water piping does not run diagonally.

[364]

Additional drain water heat recovery inputs are described in Drain Water Heat Recovery.

Recirculation (Shared)

A shared recirculation hot water distribution system (serving multiple dwelling units) is entered as a /HPXML/Building/BuildingDetails/Systems/WaterHeating/HotWaterDistribution.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
SystemType/Standard	element			Yes		Type of in-unit distribution system serving the dwelling unit
SystemType/Standard/PipingLength	double	ft	> 0	Yes		Length of piping [365]
PipeInsulation/PipeRValue	double	F-ft2-hr/Btu	>= 0	Yes		Pipe insulation R-value
DrainWaterHeatRecovery	element			No	<none>	Presence of drain water heat recovery device [366]
extension/SharedRecirculation/NumberofBedroomsServed	integer		> NumberofBedrooms	Yes [367]		Number of bedrooms served
extension/SharedRecirculation/PumpPower	double	W	>= 0	Yes		Shared recirculation pump power
extension/SharedRecirculation/MotorEfficiency	double	frac	> 0, < 1	No	0.85	Shared recirculation motor efficiency
extension/SharedRecirculation/ControlType	string		See [368]	Yes		Shared recirculation control type

[365]

PipingLength is the length of hot water piping from the shared recirculation loop to the farthest hot water fixture, measured longitudinally from plans, assuming the hot water piping does not run diagonally, plus 10 feet of piping for each floor level, plus 5 feet of piping for unconditioned basements (if any).

[366]

Additional drain water heat recovery inputs are described in Drain Water Heat Recovery.

[367]

Recirculation pump energy will be apportioned to the dwelling unit using its number of bedrooms divided by the total number of bedrooms served by the recirculation system per ANSI/RESNET/ICC 301-2022. Each dwelling unit w/zero bedrooms should be counted as 1 bedroom – e.g., a value of 3 should be entered for a shared system serving 3 studio (zero bedroom) apartments.

[368]

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

Note

The shared recirculation system is required to have a standard in-unit hot water distribution system; stacked recirculation systems (i.e., shared recirculation loop plus an additional in-unit recirculation system) are more likely to indicate input errors than reflect an actual real-world scenario.

Drain Water Heat Recovery

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

Element	Type	Units	Constraints	Required	Default	Notes
FacilitiesConnected	string		See [369]	Yes		Specifies which facilities are connected
EqualFlow	boolean			Yes		Specifies how the DHWR is configured [370]
Efficiency	double	frac	> 0, <= 1	Yes		Efficiency according to CSA 55.1

[369]

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

[370]

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

HPXML Water Fixtures

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

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

[371]

WaterFixtureType choices are “shower head” or “faucet”. If the shower stall has multiple shower heads that operate simultaneously, combine them as a single entry.

[372]

LowFlow should be true if the fixture’s flow rate (gpm) is <= 2.0. Where a shower stall has multiple shower heads that operate simultaneously, the sum of their flows must be <= 2.0.

HPXML Solar Thermal

A single solar hot water system can be described with either simple or detailed inputs.

• Simple Inputs

• Detailed Inputs

It is recommended to use detailed inputs and allow EnergyPlus to calculate the solar contribution to the hot water load; the simple inputs are provided if equivalent calculations are performed in another software tool.

Simple Inputs

A simple solar hot water system is entered as a /HPXML/Building/BuildingDetails/Systems/SolarThermal/SolarThermalSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
SystemType	string		hot water	Yes		Type of solar thermal system
SolarFraction	double	frac	> 0, <= 0.99	Yes		Solar fraction [373]
ConnectedTo	idref		See [374]	No [375]	<none>	Connected water heater

[373]

Portion of total conventional hot water heating load (delivered energy plus tank standby losses). Can be obtained from Directory of SRCC OG-300 Solar Water Heating System Ratings or NLR’s System Advisor Model or equivalent.

[374]

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

[375]

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

Warning

The solar fraction will reduce the hot water load equally for every EnergyPlus timestep.

Detailed Inputs

A detailed solar hot water system is entered as a /HPXML/Building/BuildingDetails/Systems/SolarThermal/SolarThermalSystem.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
SystemType	string		hot water	Yes		Type of solar thermal system
CollectorArea	double	ft2	> 0	Yes		Area
CollectorLoopType	string		See [376]	Yes		Loop type
CollectorType	string		See [377]	Yes		System type
CollectorAzimuth	integer	deg	>= 0, <= 359	Yes		Azimuth (clockwise from North)
CollectorTilt	double	deg	>= 0, <= 90	Yes		Tilt relative to horizontal
CollectorRatedOpticalEfficiency	double	frac	> 0, < 1	Yes		Rated optical efficiency [378]
CollectorRatedThermalLosses	double	Btu/hr-ft2-F	> 0	Yes		Rated thermal losses [379]
StorageVolume	double	gal	> 0	Yes		Hot water storage volume
ConnectedTo	idref		See [380]	Yes		Connected water heater

[376]

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

[377]

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

[378]

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

[379]

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

[380]

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

HPXML Photovoltaics

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

Many of the inputs are adopted from the PVWatts model.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units
Location	string		See [381]	Yes		Mounting location
ModuleType	string		See [382]	Yes		Type of module
Tracking	string		See [383]	Yes		Type of tracking
ArrayAzimuth	integer	deg	>= 0, <= 359	Yes		Direction panels face (clockwise from North)
ArrayTilt	double	deg	>= 0, <= 90	Yes		Tilt relative to horizontal
MaxPowerOutput	double	W	>= 0	Yes		Peak power
SystemLossesFraction	double	frac	>= 0, <= 1	Yes		System losses [384]
AttachedToInverter	idref		See [385]	Yes		ID of attached inverter
extension/NumberofBedroomsServed	integer		> NumberofBedrooms	See [386]		Number of bedrooms served

[381]

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

[382]

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

[383]

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

[384]

System losses due to soiling, shading, snow, mismatch, wiring, degradation, etc. Default from the PVWatts documentation is 0.14, which breaks down as follows. Note that the total loss (14%) is not the sum of the individual losses but is calculated by multiplying the reduction due to each loss.

- Soiling: 2%

- Shading: 3%

- Snow: 0%

- Mismatch: 2%

- Wiring: 2%

- Connections: 0.5%

- Light-induced degradation: 1.5%

- Nameplate rating: 1%

- Age: 0%

- Availability: 3%

[385]

AttachedToInverter must reference an Inverter.

[386]

NumberofBedroomsServed only required if IsSharedSystem is true. PV generation will be apportioned to the dwelling unit using its number of bedrooms divided by the total number of bedrooms served by the PV system per ANSI/RESNET/ICC 301-2019.

Each inverter inverter is entered as a /HPXML/Building/BuildingDetails/Systems/Photovoltaics/Inverter.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
InverterEfficiency	double	frac	> 0, <= 1	Yes		Inverter efficiency [387]

[387]

If there are multiple inverters with different efficiencies, a PV size weighted-average efficiency will be used due to EnergyPlus limitations. The PVWatts default is 0.96.

HPXML Batteries

A single battery can be entered as a /HPXML/Building/BuildingDetails/Systems/Batteries/Battery.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
IsSharedSystem	boolean			Yes		Whether it serves multiple dwelling units
Location	string		See [388]	No	See [389]	Location
BatteryType	string		See [390]	Yes		Battery type
UsableCapacity[Units="kWh"]/Value	double	kWh	>= 0	Yes		Usable capacity
RatedPowerOutput	double	W	>= 0	Yes		Power output under non-peak conditions
RoundTripEfficiency	double	frac	> 0, <= 1	Yes		Round trip efficiency
extension/NumberofBedroomsServed	integer		> NumberofBedrooms	See [391]		Number of bedrooms served

[388]

Location choices are “conditioned space”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “attic - vented”, “attic - unvented”, “garage”, or “outside”.

[389]

If Location not provided, defaults to “garage” if a garage is present, otherwise “outside”.

[390]

BatteryType only choice is “Li-ion”.

[391]

NumberofBedroomsServed only required if IsSharedSystem is true. Battery charging/discharging will be apportioned to the dwelling unit using its number of bedrooms divided by the total number of bedrooms served by the battery per ANSI/RESNET/ICC 301-2022 Addendum C.

Note

The battery will charge if PV production is greater than the building electrical load and the battery is below its maximum capacity. The battery will discharge if the building electrical load is greater than the PV production and the battery is above its minimum capacity. A battery in a home without PV is not modeled.

For ERI calculations, batteries will result in a small penalty because ERI is calculated using annual energy consumption and batteries increase annual electricity consumption (due to round trip efficiency). For CO2e Index calculations, batteries can result in a credit because CO2e Index is calculated using hourly electricity emissions factors and batteries shift when electricity consumption occurs.

HPXML Generators

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

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

[392]

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

[393]

AnnualOutputkWh must also be < AnnualConsumptionkBtu*3.412 (i.e., the generator must consume more energy than it produces).

[394]

NumberofBedroomsServed only required if IsSharedSystem is true. Annual consumption and annual production will be apportioned to the dwelling unit using its number of bedrooms divided by the total number of bedrooms served by the generator per ANSI/RESNET/ICC 301-2019.

Note

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

HPXML Appliances

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

HPXML Clothes Washer

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
IsSharedAppliance	boolean			Yes		Whether it serves multiple dwelling units [395]
Location	string		See [396]	Yes		Location
IntegratedModifiedEnergyFactor or ModifiedEnergyFactor	double	ft3/kWh/cyc	> 0	Yes		Efficiency [397]
RatedAnnualkWh	double	kWh/yr	> 0	Yes		EnergyGuide label annual consumption
LabelElectricRate	double	$/kWh	> 0	Yes		EnergyGuide label electricity rate
LabelGasRate	double	$/therm	> 0	Yes		EnergyGuide label natural gas rate
LabelAnnualGasCost	double	$	> 0	Yes		EnergyGuide label annual gas cost
LabelUsage	double	cyc/wk	> 0	Yes		EnergyGuide label number of cycles (not used if 301 version < 2019A)
Capacity	double	ft3	> 0	Yes		Clothes washer volume

[395]

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

[396]

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

[397]

If ModifiedEnergyFactor (MEF) provided instead of IntegratedModifiedEnergyFactor (IMEF), it will be converted using the Interpretation on ANSI/RESNET 301-2014 Clothes Washer IMEF: IMEF = (MEF - 0.503) / 0.95. IMEF may be found using the manufacturer’s data sheet, the California Energy Commission Appliance Database, the EPA ENERGY STAR website, or another reputable source.

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

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

[398]

AttachedToWaterHeatingSystem must reference a WaterHeatingSystem; AttachedToHotWaterDistribution must reference a HotWaterDistribution.

Note

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

HPXML Clothes Dryer

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
IsSharedAppliance	boolean			Yes		Whether it serves multiple dwelling units [399]
Location	string		See [400]	Yes		Location
FuelType	string		See [401]	Yes		Fuel type
CombinedEnergyFactor or EnergyFactor	double	lb/kWh	> 0	Yes		EnergyGuide label efficiency [402]
ControlType	string		See [403]	See [404]		Type of controls
Vented	boolean			Yes		Whether dryer is vented

[399]

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

[400]

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

[401]

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

[402]

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

[403]

ControlType choices are “timer” or “moisture”.

[404]

ControlType only required if ERI Version < 2019A.

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

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

Note

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

HPXML Dishwasher

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
IsSharedAppliance	boolean			Yes		Whether it serves multiple dwelling units [405]
Location	string		See [406]	Yes		Location
RatedAnnualkWh or EnergyFactor	double	kWh/yr or #	> 0	Yes		EnergyGuide label consumption/efficiency [407]
PlaceSettingCapacity	integer	#	> 0	Yes		Number of place settings
LabelElectricRate	double	$/kWh	> 0	Yes		EnergyGuide label electricity rate (not used if 301 version < 2019A)
LabelGasRate	double	$/therm	> 0	Yes		EnergyGuide label natural gas rate (not used if 301 version < 2019A)
LabelAnnualGasCost	double	$	> 0	Yes		EnergyGuide label annual gas cost (not used if 301 version < 2019A)
LabelUsage	double	cyc/wk	> 0	Yes		EnergyGuide label number of cycles (not used if 301 version < 2019A)

[405]

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

[406]

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

[407]

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

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

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

[408]

AttachedToWaterHeatingSystem must reference a WaterHeatingSystem; AttachedToHotWaterDistribution must reference a HotWaterDistribution.

Note

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

HPXML Refrigerators

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

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

[409]

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

Note

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

HPXML Dehumidifier

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
Type	string		See [410]	Yes		Type of dehumidifier
Location	string		See [411]	Yes		Location of dehumidifier
Capacity	double	pints/day	> 0	Yes		Dehumidification capacity
IntegratedEnergyFactor or EnergyFactor	double	liters/kWh	> 0	Yes		Rated efficiency
FractionDehumidificationLoadServed	double	frac	>= 0, <= [412]	Yes		Fraction of dehumidification load served

[410]

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

[411]

Location only choice is “conditioned space”.

[412]

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

Note

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

Note

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

HPXML Cooking Range/Oven

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

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

[413]

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

[414]

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

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

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

HPXML Lighting & Ceiling Fans

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

HPXML Lighting

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

• LightingType: ‘LightEmittingDiode’, ‘CompactFluorescent’, and ‘FluorescentTube’

• Location: ‘interior’, ‘exterior’, and ‘garage’ (garage lighting groups only required if a garage is present)

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

Information is entered in each LightingGroup.

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
LightingType	element		See [415]	Yes		Lighting type
Location	string		See [416]	Yes		Lighting location [417]
FractionofUnitsInLocation	double	frac	>= 0, <= 1 [418]	Yes		Fraction of light fixtures in the location with the specified lighting type

[415]

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

[416]

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

[417]

Garage lighting location is ignored if the HPXML file has no garage specified elsewhere.

[418]

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

HPXML Ceiling Fans

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

Element	Type	Units	Constraints	Required	Default	Notes
SystemIdentifier	id			Yes		Unique identifier
Airflow[FanSpeed="medium"]/Efficiency and/or LabelEnergyUse	double	cfm/W or W	> 0	Yes		Efficiency at medium speed or EnergyGuide label average energy use
Count	integer		> 0	Yes		Number of similar ceiling fans

HPXML Locations

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

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

[419]

OpenStudio-ERI does not model “conditioned” or “heated” garages. Many conditioned garages are not conditioned 24/7, rather they are only conditioned for short periods when occupants are in them and turn on the space conditioning equipment, so it is best to assume an unconditioned garage. However, if a garage was converted into livable space, then “conditioned space” should be used instead.

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.