Workflow Inputs
OpenStudio-HPXML 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.
Using HPXML
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 EnergyPlus simulations.
HPXML files submitted to OpenStudio-HPXML undergo a two step validation process:
Validation against the HPXML Schema
The HPXML XSD Schema can be found at
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.
Validation using Schematron
The Schematron document for the EnergyPlus use case can be found at
HPXMLtoOpenStudio/resources/hpxml_schematron/EPvalidator.xml
. Schematron is a rule-based validation language, expressed in XML using XPath expressions, for validating the presence or absence of inputs in XML files. As opposed to an XSD Schema, a Schematron document validates constraints and requirements based on conditionals and other logical statements. For example, if an element is specified with a particular value, the applicable enumerations of another element may change.
OpenStudio-HPXML automatically validates the HPXML file against both the XSD and Schematron documents and reports any validation errors, but software developers may find it beneficial to also integrate validation into their software.
Input Defaults
A large number of elements in the HPXML file are optional and can be defaulted. Default values, equations, and logic are described throughout this documentation.
For example, suppose a HPXML file has a refrigerator defined as follows:
<Refrigerator>
<SystemIdentifier id='Refrigerator1'/>
</Refrigerator>
Default values would be used for the refrigerator energy use, location, and schedule:
<Refrigerator>
<SystemIdentifier id='Refrigerator1'/>
<Location dataSource='software'>conditioned space</Location>
<RatedAnnualkWh dataSource='software'>691.0</RatedAnnualkWh>
<PrimaryIndicator dataSource='software'>true</PrimaryIndicator>
<extension>
<UsageMultiplier dataSource='software'>1.0</UsageMultiplier>
<WeekdayScheduleFractions dataSource='software'>0.040, 0.039, 0.038, 0.037, 0.036, 0.036, 0.038, 0.040, 0.041, 0.041, 0.040, 0.040, 0.042, 0.042, 0.042, 0.041, 0.044, 0.048, 0.050, 0.048, 0.047, 0.046, 0.044, 0.041</WeekdayScheduleFractions>
<WeekendScheduleFractions dataSource='software'>0.040, 0.039, 0.038, 0.037, 0.036, 0.036, 0.038, 0.040, 0.041, 0.041, 0.040, 0.040, 0.042, 0.042, 0.042, 0.041, 0.044, 0.048, 0.050, 0.048, 0.047, 0.046, 0.044, 0.041</WeekendScheduleFractions>
<MonthlyScheduleMultipliers dataSource='software'>0.837, 0.835, 1.084, 1.084, 1.084, 1.096, 1.096, 1.096, 1.096, 0.931, 0.925, 0.837</MonthlyScheduleMultipliers>
</extension>
</Refrigerator>
These defaults will be reflected in the EnergyPlus simulation results.
Note
The OpenStudio-HPXML workflow generally treats missing elements differently than missing values.
For example, if there is no Refrigerator
element defined, the simulation will proceed without refrigerator energy use.
On the other hand, if there is a Refrigerator
element but with no values defined (i.e., no Location
or RatedAnnualkWh
), it is assumed that a refrigerator exists but its properties are unknown, so they will be defaulted in the model.
See HPXML Defaults for information on how default values can be inspected.
HPXML Software Info
High-level simulation inputs are entered in /HPXML/SoftwareInfo
.
HPXML Simulation Control
EnergyPlus simulation controls are entered in /HPXML/SoftwareInfo/extension/SimulationControl
.
Element
Type
Units
Constraints
Required
Default
Description
Timestep
integer
minutes
Divisor of 60
No
60 (1 hour)
Timestep
BeginMonth
integer
>= 1, <= 12 [1]
No
1 (January)
Run period start date
BeginDayOfMonth
integer
>= 1, <= 31
No
1
Run period start date
EndMonth
integer
>= 1, <= 12
No
12 (December)
Run period end date
EndDayOfMonth
integer
>= 1, <= 31
No
31
Run period end date
CalendarYear
integer
> 1600 [2]
No
2007 (for TMY weather) [3]
Calendar year (for start day of week)
TemperatureCapacitanceMultiplier
double
> 0
No
1.0
Multiplier on air heat capacitance [4]
HPXML Emissions Scenarios
One or more emissions scenarios can be entered as an /HPXML/SoftwareInfo/extension/EmissionsScenarios/EmissionsScenario
.
If not entered, emissions 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)
EmissionsType
string
See [5]
Yes
Type of emissions (e.g., CO2e)
EmissionsFactor
element
See [6]
Emissions factor(s) for a given fuel type; multiple are allowed
[5] EmissionsType can be anything. But if certain values are provided (e.g., “CO2e”), then some emissions factors can be defaulted as described further below.
[6] EmissionsFactor is required for electricity and optional for all non-electric fuel types.
See Annual Outputs and Timeseries Outputs for descriptions of how the calculated emissions appear in the output files.
Electricity Emissions
For each scenario, electricity emissions factors must be entered as an /HPXML/SoftwareInfo/extension/EmissionsScenarios/EmissionsScenario/EmissionsFactor
.
Element
Type
Units
Constraints
Required
Default
Notes
FuelType
string
electricity
Yes
Emissions factor fuel type
Units
string
See [7]
Yes
Emissions factor units
Value
orScheduleFilePath
double or string
See [8]
Yes
Emissions factor annual value or schedule file with hourly values
[7] Units choices are “lb/MWh” and “kg/MWh”.
[8] ScheduleFilePath must point to a CSV file with 8760 numeric hourly values. Sources of electricity emissions data include NREL’s Cambium database and EPA’s eGRID.
If an electricity schedule file is used, additional information can be entered in the /HPXML/SoftwareInfo/extension/EmissionsScenarios/EmissionsScenario/EmissionsFactor
.
Element
Type
Units
Constraints
Required
Default
Notes
NumberofHeaderRows
integer
#
>= 0
No
0
Number of header rows in the schedule file
ColumnNumber
integer
#
>= 1
No
1
Column number of the data in the schedule file
Fuel Emissions
For each scenario, fuel emissions factors can be optionally entered as an /HPXML/SoftwareInfo/extension/EmissionsScenarios/EmissionsScenario/EmissionsFactor
.
Element
Type
Units
Constraints
Required
Default
Notes
FuelType
string
See [9]
Yes
Emissions factor fuel type
Units
string
See [10]
Yes
Emissions factor units
Value
double
Yes
Emissions factor annual value
[9] FuelType choices are “natural gas”, “propane”, “fuel oil”, “coal”, “wood”, and “wood pellets”.
[10] Units choices are “lb/MBtu” and “kg/MBtu” (million Btu).
Default Values
If EmissionsType is “CO2e”, “NOx” or “SO2” and a given fuel’s emissions factor is not entered, they will be defaulted as follows.
Fuel Type
CO2e [lb/MBtu]
NOx [lb/MBtu]
SO2 [lb/MBtu]
natural gas
147.3
0.0922
0.0006
propane
177.8
0.1421
0.0002
fuel oil
195.9
0.1300
0.0015
coal
–
–
–
wood
–
–
–
wood pellets
–
–
–
Default values in lb/MBtu (million Btu) are from ANSI/RESNET/ICC 301-2022 Addendum B and include both combustion and pre-combustion (e.g., methane leakage for natural gas) emissions.
If no default value is available, a warning will be issued.
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 Utility Bill Outputs 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
No
12.0
Monthly fixed charge [11]
MarginalRate
double
$/kWh
No
See [12]
Marginal flat rate
[11] If running Whole SFA/MF Buildings, the fixed charge will apply to every dwelling unit in the building.
[12] If MarginalRate not provided, defaults to state, regional, or national average based on 2022 EIA data that can be found at
ReportUtilityBills/resources/Data/UtilityRates/Average_retail_price_of_electricity.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 [13]
[13] 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
ReportUtilityBills/resources/detailed_rates/openei_rates.zip
. Additional sample tariff files can be found inReportUtilityBills/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 [14]
Yes
Fuel type
FixedCharge
double
$/month
No
See [15]
Monthly fixed charge
MarginalRate
double
See [16]
No
See [17]
Marginal flat rate
[14] FuelType choices are “natural gas”, “propane”, “fuel oil”, “coal”, “wood”, and “wood pellets”.
[15] FixedCharge defaults to $12/month for natural gas and $0/month for other fuels.
[16] MarginalRate units are $/therm for natural gas, $/gallon for propane and fuel oil, and $/kBtu for other fuels.
[17] If MarginalRate not provided, defaults to state, regional, or national average based on 2022 EIA data that can be found at:
- natural gas:
ReportUtilityBills/resources/Data/UtilityRates/NG_PRI_SUM_A_EPG0_PRS_DMCF_A.csv
- propane:
ReportUtilityBills/resources/Data/UtilityRates/PET_PRI_WFR_A_EPLLPA_PRS_DPGAL_W.csv
- fuel oil:
ReportUtilityBills/resources/Data/UtilityRates/PET_PRI_WFR_A_EPD2F_PRS_DPGAL_W.csv
or defaults to $0.015/kBtu for other fuels.
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 [18]
No
User-Specified
Net metering annual excess sellback rate type [19]
AnnualExcessSellbackRate
double
$/kWh
No [20]
0.03
User-specified net metering annual excess sellback rate [21]
[18] AnnualExcessSellbackRateType choices are “User-Specified” and “Retail Electricity Cost”.
[19] 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.
[20] AnnualExcessSellbackRate is only used when AnnualExcessSellbackRateType=”User-Specified”.
[21] 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
No
0.12
Feed-in tariff rate [22]
[22] 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-HPXML is currently unable to calculate utility bills for such a feed-in tariff policy.
HPXML Building
OpenStudio-HPXML can be used to model either individual residential Dwelling Units or Whole SFA/MF Buildings.
In either case, each residential dwelling unit is entered as a /HPXML/Building
.
Element
Type
Units
Constraints
Required
Default
Notes
BuildingID
id
Yes
Unique identifier
Dwelling Units
OpenStudio-HPXML was originally developed to model individual residential dwelling units – either a single-family detached (SFD) building, or a single unit of a single-family attached (SFA) or multifamily (MF) building. This approach:
Is required/desired for certain applications (e.g., a Home Energy Score or an Energy Rating Index calculation).
Improves runtime speed by being able to simulate individual units in parallel (as opposed to simulating the entire building).
For these simulations:
Surfaces can be defined adjacent to generic SFA/MF spaces (e.g., “other housing unit” or “other multifamily buffer space”) with assumed temperature profiles (see HPXML Locations).
Various building components (e.g., ducts, water heaters, appliances) can be located in these SFA/MF spaces.
Shared systems (HVAC, water heating, mechanical ventilation, etc.) serving multiple dwelling units can be defined, in which these systems are approximated as individual systems with efficiency adjustments to estimate the energy use attributed to the unit.
Energy use attributed only to the dwelling unit is calculated.
Whole SFA/MF Buildings
As of v1.7.0, OpenStudio-HPXML can model whole SFA/MF buildings in a single combined simulation.
Modeling a whole SFA/MF building is defined in /HPXML/SoftwareInfo/extension
.
Element
Type
Units
Constraints
Required
Default
Notes
WholeSFAorMFBuildingSimulation
boolean
No
false
Whether to run an individual dwelling unit or whole building for SFA/MF
For these simulations:
Unit multipliers (using the
NumberofUnits
element) can be specified to model unique dwelling units, rather than all dwelling units, reducing simulation runtime.Adjacent SFA/MF common spaces are still modeled using assumed temperature profiles, not as separate thermal zones.
Shared systems are still modeled as individual systems, not shared systems connected to multiple dwelling unit.
Energy use for the entire building is calculated.
Notes/caveats about this approach:
Some inputs (e.g., EPW location or ground conductivity) cannot vary across
Building
elements.Batteries are not currently supported.
Utility bill calculations using detailed rates are not supported.
HPXML Building Site
Building site information can be entered in /HPXML/Building/Site
.
Element
Type
Units
Constraints
Required
Default
Description
SiteID
id
Yes
Unique identifier
Address/CityMunicipality
string
No
See [24]
Address city/municipality (not used in the energy model)
Address/StateCode
string
No
See [25]
Address state/territory
Address/ZipCode
string
See [26]
No
Address ZIP Code (not used in the energy model)
GeoLocation/Latitude
double
deg
>= -90, <= 90
No
See [27]
Site latitude (negative for southern hemisphere)
GeoLocation/Longitude
double
deg
>= -180, <= 180
No
See [28]
Site longitude (negative for western hemisphere)
Elevation
double
ft
>= 0
No
See [29]
Site elevation
TimeZone/UTCOffset
double
>= -12, <= 14
No
See [30]
Difference in decimal hours between the home’s time zone and UTC
TimeZone/DSTObserved
boolean
No
true
Daylight saving time observed?
[24] If CityMunicipality not provided, defaults according to the EPW weather file header.
[25] If StateCode not provided, defaults according to the EPW weather file header.
[26] ZipCode can be defined as the standard 5 number postal code, or it can have the additional 4 number code separated by a hyphen.
[27] If Latitude not provided, defaults according to the EPW weather file header.
[28] If Longitude not provided, defaults according to the EPW weather file header.
[29] If Elevation not provided, defaults according to the EPW weather file header.
[30] If UTCOffset not provided, defaults according to the EPW weather file header.
If daylight saving time is observed, additional information can be specified in /HPXML/Building/Site/TimeZone/extension
.
Element
Type
Units
Constraints
Required
Default
Description
DSTBeginMonth
andDSTBeginDayOfMonth
integer
>= 1, <= 12 and >= 1, <= 31
No
EPW else 3/12 (March 12) [31]
Start date
DSTEndMonth
andDSTEndDayOfMonth
integer
>= 1, <= 12 and >= 1, <= 31
No
EPW else 11/5 (November 5)
End date
[31] Daylight saving dates will be defined according to the EPW weather file header; if not available, fallback default values listed above will be used.
HPXML Building Summary
High-level building summary information is entered in /HPXML/Building/BuildingDetails/BuildingSummary
.
HPXML Site
Site information is entered in /HPXML/Building/BuildingDetails/BuildingSummary/Site
.
Element
Type
Units
Constraints
Required
Default
Notes
SiteType
string
See [32]
No
suburban
Terrain type for infiltration model
ShieldingofHome
string
See [33]
No
normal
Presence of nearby buildings, trees, obstructions for infiltration model
Soil/SoilType
string
See [34]
No
unknown
Soil type
Soil/MoistureType
string
See [35]
No
mixed
Soil moisture type
Soil/Conductivity
double
Btu/hr-ft-F
> 0
No
See [36]
Soil thermal conductivity
Soil/extension/Diffusivity
double
ft2/hr
> 0
No
See [37]
Soil thermal diffusivity
extension/Neighbors
element
No
<none>
Presence of neighboring buildings for solar shading
[32] SiteType choices are “rural”, “suburban”, or “urban”.
[33] ShieldingofHome choices are “normal”, “exposed”, or “well-shielded”.
[34] SoilType choices are “sand”, “silt”, “clay”, “loam”, “gravel”, or “unknown”.
[35] MoistureType choices are “dry”, “wet”, or “mixed”.
[36] If Conductivity not provided, defaults to Diffusivity / 0.0208 if Diffusivity provided, otherwise defaults based on SoilType and MoistureType:
- unknown, dry/wet/mixed: 1.0000
- sand/gravel, dry: 0.2311
- sand, wet: 1.3865
- sand, mixed: 0.8088
- silt/clay, dry: 0.2889
- silt/clay, wet: 0.9821
- silt/clay, mixed: 0.6355
- loam, dry/wet/mixed: 1.2132
- gravel, wet: 1.0399
- gravel, mixed: 0.6355
[37] If Diffusivity not provided, defaults to Conductivity * 0.0208 if Conductivity provided, otherwise defaults based on SoilType and MoistureType:
- unknown, dry/wet/mixed: 0.0208
- sand/gravel, dry: 0.0097
- sand, wet: 0.0322
- sand, mixed: 0.0210
- silt/clay, dry: 0.0120
- silt/clay, wet: 0.0194
- silt/clay, mixed: 0.0157
- loam, dry/wet/mixed: 0.0353
- gravel, wet: 0.0291
- gravel, mixed: 0.0194
Note
Default Conductivity and Diffusivity values based on SoilType/MoistureType provided by Table 1 of Ground Thermal Diffusivity Calculation by Direct Soil Temperature Measurement. Application to very Low Enthalpy Geothermal Energy Systems (with the exception of “unknown”). Conductivity is used for foundation heat transfer and ground source heat pumps. Diffusivity is used for ground source heat pumps.
HPXML Neighbor Buildings
For each neighboring building defined, additional information is entered in a extension/Neighbors/NeighborBuilding
.
Element
Type
Units
Constraints
Required
Default
Notes
Azimuth
orOrientation
integer or string
deg or direction
>= 0, <= 359 or See [38]
Yes
Direction of neighbors (clockwise from North)
Distance
double
ft
> 0
Yes
Distance of neighbor from the dwelling unit
Height
double
ft
> 0
No
See [39]
Height of neighbor
[38] Orientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north” The azimuth/orientation of the neighboring building must match the azimuth/orientation of at least one wall in the home, otherwise an error will be thrown.
[39] If Height not provided, assumed to be same height as the dwelling unit.
HPXML Building Occupancy
Building occupancy is entered in /HPXML/Building/BuildingDetails/BuildingSummary/BuildingOccupancy
.
Element
Type
Units
Constraints
Required
Default
Notes
NumberofResidents
double
>= 0
No
See [40]
Number of occupants
extension/WeekdayScheduleFractions
array
No
See [41]
24 comma-separated weekday fractions
extension/WeekendScheduleFractions
array
No
24 comma-separated weekend fractions
extension/MonthlyScheduleMultipliers
array
No
See [42]
12 comma-separated monthly multipliers
extension/GeneralWaterUseUsageMultiplier
double
>= 0
No
1.0
Multiplier on general water use internal gains [43]
extension/GeneralWaterUseWeekdayScheduleFractions
array
No
See [44]
24 comma-separated weekday fractions
extension/GeneralWaterUseWeekendScheduleFractions
array
No
24 comma-separated weekend fractions
extension/GeneralWaterUseMonthlyScheduleMultipliers
array
No
See [45]
12 comma-separated monthly multipliers
[40] If NumberofResidents not provided, an asset calculation is performed assuming standard occupancy, in which various end use defaults (e.g., plug loads, appliances, and hot water usage) are calculated based on NumberofBedrooms and ConditionedFloorArea per ANSI/RESNET/ICC 301-2019. If NumberofResidents is provided, an operational calculation is instead performed in which the end use defaults are adjusted using the relationship between NumberofBedrooms and NumberofResidents from RECS 2015:
- single-family detached or manufactured home: NumberofBedrooms = -1.47 + 1.69 * NumberofResidents
- single-family attached or apartment unit: NumberofBedrooms = -0.68 + 1.09 * NumberofResidents
[41] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Table C.3(5) of ANSI/RESNET/ICC 301-2022 Addendum C are used: “0.035, 0.035, 0.035, 0.035, 0.035, 0.059, 0.082, 0.055, 0.027, 0.014, 0.014, 0.014, 0.014, 0.014, 0.019, 0.027, 0.041, 0.055, 0.068, 0.082, 0.082, 0.070, 0.053, 0.035”.
[42] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values are used: “1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0”.
[43] Sensible and latent internal gains from general water use (floor mopping, shower evaporation, water films on showers, tubs & sinks surfaces, plant watering, etc.), as defined by ANSI/RESNET/ICC 301-2019.
[44] If GeneralWaterUseWeekdayScheduleFractions or GeneralWaterUseWeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Table C.3(5) of ANSI/RESNET/ICC 301-2022 Addendum C are used: “0.023, 0.021, 0.021, 0.025, 0.027, 0.038, 0.044, 0.039, 0.037, 0.037, 0.034, 0.035, 0.035, 0.035, 0.039, 0.043, 0.051, 0.064, 0.065, 0.072, 0.073, 0.063, 0.045, 0.034”.
[45] If GeneralWaterUseMonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values are used: “1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0”.
HPXML Building Construction
Building construction is entered in /HPXML/Building/BuildingDetails/BuildingSummary/BuildingConstruction
.
Element
Type
Units
Constraints
Required
Default
Notes
ResidentialFacilityType
string
See [46]
Yes
Type of dwelling unit
NumberofUnits
integer
>= 1
No
1
Unit multiplier [47]
NumberofConditionedFloors
double
> 0
Yes
Number of conditioned floors (including a conditioned basement; excluding a conditioned crawlspace)
NumberofConditionedFloorsAboveGrade
double
> 0, <= NumberofConditionedFloors
Yes
Number of conditioned floors above grade (including a walkout basement)
AverageCeilingHeight
double
ft
> 0
No
8.2
Floor to ceiling height within conditioned space
NumberofBedrooms
integer
>= 0
Yes
Number of bedrooms
NumberofBathrooms
integer
> 0
No
See [48]
Number of bathrooms
ConditionedFloorArea
double
ft2
> 0
Yes
Floor area within conditioned space boundary (excluding conditioned crawlspace floor area)
ConditionedBuildingVolume
double
ft3
> 0
No
See [49]
Volume within conditioned space boundary (including a conditioned basement/crawlspace)
[46] ResidentialFacilityType choices are “single-family detached”, “single-family attached”, “apartment unit”, or “manufactured home”.
[47] NumberofUnits defines the number of similar dwelling units represented by the HPXML
Building
element. EnergyPlus simulation results will be multiplied by this value. For example, when modeling Whole SFA/MF Buildings, this allows modeling unique dwelling units, rather than all dwelling units, to reduce simulation runtime. Note that when NumberofUnits is greater than 1, a few capabilities are not currently supported:- Dehumidifiers
- Ground-source heat pumps
- HVAC maximum power ratio schedules for variable speed hvac systems (see Detailed Schedule Inputs)
[48] If NumberofBathrooms not provided, calculated as NumberofBedrooms/2 + 0.5 based on the 2010 BAHSP.
[49] If ConditionedBuildingVolume not provided, defaults to ConditionedFloorArea * AverageCeilingHeight + ConditionedCrawlspaceVolume.
HPXML Schedules
Schedules for a variety of building features can be defined using:
It is allowed to use simple, detailed, and defaulted values in the same HPXML file.
Simple Schedule Inputs
Simple schedule inputs are available as weekday/weekend fractions and monthly multipliers for a variety of building characteristics.
For example, see the WeekdayScheduleFractions
, WeekendScheduleFractions
, and MonthlyScheduleMultipliers
inputs for HPXML Building Occupancy.
Detailed Schedule Inputs
Detailed schedule inputs allow schedule values for every hour or timestep of the simulation. They can be used to reflect real-world or stochastic occupancy.
Detailed schedule inputs are provided via one or more CSV file that should be referenced in the HPXML file as /HPXML/Building/BuildingDetails/BuildingSummary/extension/SchedulesFilePath
elements.
The column names available in the schedule CSV files are:
Column Name
Units
Description
Can Be Stochastically Generated
occupants
frac
Occupant heat gain schedule.
Yes
lighting_interior
frac
Interior lighting energy use schedule.
Yes
lighting_exterior
frac
Exterior lighting energy use schedule.
No
lighting_garage
frac
Garage lighting energy use schedule.
Yes
lighting_exterior_holiday
frac
Exterior holiday lighting energy use schedule.
No
cooking_range
frac
Cooking range & oven energy use schedule.
Yes
refrigerator
frac
Primary refrigerator energy use schedule.
No
extra_refrigerator
frac
Non-primary refrigerator energy use schedule.
No
freezer
frac
Freezer energy use schedule.
No
dishwasher
frac
Dishwasher energy use schedule.
Yes
clothes_washer
frac
Clothes washer energy use schedule.
Yes
clothes_dryer
frac
Clothes dryer energy use schedule.
Yes
ceiling_fan
frac
Ceiling fan energy use schedule.
Yes
plug_loads_other
frac
Other plug load energy use schedule.
Yes
plug_loads_tv
frac
Television plug load energy use schedule.
Yes
plug_loads_vehicle
frac
Electric vehicle plug load energy use schedule.
No
plug_loads_well_pump
frac
Well pump plug load energy use schedule.
No
fuel_loads_grill
frac
Grill fuel load energy use schedule.
No
fuel_loads_lighting
frac
Lighting fuel load energy use schedule.
No
fuel_loads_fireplace
frac
Fireplace fuel load energy use schedule.
No
pool_pump
frac
Pool pump energy use schedule.
No
pool_heater
frac
Pool heater energy use schedule.
No
permanent_spa_pump
frac
Permanent spa pump energy use schedule.
No
permanent_spa_heater
frac
Permanent spa heater energy use schedule.
No
hot_water_dishwasher
frac
Dishwasher hot water use schedule.
Yes
hot_water_clothes_washer
frac
Clothes washer hot water use schedule.
Yes
hot_water_fixtures
frac
Fixtures (sinks, showers, baths) hot water use schedule.
Yes
hot_water_recirculation_pump
frac
Hot water recirculation pump schedule.
No
general_water_use
frac
General water use internal gains.
No
heating_setpoint
F
Thermostat heating setpoint schedule.
No
cooling_setpoint
F
Thermostat cooling setpoint schedule.
No
hvac_maximum_power_ratio
frac
Variable speed system maximum power ratio schedule. [50]
No
water_heater_setpoint
F
Water heater setpoint schedule.
No
water_heater_operating_mode
0/1
Heat pump water heater operating mode schedule. 0=hybrid/auto, 1=heat pump only.
No
battery
-1 to 1
Battery schedule. Positive for charging, negative for discharging.
No
[50] This feature is an advanced research capability. This schedule allows modeling shedding controls for variable speed HVAC systems (instead of setpoint changes) to limit the power of HVAC per AHRI 1380. While any fraction value can be entered, this is primarily intended to reflect the AHRI capabilities, which has two levels of load shed: “General Curtailment” and “Critical Curtailment”. A “General Curtailment” signal prevents the equipment from running at more than 70% of max power and “Critical Curtailment” limits it to 40% of max power until comfort constraints are violated (4F off the setpoint). During the shedding events, the main heat pump is limited to running below the specified fraction of rated power, and the backup system is locked out. When the comfort constraints are violated, both heat pump and backup systems are allowed to run at full load to recover the indoor temperature until reaching setpoint.
Columns with units of frac must be normalized to MAX=1; that is, these schedules only define when energy is used, not how much energy is used.
In other words, the amount of energy or hot water used in each simulation timestep is essentially the schedule value divided by the sum of all schedule values in the column, multiplied by the annual energy or hot water use.
Example schedule CSV files are provided in the HPXMLtoOpenStudio/resources/schedule_files
directory.
The schedule file must have a full year of data even if the simulation is not an entire year. Frequency of schedule values do not need to match the simulation timestep. For example, hourly schedules can be used with a 10-minute simulation timestep, or 10-minute schedules can be used with an hourly simulation timestep.
A detailed stochastic occupancy schedule CSV file can also be automatically generated for you (see “Can Be Stochastically Generated” above for applicable columns); see the Usage Instructions for the commands. Inputs for the stochastic schedule generator are entered in:
/HPXML/Building/BuildingDetails/BuildingSummary/BuildingOccupancy/NumberofResidents
/HPXML/Building/Site/Address/StateCode
(optional)/HPXML/Building/Site/GeoLocation/Latitude
(optional)/HPXML/Building/Site/GeoLocation/Longitude
(optional)/HPXML/Building/Site/TimeZone/UTCOffset
(optional)
See HPXML Building Occupancy and HPXML Building Site for more information.
Warning
For simulations with daylight saving enabled (which is the default), EnergyPlus will skip forward an hour in the CSV on the “spring forward” day and repeat an hour on the “fall back” day.
Default Schedules
If neither simple nor detailed inputs are provided, then schedules are defaulted. Default schedules are typically smooth, averaged schedules. These default schedules are described elsewhere in the documentation (e.g., see HPXML Building Occupancy for the default occupant heat gain schedule).
HPXML HVAC Sizing Control
HVAC equipment sizing controls are entered in /HPXML/Building/BuildingDetails/BuildingSummary/extension/HVACSizingControl
.
Additional autosizing factor inputs are available at the system level, see HPXML Heating Systems, HPXML Cooling Systems and HPXML Heat Pumps.
Element
Type
Units
Constraints
Required
Default
Description
HeatPumpSizingMethodology
string
See [51]
No
HERS
Logic for autosized heat pumps
HeatPumpBackupSizingMethodology
string
See [52]
No
emergency
Logic for autosized heat pump backup
AllowIncreasedFixedCapacities
boolean
No
false
Logic for fixed capacity HVAC equipment [53]
[51] HeatPumpSizingMethodology choices are ‘ACCA’, ‘HERS’, or ‘MaxLoad’, and are described as follows:
- ACCA: autosized heat pumps have their nominal capacity sized per ACCA Manual J/S based on cooling design loads, with some oversizing allowances for larger heating design loads.
- HERS: autosized heat pumps have their nominal capacity sized equal to the larger of heating/cooling design loads.
- MaxLoad: autosized heat pumps have their nominal capacity sized based on the larger of heating/cooling design loads, while taking into account the heat pump’s reduced capacity at the design temperature, such that no backup heating should be necessary.
[52] HeatPumpBackupSizingMethodology choices are ‘emergency’ or ‘supplemental’, and are described as follows:
- emergency: heat pump backup capacity will be autosized to meet the ACCA Manual J heating design load.
- supplemental: heat pump backup capacity will be autosized to meet the remainder of the ACCA Manual J heating design load not met by the heat pump at the heating design temperature.
Heat pump backup capacity is often sized for emergency heat so that it can meet the entire design load if the heat pump fails. Some contractors/homeowners may choose not to do so, perhaps due to insufficient panel/wiring capacity. Note: If the minimum temperature for the heat pump’s compressor (i.e.,
CompressorLockoutTemperature
orBackupHeatingSwitchoverTemperature
) is above the heating design temperature, the two sizing methodologies will give identical results.[53] If AllowIncreasedFixedCapacities is true, the larger of user-specified fixed capacity and design load will be used (to reduce potential for unmet loads); otherwise user-specified fixed capacity is used.
Manual J Inputs
If any HVAC equipment is being autosized (i.e., capacities are not provided), additional inputs for ACCA Manual J can be entered in /HPXML/Building/BuildingDetails/BuildingSummary/extension/HVACSizingControl/ManualJInputs
.
Element
Type
Units
Constraints
Required
Default
Description
HeatingDesignTemperature
double
F
No
See [54]
Heating outdoor design temperature
CoolingDesignTemperature
double
F
No
See [55]
Cooling outdoor design temperature
DailyTemperatureRange
string
See [56]
No
See [57]
Class based on average difference between daily high/low outdoor temperatures during the hottest month
HeatingSetpoint
double
F
No
70
Conditioned space heating setpoint [58]
CoolingSetpoint
double
F
No
75
Conditioned space cooling setpoint [59]
HumiditySetpoint
double
frac
> 0, < 1
No
See [60]
Conditioned space relative humidity
HumidityDifference
double
grains
No
See [61]
Difference between absolute humidity of the outdoor/indoor air during the summer
InternalLoadsSensible
double
Btu/hr
No
See [62]
Sensible internal loads for cooling design load
InternalLoadsLatent
double
Btu/hr
No
0
Latent internal loads for cooling design load
NumberofOccupants
integer
No
#Beds+1 [63]
Number of occupants for cooling design load
[54] If HeatingDesignTemperature not provided, the 99% heating design temperature is obtained from the DESIGN CONDITIONS header section inside the EPW weather file. If not available in the EPW header, it is calculated from the 8760 hourly temperatures in the EPW.
[55] If CoolingDesignTemperature not provided, the 1% cooling design temperature is obtained from the DESIGN CONDITIONS header section inside the EPW weather file. If not available in the EPW header, it is calculated from the 8760 hourly temperatures in the EPW.
[56] DailyTemperatureRange choices are “low”, “medium”, or “high”.
[57] If DailyTemperatureRange not provided, the cooling drybulb temperature range is obtained from the DESIGN CONDITIONS header section inside the EPW weather file. If not available in the EPW header, it is calculated from the 8760 hourly temperatures in the EPW.
[58] Any heating setpoint other than 70F is not in compliance with Manual J.
[59] Any cooling setpoint other than 75F is not in compliance with Manual J.
[60] If HumiditySetpoint not provided, defaults to 0.45 in a dry climate, otherwise 0.5.
[61] If HumidityDifference not provided, it is calculated from the other inputs/defaults and the cooling humidity ratio. The cooling humidity ratio is calculated from the DESIGN CONDITIONS header section inside the EPW weather file or, if not available, the 8760 hourly temperatures in the EPW.
[62] If InternalLoadsSensible not provided, defaults to 2400 Btu/hr if there is one refrigerator and no freezer, or 3600 Btu/hr if two refrigerators or a freezer. This default represents loads that normally occur during the early evening in mid-summer. Additional adjustments or custom internal loads can instead be specified here.
[63] If NumberofOccupants not provided, defaults to the number of bedrooms plus one per Manual J. Each occupant produces an additional 230 Btu/hr sensible load and 200 Btu/hr latent load.
HPXML Shading Control
Shading controls for window and skylight summer/winter shading coefficients are entered in /HPXML/Building/BuildingDetails/BuildingSummary/extension/ShadingControl
.
If not provided, summer will be default based on the cooling season defined in the 2010 BAHSP, using monthly average temperatures.
The remainder of the year is winter.
Element
Type
Units
Constraints
Required
Default
Description
SummerBeginMonth
integer
>= 1, <= 12
Yes
Summer shading start date
SummerBeginDayOfMonth
integer
>= 1, <= 31
Yes
Summer shading start date
SummerEndMonth
integer
>= 1, <= 12
Yes
Summer shading end date
SummerEndDayOfMonth
integer
>= 1, <= 31
Yes
Summer shading end date
HPXML Climate Zones
HPXML Climate Zone IECC
Climate zone information can be optionally entered as an /HPXML/Building/BuildingDetails/ClimateandRiskZones/ClimateZoneIECC
.
Element
Type
Units
Constraints
Required
Default
Description
Year
integer
See [64]
Yes
IECC year
ClimateZone
string
See [65]
Yes
IECC zone
[64] Year choices are 2003, 2006, 2009, 2012, 2015, 2018, or 2021.
[65] ClimateZone choices are “1A”, “1B”, “1C”, “2A”, “2B”, “2C”, “3A”, “3B”, “3C”, “4A”, “4B”, “4C”, “5A”, “5B”, “5C”, “6A”, “6B”, “6C”, “7”, or “8”.
If Climate zone information not provided, defaults according to the EPW weather file header.
Weather information is entered in /HPXML/Building/BuildingDetails/ClimateandRiskZones/WeatherStation
.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
Name
string
Yes
Name of weather station
extension/EPWFilePath
string
Yes
Path to the EnergyPlus weather file (EPW) [66]
[66] A full set of U.S. TMY3 weather files can be downloaded here.
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/orientation to be specified. Rather, only the windows/skylights themselves require an azimuth/orientation. 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
TypeOfInfiltrationLeakage
string
See [67]
See [68]
Type of infiltration leakage
InfiltrationVolume
double
ft3
> 0
No
ConditionedBuildingVolume
Volume associated with infiltration measurement [69]
InfiltrationHeight
double
ft
> 0
No
See [70]
Height associated with infiltration measurement [71]
extension/Aext
double
frac
> 0
No
See [72]
Exterior area ratio for SFA/MF dwelling units
[67] TypeOfInfiltrationLeakage choices are “unit total” or “unit exterior only”, and are described as follows:
- unit total: the provided infiltration value represents the total infiltration to the dwelling unit, as measured by a compartmentalization test, in which case it will be adjusted by
extension/Aext
.- unit exterior only: the provided infiltration value represents the infiltration to the dwelling unit from outside only, as measured by a guarded test.
[68] TypeOfInfiltrationLeakage required if single-family attached or apartment unit.
[69] 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.
[70] If InfiltrationHeight not provided, it is inferred from other inputs (e.g., conditioned floor area, number of conditioned floors above-grade, above-grade foundation wall height, etc.).
[71] InfiltrationHeight is defined as the vertical distance between the lowest and highest above-grade points within the pressure boundary, per ASHRAE 62.2.
[72] If Aext not provided and TypeOfInfiltrationLeakage is “unit total”, defaults for single-family attached and apartment units to the ratio of exterior (adjacent to outside) envelope surface area to total (adjacent to outside, other dwelling units, or other MF spaces) envelope surface area, as defined by ANSI/RESNET/ICC 301-2019 and ASHRAE 62.2-2019. Note that all attached surfaces, even adiabatic surfaces, must be defined in the HPXML file. If single-family detached or TypeOfInfiltrationLeakage is “unit exterior only”, Aext is 1.
In addition, one of the following air leakage types must also be defined:
Note
Infiltration airflow rates are calculated using the Alberta Air Infiltration Model (AIM-2) (also known as the ASHRAE Enhanced model). When there is a flue or chimney present (see Flue or Chimney) with combustion air from conditioned space, higher infiltration airflow rates are modeled because the flue leakage is at a different height for stack effect.
ACH or CFM
If entering air leakage as ACH or CFM at a user-specific pressure, additional information is entered in /HPXML/Building/BuildingDetails/Enclosure/AirInfiltration/AirInfiltrationMeasurement
.
For example, ACH50 (ACH at 50 Pascals) is a commonly obtained value from a blower door measurement.
Element
Type
Units
Constraints
Required
Default
Notes
BuildingAirLeakage/UnitofMeasure
string
See [73]
Yes
Units for air leakage
HousePressure
double
Pa
> 0
Yes
House pressure with respect to outside [74]
BuildingAirLeakage/AirLeakage
double
> 0
Yes
Value for air leakage
[73] UnitofMeasure choices are “ACH” or “CFM”.
[74] HousePressure typical value is 50 Pa.
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.
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
Flue or Chimney
The presence of a flue or chimney with combustion air from conditioned space can be entered in /HPXML/Building/BuildingDetails/Enclosure/AirInfiltration
.
Element
Type
Units
Constraints
Required
Default
Notes
extension/HasFlueOrChimneyInConditionedSpace
boolean
No
See [76]
Flue or chimney with combustion air from conditioned space
[76] If HasFlueOrChimneyInConditionedSpace not provided, defaults to true if any of the following conditions are met, otherwise false:
- heating system is non-electric Furnace, Boiler, WallFurnace, FloorFurnace, Stove, or SpaceHeater located in conditioned space and AFUE/Percent is less than 0.89,
- heating system is non-electric Fireplace located in conditioned space, or
- water heater is non-electric with energy factor (or equivalent calculated from uniform energy factor) less than 0.63 and located in conditioned space.
HPXML Attics
If the dwelling unit has an unvented attic, whether it is within the infiltration volume is entered in /HPXML/Building/BuildingDetails/Enclosure/Attics/Attic[AtticType/Attic[Vented="false"]]
.
Element
Type
Units
Constraints
Required
Default
Notes
WithinInfiltrationVolume
boolean
No
false
In accordance with ANSI/RESNET/ICC Standard 380
If the dwelling unit has a vented attic, attic ventilation information can be optionally entered in /HPXML/Building/BuildingDetails/Enclosure/Attics/Attic[AtticType/Attic[Vented="true"]]/VentilationRate
.
Element
Type
Units
Constraints
Required
Default
Notes
UnitofMeasure
string
See [77]
No
SLA
Units for ventilation rate
Value
double
> 0
No
1/300 [78]
Value for ventilation rate
[77] UnitofMeasure choices are “SLA” (specific leakage area) or “ACHnatural” (natural air changes per hour).
[78] Value default based on ANSI/RESNET/ICC 301-2019.
HPXML Foundations
If the dwelling unit has an unconditioned basement, whether it is within the infiltration volume is entered in Enclosure/Foundations/Foundation/FoundationType/Basement[Conditioned='false']
.
Element
Type
Units
Constraints
Required
Default
Notes
WithinInfiltrationVolume
boolean
No
false
In accordance with ANSI/RESNET/ICC Standard 380
If the dwelling unit has an unvented crawlspace, whether it is within the infiltration volume is entered in Enclosure/Foundations/Foundation/FoundationType/Crawlspace[Vented='false']
.
Element
Type
Units
Constraints
Required
Default
Notes
WithinInfiltrationVolume
boolean
No
false
In accordance with ANSI/RESNET/ICC Standard 380
If the dwelling unit has a vented crawlspace, crawlspace ventilation information can be optionally entered in /HPXML/Building/BuildingDetails/Enclosure/Foundations/Foundation[FoundationType/Crawlspace[Vented="true"]]/VentilationRate
.
Element
Type
Units
Constraints
Required
Default
Notes
UnitofMeasure
string
See [79]
No
SLA
Units for ventilation rate
Value
double
> 0
No
1/150 [80]
Value for ventilation rate
[79] UnitofMeasure only choice is “SLA” (specific leakage area).
[80] Value default based on ANSI/RESNET/ICC 301-2019.
If the dwelling has a manufactured home belly-and-wing foundation, whether a skirt is present can be optionally entered in /HPXML/Building/BuildingDetails/Enclosure/Foundations/Foundation/FoundationType/BellyAndWing
.
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 [82]
Yes
Interior adjacent space type
Area
double
ft2
> 0
Yes
Gross area (including skylights)
Azimuth
orOrientation
integer or string
deg or direction
>= 0, <= 359 or See [83]
No
See [84]
Direction (clockwise from North)
RoofType
string
See [85]
No
asphalt or fiberglass shingles
Roof type
RoofColor
orSolarAbsorptance
string or double
See [86] or >= 0, <= 1
No
medium
Roof color or solar absorptance [87]
Emittance
double
>= 0, <= 1
No
0.90
Emittance
InteriorFinish/Type
string
See [88]
No
See [89]
Interior finish material
InteriorFinish/Thickness
double
in
>= 0
No
0.5
Interior finish thickness
Pitch
double
?/12
>= 0
Yes
Pitch [90]
RadiantBarrier
boolean
No
false
Presence of radiant barrier [91]
RadiantBarrierGrade
integer
>= 1, <= 3
No
1
Radiant barrier installation grade
Insulation/SystemIdentifier
id
Yes
Unique identifier
Insulation/AssemblyEffectiveRValue
double
F-ft2-hr/Btu
> 0
Yes
Assembly R-value [92]
[82] InteriorAdjacentTo choices are “attic - vented”, “attic - unvented”, “conditioned space”, or “garage”. See HPXML Locations for descriptions.
[83] Orientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[84] If neither Azimuth nor Orientation provided, and it’s a pitched roof, modeled as four surfaces of equal area facing every direction. Azimuth/Orientation is irrelevant for flat roofs.
[85] RoofType choices are “asphalt or fiberglass shingles”, “wood shingles or shakes”, “shingles”, “slate or tile shingles”, “metal surfacing”, “plastic/rubber/synthetic sheeting”, “expanded polystyrene sheathing”, “concrete”, or “cool roof”.
[86] RoofColor choices are “light”, “medium”, “medium dark”, “dark”, or “reflective”.
[87] If SolarAbsorptance not provided, defaults based on RoofType and RoofColor:
- asphalt or fiberglass shingles: dark=0.92, medium dark=0.89, medium=0.85, light=0.75, reflective=0.50
- wood shingles or shakes: dark=0.92, medium dark=0.89, medium=0.85, light=0.75, reflective=0.50
- shingles: dark=0.92, medium dark=0.89, medium=0.85, light=0.75, reflective=0.50
- slate or tile shingles: dark=0.90, medium dark=0.83, medium=0.75, light=0.60, reflective=0.30
- metal surfacing: dark=0.90, medium dark=0.83, medium=0.75, light=0.60, reflective=0.30
- plastic/rubber/synthetic sheeting: dark=0.90, medium dark=0.83, medium=0.75, light=0.60, reflective=0.30
- expanded polystyrene sheathing: dark=0.92, medium dark=0.89, medium=0.85, light=0.75, reflective=0.50
- concrete: dark=0.90, medium dark=0.83, medium=0.75, light=0.65, reflective=0.50
- cool roof: 0.30
[88] InteriorFinish/Type choices are “gypsum board”, “gypsum composite board”, “plaster”, “wood”, “other”, or “none”.
[89] InteriorFinish/Type defaults to “gypsum board” if InteriorAdjacentTo is conditioned space, otherwise “none”.
[90] 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.
[91] RadiantBarrier intended for attic roofs. Model assumes an emittance of 0.05.
[92] AssemblyEffectiveRValue includes all material layers, interior/exterior air films, and insulation installation grade.
HPXML Rim Joists
Each rim joist surface (i.e., the perimeter of floor joists typically found between stories of a building or on top of a foundation wall) is entered as a /HPXML/Building/BuildingDetails/Enclosure/RimJoists/RimJoist
.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
ExteriorAdjacentTo
string
See [93]
Yes
Exterior adjacent space type
InteriorAdjacentTo
string
See [94]
Yes
Interior adjacent space type
Area
double
ft2
> 0
Yes
Gross area
Azimuth
orOrientation
integer or string
deg or direction
>= 0, <= 359 or See [95]
No
See [96]
Direction (clockwise from North)
Siding
string
See [97]
No
wood siding
Siding material
Color
orSolarAbsorptance
string or double
See [98] or >= 0, <= 1
No
medium
Color or solar absorptance [99]
Emittance
double
>= 0, <= 1
No
0.90
Emittance
Insulation/SystemIdentifier
id
Yes
Unique identifier
Insulation/AssemblyEffectiveRValue
double
F-ft2-hr/Btu
> 0
Yes
Assembly R-value [100]
[93] ExteriorAdjacentTo choices are “outside”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “crawlspace - conditioned”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.
[94] InteriorAdjacentTo choices are “conditioned space”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “crawlspace - conditioned”, or “garage”. See HPXML Locations for descriptions.
[95] Orientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[96] If neither Azimuth nor Orientation provided, and it’s an exterior rim joist, modeled as four surfaces of equal area facing every direction. Azimuth/Orientation is irrelevant for interior rim joists.
[97] Siding choices are “wood siding”, “vinyl siding”, “stucco”, “fiber cement siding”, “brick veneer”, “aluminum siding”, “masonite siding”, “composite shingle siding”, “asbestos siding”, “synthetic stucco”, or “none”.
[98] Color choices are “light”, “medium”, “medium dark”, “dark”, or “reflective”.
[99] If SolarAbsorptance not provided, defaults based on Color:
- dark: 0.95
- medium dark: 0.85
- medium: 0.70
- light: 0.50
- reflective: 0.30
[100] AssemblyEffectiveRValue includes all material layers, interior/exterior air films, and insulation installation grade.
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 [101]
Yes
Exterior adjacent space type
InteriorAdjacentTo
string
See [102]
Yes
Interior adjacent space type
WallType
element
See [103]
Yes
Wall type (for thermal mass)
Area
double
ft2
> 0
Yes
Gross area (including doors/windows)
Azimuth
orOrientation
integer or string
deg or direction
>= 0, <= 359 or See [104]
No
See [105]
Direction (clockwise from North)
Siding
string
See [106]
No
wood siding
Siding material
Color
orSolarAbsorptance
string or double
See [107] or >= 0, <= 1
No
medium
Color or solar absorptance [108]
Emittance
double
>= 0, <= 1
No
0.90
Emittance
InteriorFinish/Type
string
See [109]
No
See [110]
Interior finish material
InteriorFinish/Thickness
double
in
>= 0
No
0.5
Interior finish thickness
RadiantBarrier
boolean
No
false
Presence of radiant barrier [111]
RadiantBarrierGrade
integer
>= 1, <= 3
No
1
Radiant barrier installation grade
Insulation/SystemIdentifier
id
Yes
Unique identifier
Insulation/AssemblyEffectiveRValue
double
F-ft2-hr/Btu
> 0
Yes
Assembly R-value [112]
[101] ExteriorAdjacentTo choices are “outside”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “crawlspace - conditioned”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.
[102] InteriorAdjacentTo choices are “conditioned space”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “crawlspace - conditioned”, or “garage”. See HPXML Locations for descriptions.
[103] WallType child element choices are
WoodStud
,DoubleWoodStud
,ConcreteMasonryUnit
,StructuralInsulatedPanel
,InsulatedConcreteForms
,SteelFrame
,SolidConcrete
,StructuralBrick
,StrawBale
,Stone
,LogWall
, orAdobe
.[104] Orientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[105] If neither Azimuth nor Orientation provided, and it’s an exterior wall, modeled as four surfaces of equal area facing every direction. Azimuth/Orientation is irrelevant for interior walls (e.g., between conditioned space and garage).
[106] Siding choices are “wood siding”, “vinyl siding”, “stucco”, “fiber cement siding”, “brick veneer”, “aluminum siding”, “masonite siding”, “composite shingle siding”, “asbestos siding”, “synthetic stucco”, or “none”.
[107] Color choices are “light”, “medium”, “medium dark”, “dark”, or “reflective”.
[108] If SolarAbsorptance not provided, defaults based on Color:
- dark: 0.95
- medium dark: 0.85
- medium: 0.70
- light: 0.50
- reflective: 0.30
[109] InteriorFinish/Type choices are “gypsum board”, “gypsum composite board”, “plaster”, “wood”, “other”, or “none”.
[110] InteriorFinish/Type defaults to “gypsum board” if InteriorAdjacentTo is conditioned space or basement - conditioned, otherwise “none”.
[111] RadiantBarrier intended for attic gable walls. Model assumes an emittance of 0.05.
[112] AssemblyEffectiveRValue includes all material layers, interior/exterior air films, and insulation installation grade.
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 [113]
Yes
Exterior adjacent space type [114]
InteriorAdjacentTo
string
See [115]
Yes
Interior adjacent space type
Type
string
See [116]
No
solid concrete
Type of material
Height
double
ft
> 0
Yes
Total height
Area
orLength
double
ft2 or ft
> 0
Yes
Gross area (including doors/windows) or length
Azimuth
orOrientation
integer or string
deg or direction
>= 0, <= 359 or See [117]
No
See [118]
Direction (clockwise from North)
Thickness
double
in
> 0
No
8.0
Thickness excluding interior framing
DepthBelowGrade
double
ft
>= 0, <= Height
Yes
Depth below grade [119]
InteriorFinish/Type
string
See [120]
No
See [121]
Interior finish material
InteriorFinish/Thickness
double
in
>= 0
No
0.5
Interior finish thickness
Insulation/SystemIdentifier
id
Yes
Unique identifier
Insulation/Layer[InstallationType="continuous - interior"]
element
See [122]
Interior insulation layer
Insulation/Layer[InstallationType="continuous - exterior"]
element
See [123]
Exterior insulation layer
Insulation/AssemblyEffectiveRValue
double
F-ft2-hr/Btu
> 0
See [124]
Assembly R-value [125]
[113] ExteriorAdjacentTo choices are “ground”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “crawlspace - conditioned”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.
[114] InteriorAdjacentTo choices are “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “crawlspace - conditioned”, or “garage”. See HPXML Locations for descriptions.
[115] 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.
[116] 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”.
[117] Orientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[118] If neither Azimuth nor Orientation provided, and it’s an exterior foundation wall, modeled as four surfaces of equal area facing every direction. Azimuth/Orientation is irrelevant for interior foundation walls (e.g., between basement and garage).
[119] 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.
[120] InteriorFinish/Type choices are “gypsum board”, “gypsum composite board”, “plaster”, “wood”, “other”, or “none”.
[121] InteriorFinish/Type defaults to “gypsum board” if InteriorAdjacentTo is basement - conditioned, otherwise “none”.
[122] Layer[InstallationType=”continuous - interior”] only required if AssemblyEffectiveRValue is not provided.
[123] Layer[InstallationType=”continuous - exterior”] only required if AssemblyEffectiveRValue is not provided.
[124] AssemblyEffectiveRValue only required if Layer elements are not provided.
[125] AssemblyEffectiveRValue includes all material layers, interior air film, and insulation installation grade. R-value should not include exterior air film (for any above-grade exposure) or any soil thermal resistance.
If insulation layers are provided, additional information is entered in each FoundationWall/Insulation/Layer
.
Element
Type
Units
Constraints
Required
Default
Notes
NominalRValue
double
F-ft2-hr/Btu
>= 0
Yes
R-value of the foundation wall insulation; use zero if no insulation
DistanceToTopOfInsulation
double
ft
>= 0
No
0
Vertical distance from top of foundation wall to top of insulation
DistanceToBottomOfInsulation
double
ft
See [126]
No
Height
Vertical distance from top of foundation wall to bottom of insulation
[126] 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 [127]
Yes
Exterior adjacent space type
InteriorAdjacentTo
string
See [128]
Yes
Interior adjacent space type
FloorOrCeiling
string
See [129]
See [130]
Floor or ceiling from the perspective of the conditioned space
FloorType
element
See [131]
Yes
Floor type (for thermal mass)
Area
double
ft2
> 0
Yes
Gross area
InteriorFinish/Type
string
See [132]
No
See [133]
Interior finish material
InteriorFinish/Thickness
double
in
>= 0
No
0.5
Interior finish thickness
RadiantBarrier
boolean
No
false
Presence of radiant barrier [134]
RadiantBarrierGrade
integer
>= 1, <= 3
No
1
Radiant barrier installation grade
Insulation/SystemIdentifier
id
Yes
Unique identifier
Insulation/AssemblyEffectiveRValue
double
F-ft2-hr/Btu
> 0
Yes
Assembly R-value [135]
[127] ExteriorAdjacentTo choices are “outside”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “crawlspace - conditioned”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, “other non-freezing space”, or “manufactured home underbelly”. See HPXML Locations for descriptions.
[128] InteriorAdjacentTo choices are “conditioned space”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “crawlspace - conditioned”, or “garage”. See HPXML Locations for descriptions.
[129] FloorOrCeiling choices are “floor” or “ceiling”.
[130] FloorOrCeiling only required for floors adjacent to “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”.
[131] FloorType child element choices are
WoodFrame
,StructuralInsulatedPanel
,SteelFrame
, orSolidConcrete
.[132] InteriorFinish/Type choices are “gypsum board”, “gypsum composite board”, “plaster”, “wood”, “other”, or “none”.
[133] InteriorFinish/Type defaults to “gypsum board” if InteriorAdjacentTo is conditioned space and the surface is a ceiling, otherwise “none”.
[134] RadiantBarrier intended for attic floors. Model assumes an emittance of 0.5 (reduced effectiveness due to accumulation of dust) per an ORNL article on radiant barriers.
[135] AssemblyEffectiveRValue includes all material layers, interior/exterior air films, and insulation installation grade. For a manufactured home belly where the area of the belly wrap is different and usually greater than the floor area, the AssemblyEffectiveRValue should be adjusted to account for the surface area of the belly wrap and insulation.
HPXML Slabs
Each space type that borders the ground (i.e., basement, crawlspace, garage, and slab-on-grade foundation) should have a slab entered as an /HPXML/Building/BuildingDetails/Enclosure/Slabs/Slab
.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
InteriorAdjacentTo
string
See [136]
Yes
Interior adjacent space type
Area
double
ft2
> 0
Yes
Gross area
Thickness
double
in
>= 0
No
See [137]
Thickness [138]
ExposedPerimeter
double
ft
>= 0
Yes
Perimeter exposed to ambient conditions [139]
DepthBelowGrade
double
ft
>= 0
No
See [140]
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 [141]
Width from slab edge inward of horizontal insulation
UnderSlabInsulation/Layer/InsulationSpansEntireSlab
boolean
See [142]
Whether horizontal insulation spans entire slab
extension/GapInsulationRValue
double
F-ft2-hr/Btu
>= 0
No
See [143]
R-value of gap insulation (see figure below)
extension/CarpetFraction
double
frac
>= 0, <= 1
No
See [144]
Fraction of slab covered by carpet
extension/CarpetRValue
double
F-ft2-hr/Btu
>= 0
No
See [145]
Carpet R-value
[136] InteriorAdjacentTo choices are “conditioned space”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “crawlspace - conditioned”, or “garage”. See HPXML Locations for descriptions.
[137] If Thickness not provided, defaults to 0 when adjacent to crawlspace and 4 inches for all other cases.
[138] For a crawlspace with a dirt floor, enter a thickness of zero.
[139] ExposedPerimeter includes any slab length that falls along the perimeter of the building’s footprint (i.e., is exposed to ambient conditions). So a basement slab edge adjacent to a garage or crawlspace, for example, should not be included.
[140] 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).[141] InsulationWidth only required if InsulationSpansEntireSlab=true is not provided.
[142] InsulationSpansEntireSlab=true only required if InsulationWidth is not provided.
[143] If GapInsulationRValue not provided, defaults to 5.0 if there is under slab (horizontal) insulation, otherwise 0.0.
[144] If CarpetFraction not provided, defaults to 0.8 when adjacent to conditioned space, otherwise 0.0.
[145] If CarpetRValue not provided, defaults to 2.0 when adjacent to conditioned space, otherwise 0.0.
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
Azimuth
orOrientation
integer or string
deg or direction
>= 0, <= 359 or See [146]
Yes
Direction (clockwise from North)
UFactor
and/orGlassLayers
double or string
Btu/F-ft2-hr
> 0 or See [147]
Yes
Full-assembly NFRC U-factor or glass layers description
SHGC
and/orGlassLayers
double or string
> 0, < 1
Yes
Full-assembly NFRC solar heat gain coefficient or glass layers description
ExteriorShading/SummerShadingCoefficient
double
frac
>= 0, <= 1
No
1.00
Exterior summer shading coefficient (1=transparent, 0=opaque) [148]
ExteriorShading/WinterShadingCoefficient
double
frac
>= 0, <= 1
No
1.00
Exterior winter shading coefficient (1=transparent, 0=opaque)
InteriorShading/SummerShadingCoefficient
double
frac
>= 0, <= 1
No
Interior summer shading coefficient (1=transparent, 0=opaque)
InteriorShading/WinterShadingCoefficient
double
frac
>= 0, <= 1
No
Interior winter shading coefficient (1=transparent, 0=opaque)
StormWindow/GlassType
string
See [151]
No
Type of storm window glass
Overhangs
element
No
<none>
Presence of overhangs (including roof eaves)
FractionOperable
double
frac
>= 0, <= 1
No
0.67
Operable fraction [152]
AttachedToWall
idref
See [153]
Yes
ID of attached wall
[146] Orientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”.
[147] GlassLayers choices are “single-pane”, “double-pane”, “triple-pane”, or “glass block”.
[148] Summer vs winter shading seasons are determined per HPXML Shading Control.
[149] InteriorShading/SummerShadingCoefficient default value is calculated based on ANSI/RESNET/ICC 301-2022 Addendum C:
Interior shading coefficient = 0.92 - (0.21 * SHGC)
[150] InteriorShading/WinterShadingCoefficient default value is the same as InteriorShading/SummerShadingCoefficient default value.
[151] GlassType choices are “clear” or “low-e”. The
UFactor
andSHGC
of the window will be adjusted depending on theGlassType
, based on correlations derived using data reported by PNNL.- clear storm windows: U-factor = U-factor of base window - (0.6435 * U-factor of base window - 0.1533); SHGC = 0.9 * SHGC of base window
- low-e storm windows: U-factor = U-factor of base window - (0.766 * U-factor of base window - 0.1532); SHGC = 0.8 * SHGC of base window
Note that a storm window is not allowed for a window with U-factor lower than 0.45.
[152] 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 aWindow
represents multiple windows, the value is calculated as the total window area for any operable windows divided by the total window area. The total open window area for natural ventilation is calculated using A) the operable fraction, B) the assumption that 50% of the area of operable windows can be open, and C) the assumption that 20% of that openable area is actually opened by occupants whenever outdoor conditions are favorable for cooling.[153] AttachedToWall must reference a
Wall
orFoundationWall
.
Natural Ventilation
If operable windows are defined, the availability of natural ventilation is entered in /HPXML/Building/BuildingDetails/BuildingSummary/extension
.
Element
Type
Units
Constraints
Required
Default
Notes
NaturalVentilationAvailabilityDaysperWeek
integer
days/week
>= 0, <= 7
No
3 [154]
How often windows can be opened by occupants for natural ventilation
[154] Default of 3 days per week (Monday/Wednesday/Friday) is based on 2010 BAHSP.
UFactor/SHGC Lookup
If UFactor and SHGC are not provided and GlassLayers is not “glass block”, additional information is entered in Window
.
Element
Type
Units
Constraints
Required
Default
Notes
FrameType
element
See [155]
Yes
Type of frame
FrameType/*/ThermalBreak
boolean
See [156]
No
false
Whether the Aluminum or Metal frame has a thermal break
GlassType
string
See [157]
No
clear
Type of glass
GasFill
string
See [158]
No
See [159]
Type of gas inside double/triple-pane windows
[155] FrameType child element choices are
Aluminum
,Fiberglass
,Metal
,Vinyl
, orWood
.[156] ThermalBreak is only valid if FrameType is
Aluminum
orMetal
.[157] GlassType choices are “clear”, “low-e”, “low-e, high-solar-gain”, “low-e, low-solar-gain”, “tinted”, “tinted/reflective”, or “reflective”.
[158] GasFill choices are “air”, “argon”, “krypton”, “xenon”, “nitrogen”, or “other”.
[159] If GasFill not provided, defaults to “air” for double-pane, non-low-e windows and “argon” for double-pane, low-e or triple-pane windows.
If UFactor and SHGC are not provided, they are defaulted as follows:
GlassLayers
FrameType
ThermalBreak
GlassType
GasFill
UFactor
SHGC
single-pane
Aluminum, Metal
false
“clear”, “reflective”
–
1.27
0.75
single-pane
Fiberglass, Vinyl, Wood
–
“clear”, “reflective”
–
0.89
0.64
single-pane
Aluminum, Metal
false
“tinted”, “tinted/reflective”
–
1.27
0.64
single-pane
Fiberglass, Vinyl, Wood
–
“tinted”, “tinted/reflective”
–
0.89
0.54
double-pane
Aluminum, Metal
false
“clear”, “reflective”
air
0.81
0.67
double-pane
Aluminum, Metal
true
“clear”, “reflective”
air
0.60
0.67
double-pane
Fiberglass, Vinyl, Wood
–
“clear”, “reflective”
air
0.51
0.56
double-pane
Aluminum, Metal
false
“tinted”, “tinted/reflective”
air
0.81
0.55
double-pane
Aluminum, Metal
true
“tinted”, “tinted/reflective”
air
0.60
0.55
double-pane
Fiberglass, Vinyl, Wood
–
“tinted”, “tinted/reflective”
air
0.51
0.46
double-pane
Fiberglass, Vinyl, Wood
–
“low-e”, “low-e, high-solar-gain”
air
0.42
0.52
double-pane
Aluminum, Metal
true
“low-e”, “low-e, high-solar-gain”
<any but air>
0.47
0.62
double-pane
Fiberglass, Vinyl, Wood
–
“low-e”, “low-e, high-solar-gain”
<any but air>
0.39
0.52
double-pane
Aluminum, Metal
false
“low-e, low-solar-gain”
air
0.67
0.37
double-pane
Aluminum, Metal
true
“low-e, low-solar-gain”
air
0.47
0.37
double-pane
Fiberglass, Vinyl, Wood
–
“low-e, low-solar-gain”
air
0.39
0.31
double-pane
Fiberglass, Vinyl, Wood
–
“low-e, low-solar-gain”
<any but air>
0.36
0.31
triple-pane
Fiberglass, Vinyl, Wood
–
“low-e”, “low-e, high-solar-gain”
<any but air>
0.27
0.31
glass block
–
–
–
–
0.60
0.60
Warning
OpenStudio-HPXML will return an error if the combination of window properties is not in the above table.
HPXML Overhangs
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 [160]
Yes
Vertical distance from overhang to bottom of window [161]
[160] The difference between DistanceToBottomOfWindow and DistanceToTopOfWindow defines the height of the window.
[161] 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
Azimuth
orOrientation
integer or string
deg or direction
>= 0, <= 359 or See [162]
Yes
Direction (clockwise from North)
UFactor
and/orGlassLayers
double or string
Btu/F-ft2-hr
> 0 or See [163]
Yes
Full-assembly NFRC U-factor or glass layers description
SHGC
and/orGlassLayers
double or string
> 0, < 1
Yes
Full-assembly NFRC solar heat gain coefficient or glass layers description
ExteriorShading/SummerShadingCoefficient
double
frac
>= 0, <= 1
No
1.00
Exterior summer shading coefficient (1=transparent, 0=opaque) [164]
ExteriorShading/WinterShadingCoefficient
double
frac
>= 0, <= 1
No
1.00
Exterior winter shading coefficient (1=transparent, 0=opaque)
InteriorShading/SummerShadingCoefficient
double
frac
>= 0, <= 1
No
1.00
Interior summer shading coefficient (1=transparent, 0=opaque)
InteriorShading/WinterShadingCoefficient
double
frac
>= 0, <= 1
No
1.00
Interior winter shading coefficient (1=transparent, 0=opaque)
StormWindow/GlassType
string
See [165]
No
Type of storm window glass
AttachedToRoof
idref
See [166]
Yes
ID of attached roof
[162] Orientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[163] GlassLayers choices are “single-pane”, “double-pane”, or “triple-pane”.
[164] Summer vs winter shading seasons are determined per HPXML Shading Control.
[165] GlassType choices are “clear” or “low-e”. The
UFactor
andSHGC
of the skylight will be adjusted depending on theGlassType
, based on correlations derived using data reported by PNNL.- clear storm windows: U-factor = U-factor of base window - (0.6435 * U-factor of base window - 0.1533); SHGC = 0.9 * SHGC of base window
- low-e storm windows: U-factor = U-factor of base window - (0.766 * U-factor of base window - 0.1532); SHGC = 0.8 * SHGC of base window
Note that a storm window is not allowed for a skylight with U-factor lower than 0.45.
[166] AttachedToRoof must reference a
Roof
.
UFactor/SHGC Lookup
If UFactor and SHGC are not provided and GlassLayers is not “glass block”, additional information is entered in Skylight
.
Element
Type
Units
Constraints
Required
Default
Notes
FrameType
element
See [167]
Yes
Type of frame
FrameType/*/ThermalBreak
boolean
See [168]
No
false
Whether the Aluminum or Metal frame has a thermal break
GlassType
string
See [169]
No
<none>
Type of glass
GasFill
string
See [170]
No
See [171]
Type of gas inside double/triple-pane skylights
[167] FrameType child element choices are
Aluminum
,Fiberglass
,Metal
,Vinyl
, orWood
.[168] ThermalBreak is only valid if FrameType is
Aluminum
orMetal
.[169] GlassType choices are “clear”, “low-e”, “low-e, high-solar-gain”, “low-e, low-solar-gain”, “tinted”, “tinted/reflective”, or “reflective”.
[170] GasFill choices are “air”, “argon”, “krypton”, “xenon”, “nitrogen”, or “other”.
[171] If GasFill not provided, defaults to “air” for double-pane, non-low-e skylights and “argon” for double-pane, low-e or triple-pane skylights.
If UFactor and SHGC are not provided, they are defaulted as follows:
GlassLayers
FrameType
ThermalBreak
GlassType
GasFill
UFactor
SHGC
single-pane
Aluminum, Metal
false
“clear”, “reflective”
–
1.98
0.75
single-pane
Fiberglass, Vinyl, Wood
–
“clear”, “reflective”
–
1.47
0.64
single-pane
Aluminum, Metal
false
“tinted”, “tinted/reflective”
–
1.98
0.64
single-pane
Fiberglass, Vinyl, Wood
–
“tinted”, “tinted/reflective”
–
1.47
0.54
double-pane
Aluminum, Metal
false
“clear”, “reflective”
air
1.30
0.67
double-pane
Aluminum, Metal
true
“clear”, “reflective”
air
1.10
0.67
double-pane
Fiberglass, Vinyl, Wood
–
“clear”, “reflective”
air
0.84
0.56
double-pane
Aluminum, Metal
false
“tinted”, “tinted/reflective”
air
1.30
0.55
double-pane
Aluminum, Metal
true
“tinted”, “tinted/reflective”
air
1.10
0.55
double-pane
Fiberglass, Vinyl, Wood
–
“tinted”, “tinted/reflective”
air
0.84
0.46
double-pane
Fiberglass, Vinyl, Wood
–
“low-e”, “low-e, high-solar-gain”
air
0.74
0.52
double-pane
Aluminum, Metal
true
“low-e”, “low-e, high-solar-gain”
<any but air>
0.95
0.62
double-pane
Fiberglass, Vinyl, Wood
–
“low-e”, “low-e, high-solar-gain”
<any but air>
0.68
0.52
double-pane
Aluminum, Metal
false
“low-e, low-solar-gain”
air
1.17
0.37
double-pane
Aluminum, Metal
true
“low-e, low-solar-gain”
air
0.98
0.37
double-pane
Fiberglass, Vinyl, Wood
–
“low-e, low-solar-gain”
air
0.71
0.31
double-pane
Fiberglass, Vinyl, Wood
–
“low-e, low-solar-gain”
<any but air>
0.65
0.31
triple-pane
Fiberglass, Vinyl, Wood
–
“low-e”, “low-e, high-solar-gain”
<any but air>
0.47
0.31
glass block
–
–
–
–
0.60
0.60
Warning
OpenStudio-HPXML will return an error if the combination of skylight properties is not in the above table.
HPXML Doors
Each opaque door 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 [172]
Yes
ID of attached wall
Area
double
ft2
> 0
Yes
Total area
Azimuth
orOrientation
integer or string
deg
>= 0, <= 359 or See [173]
No
See [174]
Direction (clockwise from North)
RValue
double
F-ft2-hr/Btu
> 0
Yes
R-value (including any storm door)
[172] AttachedToWall must reference a
Wall
orFoundationWall
.[173] Orientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[174] If neither Azimuth nor Orientation nor AttachedToWall azimuth provided, defaults to the azimuth with the largest surface area defined in the HPXML file.
HPXML Partition Wall Mass
Partition wall mass in the conditioned space is entered as /HPXML/Building/BuildingDetails/Enclosure/extension/PartitionWallMass
.
Element
Type
Units
Constraints
Required
Default
Notes
AreaFraction
double
frac
>= 0
No
1.0
Fraction of both sides of wall area to conditioned floor area
InteriorFinish/Type
string
See [175]
No
gypsum board
Interior finish material
InteriorFinish/Thickness
double
in
>= 0
No
0.5
Interior finish thickness
[175] InteriorFinish/Type choices are “gypsum board”, “gypsum composite board”, “plaster”, “wood”, “other”, or “none”.
HPXML Furniture Mass
Furniture mass in the conditioned space is entered as /HPXML/Building/BuildingDetails/Enclosure/extension/FurnitureMass
.
Note
Light-weight furniture is modeled with a weight of 8 lb/ft2 of floor area and a density of 40 lb/ft3 while heavy-weight furniture is modeled with a weight of 16 lb/ft2 of floor area and a density of 80 lb/ft3.
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
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
HeatingSystemType/ElectricResistance/ElectricDistribution
string
See [177]
No
baseboard
Type of electric resistance distribution
HeatingSystemFuel
string
electricity
Yes
Fuel type
HeatingCapacity
double
Btu/hr
>= 0
No
autosized [178]
Heating output capacity
AnnualHeatingEfficiency[Units="Percent"]/Value
double
frac
> 0, <= 1
Yes
Efficiency
FractionHeatLoadServed
double
frac
>= 0, <= 1 [179]
See [180]
Fraction of heating load served
extension/HeatingAutosizingFactor
double
frac
> 0
No
1.0
Heating autosizing scaling factor
[177] ElectricDistribution choices are “baseboard”, “radiant floor”, or “radiant ceiling”.
[178] Heating capacity autosized per ACCA Manual J/S based on heating design load.
[179] The sum of all
FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.[180] FractionHeatLoadServed is required unless the heating system is a heat pump backup system (i.e., referenced by a
HeatPump[BackupType="separate"]/BackupSystem
; see HPXML Heat Pumps), in which case FractionHeatLoadServed is not allowed. Heat pump backup will only operate during colder temperatures when the heat pump runs out of heating capacity or is disabled due to a switchover/lockout temperature.
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
UnitLocation
string
See [181]
No
See [182]
Location of air handler
DistributionSystem
idref
See [183]
Yes
ID of attached distribution system
HeatingSystemType/Furnace
element
Yes
Type of heating system
HeatingSystemType/Furnace/PilotLight
boolean
No
false
Presence of standing pilot light (older systems)
HeatingSystemType/Furnace/extension/PilotLightBtuh
double
Btu/hr
>= 0
No
500
Pilot light burn rate
HeatingSystemFuel
string
See [184]
Yes
Fuel type
HeatingCapacity
double
Btu/hr
>= 0
No
autosized [185]
Heating output capacity
AnnualHeatingEfficiency[Units="AFUE"]/Value
double
frac
> 0, <= 1
Yes
Rated efficiency
FractionHeatLoadServed
double
frac
>= 0, <= 1 [186]
See [187]
Fraction of heating load served
extension/FanPowerWattsPerCFM
double
W/cfm
>= 0
No
See [188]
Blower fan efficiency at maximum fan speed [189]
extension/AirflowDefectRatio
double
frac
>= -0.9, <= 9
No
0.0
Deviation between design/installed airflows [190]
extension/HeatingAutosizingFactor
double
frac
> 0
No
1.0
Heating autosizing scaling factor
[181] UnitLocation choices are “conditioned space”, “basement - unconditioned”, “basement - conditioned”, “attic - unvented”, “attic - vented”, “garage”, “crawlspace - unvented”, “crawlspace - vented”, “crawlspace - conditioned”, “other exterior”, “other housing unit”, “other heated space”, “other multifamily buffer space”, “other non-freezing space”, “roof deck”, “manufactured home belly”, or “unconditioned space”.
[182] If UnitLocation not provided, defaults based on the distribution system:
- Air: supply duct location with the largest area, otherwise “conditioned space”
- DSE: “conditioned space” if
FractionHeatLoadServed
is 1, otherwise “unconditioned space”[183] HVACDistribution type must be Air Distribution (type: “regular velocity” or “gravity”) or Distribution System Efficiency (DSE).
[184] HeatingSystemFuel choices are “electricity”, “natural gas”, “fuel oil”, “fuel oil 1”, “fuel oil 2”, “fuel oil 4”, “fuel oil 5/6”, “diesel”, “propane”, “kerosene”, “coal”, “coke”, “bituminous coal”, “wood”, or “wood pellets”.
[185] Heating capacity autosized per ACCA Manual J/S based on heating design load.
[186] The sum of all
FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.[187] FractionHeatLoadServed is required unless the heating system is a heat pump backup system (i.e., referenced by a
HeatPump[BackupType="separate"]/BackupSystem
; see HPXML Heat Pumps), in which case FractionHeatLoadServed is not allowed. Heat pump backup will only operate during colder temperatures when the heat pump runs out of heating capacity or is disabled due to a switchover/lockout temperature.[188] If FanPowerWattsPerCFM not provided, defaulted to 0 W/cfm if gravity distribution system, else 0.5 W/cfm if AFUE <= 0.9, else 0.375 W/cfm.
[189] If there is a cooling system attached to the DistributionSystem, the heating and cooling systems cannot have different values for FanPowerWattsPerCFM.
[190] AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect. See ANSI/RESNET/ACCA 310-2020 for more information.
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
HeatingSystemType/WallFurnace/PilotLight
boolean
No
false
Presence of standing pilot light (older systems)
HeatingSystemType/WallFurnace/extension/PilotLightBtuh
double
Btu/hr
>= 0
No
500
Pilot light burn rate
HeatingSystemFuel
string
See [191]
Yes
Fuel type
HeatingCapacity
double
Btu/hr
>= 0
No
autosized [192]
Heating output capacity
AnnualHeatingEfficiency[Units="AFUE"]/Value
double
frac
> 0, <= 1
Yes
Rated efficiency
FractionHeatLoadServed
double
frac
>= 0, <= 1 [193]
See [194]
Fraction of heating load served
extension/FanPowerWatts
double
W
>= 0
No
0
Fan power
extension/HeatingAutosizingFactor
double
frac
> 0
No
1.0
Heating autosizing scaling factor
[191] HeatingSystemFuel choices are “electricity”, “natural gas”, “fuel oil”, “fuel oil 1”, “fuel oil 2”, “fuel oil 4”, “fuel oil 5/6”, “diesel”, “propane”, “kerosene”, “coal”, “coke”, “bituminous coal”, “wood”, or “wood pellets”.
[192] Heating capacity autosized per ACCA Manual J/S based on heating design load.
[193] The sum of all
FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.[194] FractionHeatLoadServed is required unless the heating system is a heat pump backup system (i.e., referenced by a
HeatPump[BackupType="separate"]/BackupSystem
; see HPXML Heat Pumps), in which case FractionHeatLoadServed is not allowed. Heat pump backup will only operate during colder temperatures when the heat pump runs out of heating capacity or is disabled due to a switchover/lockout temperature.
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
HeatingSystemType/FloorFurnace/PilotLight
boolean
No
false
Presence of standing pilot light (older systems)
HeatingSystemType/FloorFurnace/extension/PilotLightBtuh
double
Btu/hr
>= 0
No
500
Pilot light burn rate
HeatingSystemFuel
string
See [195]
Yes
Fuel type
HeatingCapacity
double
Btu/hr
>= 0
No
autosized [196]
Heating output capacity
AnnualHeatingEfficiency[Units="AFUE"]/Value
double
frac
> 0, <= 1
Yes
Rated efficiency
FractionHeatLoadServed
double
frac
>= 0, <= 1 [197]
See [198]
Fraction of heating load served
extension/FanPowerWatts
double
W
>= 0
No
0
Fan power
extension/HeatingAutosizingFactor
double
frac
> 0
No
1.0
Heating autosizing scaling factor
[195] HeatingSystemFuel choices are “electricity”, “natural gas”, “fuel oil”, “fuel oil 1”, “fuel oil 2”, “fuel oil 4”, “fuel oil 5/6”, “diesel”, “propane”, “kerosene”, “coal”, “coke”, “bituminous coal”, “wood”, or “wood pellets”.
[196] Heating capacity autosized per ACCA Manual J/S based on heating design load.
[197] The sum of all
FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.[198] FractionHeatLoadServed is required unless the heating system is a heat pump backup system (i.e., referenced by a
HeatPump[BackupType="separate"]/BackupSystem
; see HPXML Heat Pumps), in which case FractionHeatLoadServed is not allowed. Heat pump backup will only operate during colder temperatures when the heat pump runs out of heating capacity or is disabled due to a switchover/lockout temperature.
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
UnitLocation
string
See [199]
No
See [200]
Location of boiler
DistributionSystem
idref
See [201]
Yes
ID of attached distribution system
HeatingSystemType/Boiler
element
Yes
Type of heating system
HeatingSystemType/Boiler/PilotLight
boolean
No
false
Presence of standing pilot light (older systems)
HeatingSystemType/Boiler/extension/PilotLightBtuh
double
Btu/hr
>= 0
No
500
Pilot light burn rate
HeatingSystemFuel
string
See [202]
Yes
Fuel type
HeatingCapacity
double
Btu/hr
>= 0
No
autosized [203]
Heating output capacity
AnnualHeatingEfficiency[Units="AFUE"]/Value
double
frac
> 0, <= 1
Yes
Rated efficiency
FractionHeatLoadServed
double
frac
>= 0, <= 1 [204]
See [205]
Fraction of heating load served
ElectricAuxiliaryEnergy
double
kWh/yr
>= 0
No
See [206]
Electric auxiliary energy
extension/HeatingAutosizingFactor
double
frac
> 0
No
1.0
Heating autosizing scaling factor
[199] UnitLocation choices are “conditioned space”, “basement - unconditioned”, “basement - conditioned”, “attic - unvented”, “attic - vented”, “garage”, “crawlspace - unvented”, “crawlspace - vented”, “crawlspace - conditioned”, “other exterior”, “other housing unit”, “other heated space”, “other multifamily buffer space”, “other non-freezing space”, “roof deck”, “manufactured home belly”, or “unconditioned space”.
[200] If UnitLocation not provided, defaults based on the distribution system:
- Hydronic: same default logic as HPXML Water Heating Systems
- DSE: “conditioned space” if
FractionHeatLoadServed
is 1, otherwise “unconditioned space”[201] 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.
[202] HeatingSystemFuel choices are “electricity”, “natural gas”, “fuel oil”, “fuel oil 1”, “fuel oil 2”, “fuel oil 4”, “fuel oil 5/6”, “diesel”, “propane”, “kerosene”, “coal”, “coke”, “bituminous coal”, “wood”, or “wood pellets”.
[203] Heating capacity autosized per ACCA Manual J/S based on heating design load.
[204] The sum of all
FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.[205] FractionHeatLoadServed is required unless the heating system is a heat pump backup system (i.e., referenced by a
HeatPump[BackupType="separate"]/BackupSystem
; see HPXML Heat Pumps), in which case FractionHeatLoadServed is not allowed. Heat pump backup will only operate during colder temperatures when the heat pump runs out of heating capacity or is disabled due to a switchover/lockout temperature.[206] If ElectricAuxiliaryEnergy not provided, defaults as follows per ANSI/RESNET/ICC 301-2019:
- Oil boiler: 330 kWh/yr
- Gas boiler: 170 kWh/yr
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
HeatingSystemType/Stove/PilotLight
boolean
No
false
Presence of standing pilot light (older systems)
HeatingSystemType/Stove/extension/PilotLightBtuh
double
Btu/hr
>= 0
No
500
Pilot light burn rate
HeatingSystemFuel
string
See [214]
Yes
Fuel type
HeatingCapacity
double
Btu/hr
>= 0
No
autosized [215]
Heating output capacity
AnnualHeatingEfficiency[Units="Percent"]/Value
double
frac
> 0, <= 1
Yes
Efficiency
FractionHeatLoadServed
double
frac
>= 0, <= 1 [216]
See [217]
Fraction of heating load served
extension/FanPowerWatts
double
W
>= 0
No
40
Fan power
extension/HeatingAutosizingFactor
double
frac
> 0
No
1.0
Heating autosizing scaling factor
[214] HeatingSystemFuel choices are “electricity”, “natural gas”, “fuel oil”, “fuel oil 1”, “fuel oil 2”, “fuel oil 4”, “fuel oil 5/6”, “diesel”, “propane”, “kerosene”, “coal”, “coke”, “bituminous coal”, “wood”, or “wood pellets”.
[215] Heating capacity autosized per ACCA Manual J/S based on heating design load.
[216] The sum of all
FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.[217] FractionHeatLoadServed is required unless the heating system is a heat pump backup system (i.e., referenced by a
HeatPump[BackupType="separate"]/BackupSystem
; see HPXML Heat Pumps), in which case FractionHeatLoadServed is not allowed. Heat pump backup will only operate during colder temperatures when the heat pump runs out of heating capacity or is disabled due to a switchover/lockout temperature.
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 [218]
Yes
Fuel type
HeatingCapacity
double
Btu/hr
>= 0
No
autosized [219]
Heating output capacity
AnnualHeatingEfficiency[Units="Percent"]/Value
double
frac
> 0, <= 1
Yes
Efficiency
FractionHeatLoadServed
double
frac
>= 0, <= 1 [220]
See [221]
Fraction of heating load served
extension/FanPowerWatts
double
W
>= 0
No
0
Fan power
extension/HeatingAutosizingFactor
double
frac
> 0
No
1.0
Heating autosizing scaling factor
[218] HeatingSystemFuel choices are “electricity”, “natural gas”, “fuel oil”, “fuel oil 1”, “fuel oil 2”, “fuel oil 4”, “fuel oil 5/6”, “diesel”, “propane”, “kerosene”, “coal”, “coke”, “bituminous coal”, “wood”, or “wood pellets”.
[219] Heating capacity autosized per ACCA Manual J/S based on heating design load.
[220] The sum of all
FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.[221] FractionHeatLoadServed is required unless the heating system is a heat pump backup system (i.e., referenced by a
HeatPump[BackupType="separate"]/BackupSystem
; see HPXML Heat Pumps), in which case FractionHeatLoadServed is not allowed. Heat pump backup will only operate during colder temperatures when the heat pump runs out of heating capacity or is disabled due to a switchover/lockout temperature.
Fireplace
Each fireplace is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatingSystem
.
Instead of modeling fireplaces as serving a fraction of the heating load, fireplaces can be assigned a therm/year usage using HPXML Fuel Loads.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
HeatingSystemType/Fireplace
element
Yes
Type of heating system
HeatingSystemType/Fireplace/PilotLight
boolean
No
false
Presence of standing pilot light (older systems)
HeatingSystemType/Fireplace/extension/PilotLightBtuh
double
Btu/hr
>= 0
No
500
Pilot light burn rate
HeatingSystemFuel
string
See [222]
Yes
Fuel type
HeatingCapacity
double
Btu/hr
>= 0
No
autosized [223]
Heating output capacity
AnnualHeatingEfficiency[Units="Percent"]/Value
double
frac
> 0, <= 1
Yes
Efficiency
FractionHeatLoadServed
double
frac
>= 0, <= 1 [224]
See [225]
Fraction of heating load served
extension/FanPowerWatts
double
W
>= 0
No
0
Fan power
extension/HeatingAutosizingFactor
double
frac
> 0
No
1.0
Heating autosizing scaling factor
[222] HeatingSystemFuel choices are “electricity”, “natural gas”, “fuel oil”, “fuel oil 1”, “fuel oil 2”, “fuel oil 4”, “fuel oil 5/6”, “diesel”, “propane”, “kerosene”, “coal”, “coke”, “bituminous coal”, “wood”, or “wood pellets”.
[223] Heating capacity autosized per ACCA Manual J/S based on heating design load.
[224] The sum of all
FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.[225] FractionHeatLoadServed is required unless the heating system is a heat pump backup system (i.e., referenced by a
HeatPump[BackupType="separate"]/BackupSystem
; see HPXML Heat Pumps), in which case FractionHeatLoadServed is not allowed. Heat pump backup will only operate during colder temperatures when the heat pump runs out of heating capacity or is disabled due to a switchover/lockout temperature.
HPXML Cooling Systems
The following cooling system types can be modeled:
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
UnitLocation
string
See [226]
No
See [227]
Location of air handler
DistributionSystem
idref
See [228]
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
No
autosized [229]
Cooling output capacity
CompressorType
string
See [230]
No
See [231]
Type of compressor
FractionCoolLoadServed
double
frac
>= 0, <= 1 [232]
Yes
Fraction of cooling load served
AnnualCoolingEfficiency[Units="SEER" or Units="SEER2"]/Value
double
Btu/Wh or #
> 0
Yes
Rated efficiency [233]
SensibleHeatFraction
double
frac
> 0.5, <= 1
No
See [234]
Sensible heat fraction
CoolingDetailedPerformanceData
element
No
<none>
Cooling detailed performance data [235]
extension/FanPowerWattsPerCFM
double
W/cfm
>= 0
No
See [236]
Blower fan efficiency at maximum fan speed [237]
extension/AirflowDefectRatio
double
frac
>= -0.9, <= 9
No
0.0
Deviation between design/installed airflows [238]
extension/ChargeDefectRatio
double
frac
>= -0.9, <= 9
No
0.0
Deviation between design/installed refrigerant charges [239]
extension/CrankcaseHeaterPowerWatts
double
W
>= 0
No
50.0
Crankcase heater power
extension/CoolingAutosizingFactor
double
frac
> 0
No
1.0
Cooling autosizing scaling factor
[226] UnitLocation choices are “conditioned space”, “basement - unconditioned”, “basement - conditioned”, “attic - unvented”, “attic - vented”, “garage”, “crawlspace - unvented”, “crawlspace - vented”, “crawlspace - conditioned”, “other exterior”, “other housing unit”, “other heated space”, “other multifamily buffer space”, “other non-freezing space”, “roof deck”, “manufactured home belly”, or “unconditioned space”.
[227] If UnitLocation not provided, defaults based on the distribution system:
- Air: supply duct location with the largest area, otherwise “conditioned space”
- DSE: “conditioned space” if
FractionCoolLoadServed
is 1, otherwise “unconditioned space”[228] HVACDistribution type must be Air Distribution (type: “regular velocity”) or Distribution System Efficiency (DSE).
[229] Cooling capacity autosized per ACCA Manual J/S based on cooling design load.
[230] CompressorType choices are “single stage”, “two stage”, or “variable speed”.
[231] If CompressorType not provided, defaults to “single stage” if SEER <= 15, else “two stage” if SEER <= 21, else “variable speed”.
[232] The sum of all
FractionCoolLoadServed
(across all HVAC systems) must be less than or equal to 1.[233] If SEER2 provided, converted to SEER using ANSI/RESNET/ICC 301-2022 Addendum C, where SEER = SEER2 / 0.95 (assumed to be a split system).
[234] If SensibleHeatFraction not provided, defaults to 0.73 for single/two stage and 0.78 for variable speed.
[235] If CoolingDetailedPerformanceData is provided, see Detailed Cooling Performance Data.
[236] If FanPowerWattsPerCFM not provided, defaults to using attached furnace W/cfm if available, else 0.5 W/cfm if SEER <= 13.5, else 0.375 W/cfm.
[237] If there is a heating system attached to the DistributionSystem, the heating and cooling systems cannot have different values for FanPowerWattsPerCFM.
[238] AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect. See ANSI/RESNET/ACCA 310-2020 for more information.
[239] 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 for more information.
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
No
autosized [240]
Cooling output capacity
FractionCoolLoadServed
double
frac
>= 0, <= 1 [241]
Yes
Fraction of cooling load served
AnnualCoolingEfficiency[Units="EER" or Units="CEER"]/Value
double
Btu/Wh
> 0
Yes
Rated efficiency
SensibleHeatFraction
double
frac
> 0.5, <= 1
No
0.65
Sensible heat fraction
IntegratedHeatingSystemFuel
string
See [242]
No
<none>
Fuel type of integrated heater
extension/CrankcaseHeaterPowerWatts
double
W
>= 0
No
0.0
Crankcase heater power
extension/CoolingAutosizingFactor
double
frac
> 0
No
1.0
Cooling autosizing scaling factor
[240] Cooling capacity autosized per ACCA Manual J/S based on cooling design load.
[241] The sum of all
FractionCoolLoadServed
(across all HVAC systems) must be less than or equal to 1.[242] IntegratedHeatingSystemFuel choices are “electricity”, “natural gas”, “fuel oil”, “fuel oil 1”, “fuel oil 2”, “fuel oil 4”, “fuel oil 5/6”, “diesel”, “propane”, “kerosene”, “coal”, “coke”, “bituminous coal”, “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
No
autosized [243]
Heating output capacity of integrated heater
IntegratedHeatingSystemAnnualEfficiency[Units="Percent"]/Value
double
frac
> 0, <= 1
Yes
Efficiency of integrated heater
IntegratedHeatingSystemFractionHeatLoadServed
double
frac
>= 0, <= 1 [244]
Yes
Fraction of heating load served
[243] Heating capacity autosized per ACCA Manual J/S based on heating design load.
[244] 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
No
autosized [245]
Cooling output capacity
FractionCoolLoadServed
double
frac
>= 0, <= 1 [246]
Yes
Fraction of cooling load served
AnnualCoolingEfficiency[Units="EER" or Units="CEER"]/Value
double
Btu/Wh
> 0
Yes
Rated efficiency
SensibleHeatFraction
double
frac
> 0.5, <= 1
No
0.65
Sensible heat fraction
IntegratedHeatingSystemFuel
string
See [247]
No
<none>
Fuel type of integrated heater
extension/CrankcaseHeaterPowerWatts
double
W
>= 0
No
0.0
Crankcase heater power
extension/CoolingAutosizingFactor
double
frac
> 0
No
1.0
Cooling autosizing scaling factor
[245] Cooling capacity autosized per ACCA Manual J/S based on cooling design load.
[246] The sum of all
FractionCoolLoadServed
(across all HVAC systems) must be less than or equal to 1.[247] IntegratedHeatingSystemFuel choices are “electricity”, “natural gas”, “fuel oil”, “fuel oil 1”, “fuel oil 2”, “fuel oil 4”, “fuel oil 5/6”, “diesel”, “propane”, “kerosene”, “coal”, “coke”, “bituminous coal”, “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
No
autosized [248]
Heating output capacity of integrated heater
IntegratedHeatingSystemAnnualEfficiency[Units="Percent"]/Value
double
frac
> 0, <= 1
Yes
Efficiency of integrated heater
IntegratedHeatingSystemFractionHeatLoadServed
double
frac
>= 0, <= 1 [249]
Yes
Fraction of heating load served
[248] Heating capacity autosized per ACCA Manual J/S based on heating design load.
[249] 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 [250]
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
No
autosized [251]
Cooling output capacity
FractionCoolLoadServed
double
frac
>= 0, <= 1 [252]
Yes
Fraction of cooling load served
extension/CoolingAutosizingFactor
double
frac
> 0
No
1.0
Cooling autosizing scaling factor
[250] If DistributionSystem provided, HVACDistribution type must be Air Distribution (type: “regular velocity”) or Distribution System Efficiency (DSE).
[251] Cooling capacity autosized per ACCA Manual J/S based on cooling design load.
[252] 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
UnitLocation
string
See [253]
No
See [254]
Location of air handler
DistributionSystem
idref
See [255]
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
No
autosized [256]
Cooling output capacity
CompressorType
string
See [257]
No
variable speed
Type of compressor
FractionCoolLoadServed
double
frac
>= 0, <= 1 [258]
Yes
Fraction of cooling load served
AnnualCoolingEfficiency[Units="SEER" or Units="SEER2"]/Value
double
Btu/Wh
> 0
Yes
Rated cooling efficiency [259]
SensibleHeatFraction
double
frac
> 0.5, <= 1
No
0.73
Sensible heat fraction
CoolingDetailedPerformanceData
element
No
<none>
Cooling detailed performance data [260]
extension/FanPowerWattsPerCFM
double
W/cfm
>= 0
No
See [261]
Blower fan efficiency at maximum fan speed
extension/AirflowDefectRatio
double
frac
>= -0.9, <= 9
No
0.0
Deviation between design/installed airflows [262]
extension/ChargeDefectRatio
double
frac
>= -0.9, <= 9
No
0.0
Deviation between design/installed refrigerant charges [263]
extension/CrankcaseHeaterPowerWatts
double
W
>= 0
No
50.0
Crankcase heater power
extension/CoolingAutosizingFactor
double
frac
> 0
No
1.0
Cooling autosizing scaling factor
[253] UnitLocation choices are “conditioned space”, “basement - unconditioned”, “basement - conditioned”, “attic - unvented”, “attic - vented”, “garage”, “crawlspace - unvented”, “crawlspace - vented”, “crawlspace - conditioned”, “other exterior”, “other housing unit”, “other heated space”, “other multifamily buffer space”, “other non-freezing space”, “roof deck”, “manufactured home belly”, or “unconditioned space”.
[254] If UnitLocation not provided, defaults based on the distribution system:
- Air: supply duct location with the largest area, otherwise “conditioned space”
- DSE: “conditioned space” if
FractionCoolLoadServed
is 1, otherwise “unconditioned space”[255] If DistributionSystem provided, HVACDistribution type must be Air Distribution (type: “regular velocity”) or Distribution System Efficiency (DSE).
[256] Cooling capacity autosized per ACCA Manual J/S based on cooling design load.
[257] CompressorType only choices is “variable speed” (i.e., they are assumed to be inverter driven).
[258] The sum of all
FractionCoolLoadServed
(across all HVAC systems) must be less than or equal to 1.[259] If SEER2 provided, converted to SEER using ANSI/RESNET/ICC 301-2022 Addendum C, where SEER = SEER2 / 0.95 if ducted and SEER = SEER2 if ductless.
[260] If CoolingDetailedPerformanceData is provided, see Detailed Cooling Performance Data.
[261] FanPowerWattsPerCFM defaults to 0.07 W/cfm for ductless systems and 0.18 W/cfm for ducted systems.
[262] 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 for more information.
[263] 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 for more information.
HPXML Heat Pumps
The following heat pump types can be modeled:
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
UnitLocation
string
See [269]
No
See [270]
Location of air handler
DistributionSystem
idref
See [271]
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
No
autosized [272]
Heating output capacity (excluding any backup heating)
HeatingCapacity17F
double
Btu/hr
>= 0, <= HeatingCapacity
No
Heating output capacity at 17F, if available
CoolingCapacity
double
Btu/hr
>= 0
No
autosized [273]
Cooling output capacity
CompressorType
string
See [274]
No
See [275]
Type of compressor
CompressorLockoutTemperature
double
F
No
See [276]
Minimum outdoor temperature for compressor operation
CoolingSensibleHeatFraction
double
frac
> 0.5, <= 1
No
See [277]
Sensible heat fraction
BackupType
string
See [278]
No
<none>
Type of backup heating
FractionHeatLoadServed
double
frac
>= 0, <= 1 [279]
Yes
Fraction of heating load served
FractionCoolLoadServed
double
frac
>= 0, <= 1 [280]
Yes
Fraction of cooling load served
AnnualCoolingEfficiency[Units="SEER" or Units="SEER2"]/Value
double
Btu/Wh
> 0
Yes
Rated cooling efficiency [281]
AnnualHeatingEfficiency[Units="HSPF" or Units="HSPF2"]/Value
double
Btu/Wh
> 0
Yes
Rated heating efficiency [282]
CoolingDetailedPerformanceData
element
No
<none>
Cooling detailed performance data [283]
HeatingDetailedPerformanceData
element
No
<none>
Heating detailed performance data [284]
extension/HeatingCapacityRetention[Fraction | Temperature]
double
frac | F
>= 0, < 1 | <= 17
No
See [285]
Heating output capacity retention at cold temperature [286]
extension/FanPowerWattsPerCFM
double
W/cfm
>= 0
No
See [287]
Blower fan efficiency at maximum fan speed
extension/AirflowDefectRatio
double
frac
>= -0.9, <= 9
No
0.0
Deviation between design/installed airflows [288]
extension/ChargeDefectRatio
double
frac
>= -0.9, <= 9
No
0.0
Deviation between design/installed refrigerant charges [289]
extension/CrankcaseHeaterPowerWatts
double
W
>= 0
No
50.0
Crankcase heater power
extension/CoolingAutosizingFactor
double
frac
> 0
No
1.0
Cooling autosizing scaling factor
extension/HeatingAutosizingFactor
double
frac
> 0
No
1.0
Heating autosizing scaling factor
[269] UnitLocation choices are “conditioned space”, “basement - unconditioned”, “basement - conditioned”, “attic - unvented”, “attic - vented”, “garage”, “crawlspace - unvented”, “crawlspace - vented”, “crawlspace - conditioned”, “other exterior”, “other housing unit”, “other heated space”, “other multifamily buffer space”, “other non-freezing space”, “roof deck”, “manufactured home belly”, or “unconditioned space”.
[270] If UnitLocation not provided, defaults based on the distribution system:
- Air: supply duct location with the largest area, otherwise “conditioned space”
- DSE: “conditioned space” if
FractionHeatLoadServed
/FractionCoolLoadServed
are 1, otherwise “unconditioned space”[271] HVACDistribution type must be Air Distribution (type: “regular velocity”) or Distribution System Efficiency (DSE).
[272] Heating capacity autosized per ACCA Manual J/S based on heating design load (unless a different HeatPumpSizingMethodology was selected in HPXML HVAC Sizing Control).
[273] Cooling capacity autosized per ACCA Manual J/S based on cooling design load (unless a different HeatPumpSizingMethodology was selected in HPXML HVAC Sizing Control).
[274] CompressorType choices are “single stage”, “two stage”, or “variable speed”.
[275] If CompressorType not provided, defaults to “single stage” if SEER <= 15, else “two stage” if SEER <= 21, else “variable speed”.
[276] If neither CompressorLockoutTemperature nor BackupHeatingSwitchoverTemperature provided, CompressorLockoutTemperature defaults to 25F if fossil fuel backup otherwise -20F if CompressorType is “variable speed” otherwise 0F.
[277] If SensibleHeatFraction not provided, defaults to 0.73 for single/two stage and 0.78 for variable speed.
[278] BackupType choices are “integrated” or “separate”. Heat pump backup will only operate during colder temperatures when the heat pump runs out of heating capacity or is disabled due to a switchover/lockout temperature. Use “integrated” if the heat pump’s distribution system and blower fan power applies to the backup heating (e.g., built-in electric strip heat or an integrated backup furnace, i.e., a dual-fuel heat pump). Use “separate” if the backup system has its own distribution system (e.g., electric baseboard or a boiler). Additional backup inputs are described in Backup.
[279] The sum of all
FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.[280] The sum of all
FractionCoolLoadServed
(across all HVAC systems) must be less than or equal to 1.[281] If SEER2 provided, converted to SEER using ANSI/RESNET/ICC 301-2022 Addendum C, where SEER = SEER2 / 0.95 (assumed to be a split system).
[282] If HSPF2 provided, converted to HSPF using ANSI/RESNET/ICC 301-2022 Addendum C, where HSPF = HSPF2 / 0.85 (assumed to be a split system).
[283] If CoolingDetailedPerformanceData is provided, see Detailed Cooling Performance Data.
[284] If HeatingDetailedPerformanceData is provided, see Detailed Heating Performance Data.
[285] If neither extension/HeatingCapacityRetention nor HeatingCapacity17F nor HeatingDetailedPerformanceData provided, heating capacity retention defaults based on CompressorType:
- single/two stage: 0.425 (at 5F)
- variable speed: 0.0461 * HSPF + 0.1594 (at 5F)
[286] The extension/HeatingCapacityRetention input is a more flexible alternative to HeatingCapacity17F, as it can apply to autosized systems and allows the heating capacity retention to be defined at a user-specified temperature (instead of 17F). Either input approach can be used, but not both.
[287] If FanPowerWattsPerCFM not provided, defaulted to 0.5 W/cfm if HSPF <= 8.75, else 0.375 W/cfm.
[288] AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect. See ANSI/RESNET/ACCA 310-2020 for more information.
[289] 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 for more information.
Mini-Split Heat Pump
Each mini-split heat pump is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatPump
.
Each HeatPump
is expected to 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
UnitLocation
string
See [290]
No
See [291]
Location of air handler
DistributionSystem
idref
See [292]
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
No
autosized [293]
Heating output capacity (excluding any backup heating)
HeatingCapacity17F
double
Btu/hr
>= 0, <= HeatingCapacity
No
Heating output capacity at 17F, if available
CoolingCapacity
double
Btu/hr
>= 0
No
autosized [294]
Cooling output capacity
CompressorType
string
See [295]
No
variable speed
Type of compressor
CompressorLockoutTemperature
double
F
No
See [296]
Minimum outdoor temperature for compressor operation
CoolingSensibleHeatFraction
double
frac
> 0.5, <= 1
No
0.73
Sensible heat fraction
BackupType
string
See [297]
No
<none>
Type of backup heating
FractionHeatLoadServed
double
frac
>= 0, <= 1 [298]
Yes
Fraction of heating load served
FractionCoolLoadServed
double
frac
>= 0, <= 1 [299]
Yes
Fraction of cooling load served
AnnualCoolingEfficiency[Units="SEER" or Units="SEER2"]/Value
double
Btu/Wh
> 0
Yes
Rated cooling efficiency [300]
AnnualHeatingEfficiency[Units="HSPF" or Units="HSPF2"]/Value
double
Btu/Wh
> 0
Yes
Rated heating efficiency [301]
CoolingDetailedPerformanceData
element
No
<none>
Cooling detailed performance data [302]
HeatingDetailedPerformanceData
element
No
<none>
Heating detailed performance data [303]
extension/HeatingCapacityRetention[Fraction | Temperature]
double
frac | F
>= 0, < 1 | <= 17
No
See [304]
Heating output capacity retention at cold temperature [305]
extension/FanPowerWattsPerCFM
double
W/cfm
>= 0
No
See [306]
Blower fan efficiency at maximum fan speed
extension/AirflowDefectRatio
double
frac
>= -0.9, <= 9
No
0.0
Deviation between design/installed airflows [307]
extension/ChargeDefectRatio
double
frac
>= -0.9, <= 9
No
0.0
Deviation between design/installed refrigerant charges [308]
extension/CrankcaseHeaterPowerWatts
double
W
>= 0
No
50.0
Crankcase heater power
extension/CoolingAutosizingFactor
double
frac
> 0
No
1.0
Cooling autosizing scaling factor
extension/HeatingAutosizingFactor
double
frac
> 0
No
1.0
Heating autosizing scaling factor
[290] UnitLocation choices are “conditioned space”, “basement - unconditioned”, “basement - conditioned”, “attic - unvented”, “attic - vented”, “garage”, “crawlspace - unvented”, “crawlspace - vented”, “crawlspace - conditioned”, “other exterior”, “other housing unit”, “other heated space”, “other multifamily buffer space”, “other non-freezing space”, “roof deck”, “manufactured home belly”, or “unconditioned space”.
[291] If UnitLocation not provided, defaults based on the distribution system:
- Air: supply duct location with the largest area, otherwise “conditioned space”
- DSE: “conditioned space” if
FractionHeatLoadServed
/FractionCoolLoadServed
are 1, otherwise “unconditioned space”[292] If DistributionSystem provided, HVACDistribution type must be Air Distribution (type: “regular velocity”) or Distribution System Efficiency (DSE).
[293] Heating capacity autosized per ACCA Manual J/S based on heating design load (unless a different HeatPumpSizingMethodology was selected in HPXML HVAC Sizing Control).
[294] Cooling capacity autosized per ACCA Manual J/S based on cooling design load (unless a different HeatPumpSizingMethodology was selected in HPXML HVAC Sizing Control).
[295] CompressorType only choice is “variable speed” (i.e., they are assumed to be inverter driven).
[296] If neither CompressorLockoutTemperature nor BackupHeatingSwitchoverTemperature provided, CompressorLockoutTemperature defaults to 25F if fossil fuel backup otherwise -20F.
[297] BackupType choices are “integrated” or “separate”. Heat pump backup will only operate during colder temperatures when the heat pump runs out of heating capacity or is disabled due to a switchover/lockout temperature. Use “integrated” if the heat pump’s distribution system and blower fan power applies to the backup heating (e.g., built-in electric strip heat or an integrated backup furnace, i.e., a dual-fuel heat pump). Use “separate” if the backup system has its own distribution system (e.g., electric baseboard or a boiler). Additional backup inputs are described in Backup.
[298] The sum of all
FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.[299] The sum of all
FractionCoolLoadServed
(across all HVAC systems) must be less than or equal to 1.[300] If SEER2 provided, converted to SEER using ANSI/RESNET/ICC 301-2022 Addendum C, where SEER = SEER2 / 0.95 if ducted and SEER = SEER2 if ductless.
[301] If HSPF2 provided, converted to HSPF using ANSI/RESNET/ICC 301-2022 Addendum C, where HSPF = HSPF2 / 0.85 if ducted and HSPF = HSPF2 / 0.90 if ductless.
[302] If CoolingDetailedPerformanceData is provided, see Detailed Cooling Performance Data.
[303] If HeatingDetailedPerformanceData is provided, see Detailed Heating Performance Data.
[304] If neither extension/HeatingCapacityRetention nor HeatingCapacity17F nor HeatingDetailedPerformanceData provided, heating capacity retention defaults to 0.0461 * HSPF + 0.1594 (at 5F).
[305] The extension/HeatingCapacityRetention input is a more flexible alternative to HeatingCapacity17F, as it can apply to autosized systems and allows the heating capacity retention to be defined at a user-specified temperature (instead of 17F). Either input approach can be used, but not both.
[306] FanPowerWattsPerCFM defaults to 0.07 W/cfm for ductless systems and 0.18 W/cfm for ducted systems.
[307] 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 for more information.
[308] 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 for more information.
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
No
autosized [309]
Heating output capacity (excluding any backup heating)
HeatingCapacity17F
double
Btu/hr
>= 0, <= HeatingCapacity
No
Heating output capacity at 17F, if available
CoolingCapacity
double
Btu/hr
>= 0
No
autosized [310]
Cooling output capacity
CompressorLockoutTemperature
double
F
No
See [311]
Minimum outdoor temperature for compressor operation
CoolingSensibleHeatFraction
double
frac
> 0.5, <= 1
No
0.65
Sensible heat fraction
BackupType
string
See [312]
No
<none>
Type of backup heating
FractionHeatLoadServed
double
frac
>= 0, <= 1 [313]
Yes
Fraction of heating load served
FractionCoolLoadServed
double
frac
>= 0, <= 1 [314]
Yes
Fraction of cooling load served
AnnualCoolingEfficiency[Units="EER" or Units="CEER"]/Value
double
Btu/Wh
> 0
Yes
Rated cooling efficiency
AnnualHeatingEfficiency[Units="COP"]/Value
double
W/W
> 0
Yes
Rated heating efficiency
extension/HeatingCapacityRetention[Fraction | Temperature]
double
frac | F
>= 0, < 1 | <= 17
No
0.425 | 5
Heating output capacity retention at cold temperature [315]
extension/CrankcaseHeaterPowerWatts
double
W
>= 0
No
0.0
Crankcase heater power
extension/CoolingAutosizingFactor
double
frac
> 0
No
1.0
Cooling autosizing scaling factor
extension/HeatingAutosizingFactor
double
frac
> 0
No
1.0
Heating autosizing scaling factor
[309] Heating capacity autosized per ACCA Manual J/S based on heating design load (unless a different HeatPumpSizingMethodology was selected in HPXML HVAC Sizing Control).
[310] Cooling capacity autosized per ACCA Manual J/S based on cooling design load (unless a different HeatPumpSizingMethodology was selected in HPXML HVAC Sizing Control).
[311] If neither CompressorLockoutTemperature nor BackupHeatingSwitchoverTemperature provided, CompressorLockoutTemperature defaults to 25F if fossil fuel backup otherwise 0F.
[312] BackupType choices are “integrated” or “separate”. Heat pump backup will only operate during colder temperatures when the heat pump runs out of heating capacity or is disabled due to a switchover/lockout temperature. Use “integrated” if the heat pump’s distribution system and blower fan power applies to the backup heating (e.g., built-in electric strip heat or an integrated backup furnace, i.e., a dual-fuel heat pump). Use “separate” if the backup system has its own distribution system (e.g., electric baseboard or a boiler). Additional backup inputs are described in Backup.
[313] The sum of all
FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.[314] The sum of all
FractionCoolLoadServed
(across all HVAC systems) must be less than or equal to 1.[315] The extension/HeatingCapacityRetention input is a more flexible alternative to HeatingCapacity17F, as it can apply to autosized systems and allows the heating capacity retention to be defined at a user-specified temperature (instead of 17F). Either input approach can be used, but not both.
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
No
autosized [316]
Heating output capacity (excluding any backup heating)
HeatingCapacity17F
double
Btu/hr
>= 0, <= HeatingCapacity
No
Heating output capacity at 17F, if available
CoolingCapacity
double
Btu/hr
>= 0
No
autosized [317]
Cooling output capacity
CompressorLockoutTemperature
double
F
No
See [318]
Minimum outdoor temperature for compressor operation
CoolingSensibleHeatFraction
double
frac
> 0.5, <= 1
No
0.65
Sensible heat fraction
BackupType
string
See [319]
No
<none>
Type of backup heating
FractionHeatLoadServed
double
frac
>= 0, <= 1 [320]
Yes
Fraction of heating load served
FractionCoolLoadServed
double
frac
>= 0, <= 1 [321]
Yes
Fraction of cooling load served
AnnualCoolingEfficiency[Units="EER" or Units="CEER"]/Value
double
Btu/Wh
> 0
Yes
Rated cooling efficiency
AnnualHeatingEfficiency[Units="COP"]/Value
double
W/W
> 0
Yes
Rated heating efficiency
extension/HeatingCapacityRetention[Fraction | Temperature]
double
frac | F
>= 0, < 1 | <= 17
No
0.425 | 5
Heating output capacity retention at cold temperature [322]
extension/CrankcaseHeaterPowerWatts
double
W
>= 0
No
0.0
Crankcase heater power
extension/CoolingAutosizingFactor
double
frac
> 0
No
1.0
Cooling autosizing scaling factor
extension/HeatingAutosizingFactor
double
frac
> 0
No
1.0
Heating autosizing scaling factor
[316] Heating capacity autosized per ACCA Manual J/S based on heating design load (unless a different HeatPumpSizingMethodology was selected in HPXML HVAC Sizing Control).
[317] Cooling capacity autosized per ACCA Manual J/S based on cooling design load (unless a different HeatPumpSizingMethodology was selected in HPXML HVAC Sizing Control).
[318] If neither CompressorLockoutTemperature nor BackupHeatingSwitchoverTemperature provided, CompressorLockoutTemperature defaults to 25F if fossil fuel backup otherwise 0F.
[319] BackupType choices are “integrated” or “separate”. Heat pump backup will only operate during colder temperatures when the heat pump runs out of heating capacity or is disabled due to a switchover/lockout temperature. Use “integrated” if the heat pump’s distribution system and blower fan power applies to the backup heating (e.g., built-in electric strip heat or an integrated backup furnace, i.e., a dual-fuel heat pump). Use “separate” if the backup system has its own distribution system (e.g., electric baseboard or a boiler). Additional backup inputs are described in Backup.
[320] The sum of all
FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.[321] The sum of all
FractionCoolLoadServed
(across all HVAC systems) must be less than or equal to 1.[322] The extension/HeatingCapacityRetention input is a more flexible alternative to HeatingCapacity17F, as it can apply to autosized systems and allows the heating capacity retention to be defined at a user-specified temperature (instead of 17F). Either input approach can be used, but not both.
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
UnitLocation
string
See [323]
No
See [324]
Location of air handler
DistributionSystem
idref
See [325]
Yes
ID of attached distribution system
IsSharedSystem
boolean
No
false
Whether it has a shared hydronic circulation loop [326]
HeatPumpType
string
ground-to-air
Yes
Type of heat pump
HeatPumpFuel
string
electricity
Yes
Fuel type
HeatingCapacity
double
Btu/hr
>= 0
No
autosized [327]
Heating output capacity (excluding any backup heating)
CoolingCapacity
double
Btu/hr
>= 0
No
autosized [328]
Cooling output capacity
CoolingSensibleHeatFraction
double
frac
> 0.5, <= 1
No
0.73
Sensible heat fraction
BackupType
string
See [329]
No
<none>
Type of backup heating
FractionHeatLoadServed
double
frac
>= 0, <= 1 [330]
Yes
Fraction of heating load served
FractionCoolLoadServed
double
frac
>= 0, <= 1 [331]
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 [332]
Number of dwelling units served
AttachedToGeothermalLoop
idref
See [333]
No [334]
ID of attached geothermal loop
extension/PumpPowerWattsPerTon
double
W/ton
>= 0
No
See [335]
Pump power [336]
extension/SharedLoopWatts
double
W
>= 0
See [337]
Shared pump power [338]
extension/FanPowerWattsPerCFM
double
W/cfm
>= 0
No
See [339]
Blower fan efficiency at maximum fan speed
extension/AirflowDefectRatio
double
frac
>= -0.9, <= 9
No
0.0
Deviation between design/installed airflows [340]
extension/ChargeDefectRatio
double
frac
>= -0.9, <= 9
No
0.0
Deviation between design/installed refrigerant charges [341]
extension/CoolingAutosizingFactor
double
frac
> 0
No
1.0
Cooling autosizing scaling factor
extension/HeatingAutosizingFactor
double
frac
> 0
No
1.0
Heating autosizing scaling factor
[323] UnitLocation choices are “conditioned space”, “basement - unconditioned”, “basement - conditioned”, “attic - unvented”, “attic - vented”, “garage”, “crawlspace - unvented”, “crawlspace - vented”, “crawlspace - conditioned”, “other exterior”, “other housing unit”, “other heated space”, “other multifamily buffer space”, “other non-freezing space”, “roof deck”, “manufactured home belly”, or “unconditioned space”.
[324] If UnitLocation not provided, defaults based on the distribution system:
- Air: supply duct location with the largest area, otherwise “conditioned space”
- DSE: “conditioned space” if
FractionHeatLoadServed
/FractionCoolLoadServed
are 1, otherwise “unconditioned space”[325] HVACDistribution type must be Air Distribution (type: “regular velocity”) or Distribution System Efficiency (DSE).
[326] IsSharedSystem should be true if the SFA/MF building has multiple ground source heat pumps connected to a shared hydronic circulation loop.
[327] Heating capacity autosized per ACCA Manual J/S based on heating design load.
[328] Cooling capacity autosized per ACCA Manual J/S based on cooling design load.
[329] BackupType choices are “integrated” or “separate”. Heat pump backup will only operate during colder temperatures when the heat pump runs out of heating capacity or is disabled due to a switchover/lockout temperature. Use “integrated” if the heat pump’s distribution system and blower fan power applies to the backup heating (e.g., built-in electric strip heat or an integrated backup furnace, i.e., a dual-fuel heat pump). Use “separate” if the backup system has its own distribution system (e.g., electric baseboard or a boiler). Additional backup inputs are described in Backup.
[330] The sum of all
FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.[331] The sum of all
FractionCoolLoadServed
(across all HVAC systems) must be less than or equal to 1.[332] NumberofUnitsServed only required if IsSharedSystem is true, in which case it must be > 1.
[333] AttachedToGeothermalLoop must reference a
GeothermalLoop
.[334] If AttachedToGeothermalLoop not provided, the ground-to-air heat pump will be automatically attached to a geothermal loop that is entirely defaulted.
[335] If PumpPowerWattsPerTon not provided, defaults to 30 W/ton per ANSI/RESNET/ICC 301-2019 for a closed loop system.
[336] 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.
[337] SharedLoopWatts only required if IsSharedSystem is true.
[338] Shared loop pump power attributed to the dwelling unit is calculated as SharedLoopWatts / NumberofUnitsServed.
[339] If FanPowerWattsPerCFM not provided, defaulted to 0.5 W/cfm if COP <= 8.75/3.2, else 0.375 W/cfm.
[340] AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect. See ANSI/RESNET/ACCA 310-2020 for more information.
[341] 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 for more information.
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
UnitLocation
string
See [342]
No
See [343]
Location of air handler
DistributionSystem
idref
See [344]
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
No
autosized [345]
Heating output capacity
CoolingCapacity
double
Btu/hr
> 0
See [346]
Cooling output capacity
BackupType
string
See [347]
No
<none>
Type of backup heating
AnnualCoolingEfficiency[Units="EER"]/Value
double
Btu/Wh
> 0
See [348]
Rated cooling efficiency
AnnualHeatingEfficiency[Units="COP"]/Value
double
W/W
> 0
See [349]
Rated heating efficiency
extension/CoolingAutosizingFactor
double
frac
> 0
No
1.0
Cooling autosizing scaling factor
extension/HeatingAutosizingFactor
double
frac
> 0
No
1.0
Heating autosizing scaling factor
[342] UnitLocation choices are “conditioned space”, “basement - unconditioned”, “basement - conditioned”, “attic - unvented”, “attic - vented”, “garage”, “crawlspace - unvented”, “crawlspace - vented”, “crawlspace - conditioned”, “other exterior”, “other housing unit”, “other heated space”, “other multifamily buffer space”, “other non-freezing space”, “roof deck”, “manufactured home belly”, or “unconditioned space”.
[343] If UnitLocation not provided, defaults based on the distribution system:
- Air: supply duct location with the largest area, otherwise “conditioned space”
- DSE: “conditioned space” if
FractionHeatLoadServed
/FractionCoolLoadServed
are 1, otherwise “unconditioned space”[344] HVACDistribution type must be Air Distribution (type: “regular velocity”) or Distribution System Efficiency (DSE).
[345] Heating capacity autosized per ACCA Manual J/S based on heating design load.
[346] CoolingCapacity required if there is a shared chiller or cooling tower with water loop distribution.
[347] BackupType choices are “integrated” or “separate”. Heat pump backup will only operate during colder temperatures when the heat pump runs out of heating capacity or is disabled due to a switchover/lockout temperature. Use “integrated” if the heat pump’s distribution system and blower fan power applies to the backup heating (e.g., built-in electric strip heat or an integrated backup furnace, i.e., a dual-fuel heat pump). Use “separate” if the backup system has its own distribution system (e.g., electric baseboard or a boiler). Additional backup inputs are described in Backup.
[348] AnnualCoolingEfficiency required if there is a shared chiller or cooling tower with water loop distribution.
[349] 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 (Shared)) and/or one shared cooling system (i.e., Chiller (Shared) or Cooling Tower (Shared)) specified with water loop distribution.
Backup
If a backup type (“integrated” or “separate”) is provided, additional information is entered in HeatPump
.
Element
Type
Units
Constraints
Required
Default
Notes
BackupHeatingSwitchoverTemperature
orCompressorLockoutTemperature
double
F
No
See [350]
Minimum outdoor temperature for compressor operation
BackupHeatingSwitchoverTemperature
orBackupHeatingLockoutTemperature
double
F
See [351]
No
See [352]
Maximum outdoor temperature for backup operation
[350] If neither BackupHeatingSwitchoverTemperature nor CompressorLockoutTemperature provided, CompressorLockoutTemperature defaults as described above for individual heat pump types.
[351] If both BackupHeatingLockoutTemperature and CompressorLockoutTemperature provided, BackupHeatingLockoutTemperature must be greater than or equal to CompressorLockoutTemperature.
[352] If neither BackupHeatingSwitchoverTemperature nor BackupHeatingLockoutTemperature provided, BackupHeatingLockoutTemperature defaults to 40F for electric backup and 50F for fossil fuel backup.
Note
Provide
BackupHeatingSwitchoverTemperature
for a situation where there is a discrete outdoor temperature below which the heat pump stops operating and above which the backup heating system stops operating.Alternatively, provide A)
CompressorLockoutTemperature
to specify the outdoor temperature below which the heat pump stops operating and/or B)BackupHeatingLockoutTemperature
to specify the outdoor temperature above which the heat pump backup system stops operating. If both are provided, the compressor and backup system can both operate between the two temperatures (e.g., simultaneous operation or cycling). If both are provided using the same temperature, it is equivalent to usingBackupHeatingSwitchoverTemperature
.
If a backup type of “integrated” is provided, additional information is entered in HeatPump
.
Element
Type
Units
Constraints
Required
Default
Notes
BackupSystemFuel
string
See [353]
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
No
autosized [354]
Integrated backup heating output capacity
extension/BackupHeatingAutosizingFactor
double
frac
> 0
No
1.0
Backup Heating autosizing scaling factor
[353] BackupSystemFuel choices are “electricity”, “natural gas”, “fuel oil”, “fuel oil 1”, “fuel oil 2”, “fuel oil 4”, “fuel oil 5/6”, “diesel”, “propane”, “kerosene”, “coal”, “coke”, “bituminous coal”, “wood”, or “wood pellets”.
[354] Heating capacity autosized per ACCA Manual J/S based on heating design load. (The autosized capacity is not affected by the HeatPumpSizingMethodology selected in HPXML HVAC Sizing Control.)
If a backup type of “separate” is provided, additional information is entered in HeatPump
.
Element
Type
Units
Constraints
Required
Default
Notes
BackupSystem
idref
See [355]
Yes
ID of separate backup heating system
[355] BackupSystem must reference a
HeatingSystem
.Note
Due to how the separate backup heating system is modeled in EnergyPlus, there are a few restrictions:
The conditioned space cannot be partially heated (i.e., the sum of all
FractionHeatLoadServed
must be 1).There cannot be multiple backup heating systems.
HPXML HVAC Detailed Perf. Data
Some air-source HVAC system types allow detailed heating/cooling performance data to be provided using the CoolingDetailedPerformanceData
and HeatingDetailedPerformanceData
elements, as described above.
One source of detailed performance data is NEEP’s Cold Climate Air Source Heat Pump List.
Currently detailed performance data can only be provided for variable-speed HVAC systems.
Detailed Cooling Performance Data
For air-source HVAC systems with detailed cooling performance data, two or more pairs of minimum/maximum capacity data are entered in CoolingDetailedPerformanceData/PerformanceDataPoint
.
Element
Type
Units
Constraints
Required
Default
Notes
OutdoorTemperature
double
F
See [356]
Yes
Outdoor drybulb temperature
Capacity
orCapacityFractionOfNominal
double
Btu/hr or frac
>= 0
Yes [357]
Cooling capacity or capacity fraction at the specified outdoor temperature
CapacityDescription
string
See [358]
Yes
Whether the datapoint corresponds to minimum or maximum capacity
Efficiency[Units="COP"]/Value
double
W/W
> 0
Yes
Cooling efficiency at the specified outdoor temperature
[356] One of the minimum/maximum datapoint pairs must occur at the 95F rated outdoor temperature condition. The other datapoint pairs can be at any temperature.
[357] If Capacity is provided, the nominal capacity (
CoolingCapacity
) must also be set in the parent object.[358] CapacityDescription choices are “minimum” and “maximum”.
In addition, the CompressorType
must be set to “variable speed” in the parent object.
Note that when detailed cooling performance data is provided, some other inputs (like SEER) are ignored.
Detailed Heating Performance Data
For air-source HVAC systems with detailed heating performance data, two or more pairs of minimum/maximum capacity data are entered in HeatingDetailedPerformanceData/PerformanceDataPoint
.
Element
Type
Units
Constraints
Required
Default
Notes
OutdoorTemperature
double
F
See [359]
Yes
Outdoor drybulb temperature
Capacity
orCapacityFractionOfNominal
double
Btu/hr or frac
>= 0
Yes [360]
Heating capacity or capacity fraction at the specified outdoor temperature
CapacityDescription
string
See [361]
Yes
Whether the datapoint corresponds to minimum or maximum capacity
Efficiency[Units="COP"]/Value
double
W/W
> 0
Yes
Heating efficiency at the specified outdoor temperature
[359] One of the minimum/maximum datapoint pairs must occur at the 47F rated outdoor temperature condition. The other datapoint pairs can be at any temperature.
[360] If Capacity is provided, the nominal capacity (
HeatingCapacity
) must also be set in the parent object.[361] CapacityDescription choices are “minimum” and “maximum”.
In addition, the CompressorType
must be set to “variable speed” in the parent object.
Note that when detailed cooling performance data is provided, some other inputs (like HSPF and HeatingCapacityRetention) are ignored.
HPXML Geothermal Loops
Each geothermal loop is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/GeothermalLoop
.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
LoopConfiguration
string
vertical
Yes
Geothermal loop configuration
LoopFlow
double
gal/min
> 0
No
See [362]
Water flow rate through the geothermal loop
BoreholesOrTrenches/Count
integer
>= 1, <= 10
No [363]
See [364]
Number of boreholes
BoreholesOrTrenches/Length
double
ft
>= 79, <= 500 [365]
No
See [366]
Length (i.e., average depth) of each borehole
BoreholesOrTrenches/Spacing
double
ft
> 0
No
16.4
Distance between boreholes
BoreholesOrTrenches/Diameter
double
in
> 0
No
5.0
Borehole diameter
Grout/Type
orGrout/Conductivity
string or double
Btu/hr-ft-F
See [367] or > 0
No
standard
Grout type or conductivity [368]
Pipe/Type
orPipe/Conductivity
string or double
Btu/hr-ft-F
See [369] or > 0
No
standard
Pipe type or conductivity [370]
Pipe/Diameter
double
in
See [371]
No
1.25
Pipe diameter
Pipe/ShankSpacing
double
in
> 0
No
See [372]
Center-to-center distance between two branches of a vertical U-tube
extension/BorefieldConfiguration
string
See [373]
No
Rectangle
Configuration of boreholes
[362] LoopFlow autosized by calculating 3 times the maximum of the ground source heat pump’s heating/cooling capacity in tons, with a minimum of 3 gal/min.
[363] If extension/BorefieldConfiguration provided, and it is not Rectangle, a valid BoreholesOrTrenches/Count must also be provided:
- Rectangle: 1, 2, 3, 4, 5, 6, 7, 8, 9, or 10
- Open Rectangle: 8 or 10
- C: 7 or 9
- L: 4, 5, 6, 7, 8, 9, or 10
- U: 7, 9, or 10
- Lopsided U: 6, 7, 8, 9, or 10
[364] BoreholesOrTrenches/Count calculated as the required total length of the ground heat exchanger (calculated during sizing) divided by BoreholesOrTrenches/Length if BoreholesOrTrenches/Length is provided, otherwise autosized by assuming 1 for every ton of ground source heat pump cooling capacity (max of 10).
[365] 79 ft is the minimum depth in the g-function library. 500 ft is the maximum realistic depth to be used in residential applications.
[366] BoreholesOrTrenches/Length calculated as the required total length of the ground heat exchanger (calculated during sizing) divided by the total number of boreholes.
[367] Grout/Type choices are “standard” or “thermally enhanced”.
[368] If Grout/Conductivity not provided, defaults based on Grout/Type:
- standard: 0.75 Btu/hr-ft-F
- thermally enhanced: 1.2 Btu/hr-ft-F
[369] Pipe/Type choices are “standard” or “thermally enhanced”.
[370] If Pipe/Conductivity not provided, defaults based on Pipe/Type:
- standard: 0.23 Btu/hr-ft-F
- thermally enhanced: 0.40 Btu/hr-ft-F
[371] Pipe diameter must be either 0.75, 1.0, or 1.25.
[372] ShankSpacing defaults to sum of U-tube spacing (assumed to be 0.9661 in) and pipe outer diameter, where pipe outer diameter is assumed to be:
- 0.75 in pipe: 1.050 in
- 1.0 in pipe: 1.315 in
- 1.25 in pipe: 1.660 in
[373] extension/BorefieldConfiguration choices are “Rectangle”, “Open Rectangle”, “C”, “L”, “U”, or “Lopsided U”.
Note
For a given combination of extension/BorefieldConfiguration
, BoreholesOrTrenches/Count
, BoreholesOrTrenches/Spacing
, BoreholesOrTrenches/Length
, and BoreholesOrTrenches/Diameter
g-function values are determined using the G-Function Library (from the Geothermal Data Repository).
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
HeatingSeason
element
No
See [374]
Heating season
CoolingSeason
element
No
See [375]
Cooling season
extension/CeilingFanSetpointTempCoolingSeasonOffset
double
F
>= 0
No
0
Cooling setpoint temperature offset [376]
[374] If HeatingSeason not provided, defaults to year-round.
[375] If CoolingSeason not provided, defaults to year-round.
[376] CeilingFanSetpointTempCoolingSeasonOffset should only be used if there are sufficient ceiling fans present to warrant a reduced cooling setpoint.
HPXML HVAC Seasons
If a heating and/or cooling season is defined, additional information is entered in HVACControl/HeatingSeason
and/or HVACControl/CoolingSeason
.
Element
Type
Units
Constraints
Required
Default
Description
BeginMonth
integer
>= 1, <= 12
Yes
Begin month
BeginDayOfMonth
integer
>= 1, <= 31
Yes
Begin day
EndMonth
integer
>= 1, <= 12
Yes
End month
EndDayOfMonth
integer
>= 1, <= 31
Yes
End day
HPXML HVAC Setpoints
Thermostat setpoints are additionally entered using either simple inputs, hourly inputs, or Detailed Schedule Inputs.
Simple Inputs
To define simple thermostat setpoints, additional information is entered in HVACControl
.
Element
Type
Units
Constraints
Required
Default
Notes
SetpointTempHeatingSeason
double
F
No [377]
68
Heating setpoint temperature
SetpointTempCoolingSeason
double
F
No [378]
78
Cooling setpoint temperature
[377] SetpointTempHeatingSeason only used if there is heating equipment.
[378] SetpointTempCoolingSeason only used if there is cooling equipment.
If there is a heating temperature setback, additional information is entered in HVACControl
.
Element
Type
Units
Constraints
Required
Default
Notes
SetbackTempHeatingSeason
double
F
Yes
Heating setback temperature
TotalSetbackHoursperWeekHeating
integer
hrs/week
> 0
Yes
Hours/week of heating temperature setback [379]
extension/SetbackStartHourHeating
integer
>= 0, <= 23
No
23 (11pm)
Daily setback start hour
[379] TotalSetbackHoursperWeekHeating is converted to hrs/day and modeled as a temperature setback every day starting at SetbackStartHourHeating.
If there is a cooling temperature setup, additional information is entered in HVACControl
.
Element
Type
Units
Constraints
Required
Default
Notes
SetupTempCoolingSeason
double
F
Yes
Cooling setup temperature
TotalSetupHoursperWeekCooling
integer
hrs/week
> 0
Yes
Hours/week of cooling temperature setup [380]
extension/SetupStartHourCooling
integer
>= 0, <= 23
No
9 (9am)
Daily setup start hour
[380] TotalSetupHoursperWeekCooling is converted to hrs/day and modeled as a temperature setup every day starting at SetupStartHourCooling.
Hourly Inputs
To define hourly thermostat setpoints, additional information is entered in HVACControl
.
Element
Type
Units
Constraints
Required
Default
Notes
extension/WeekdaySetpointTempsHeatingSeason
array
F
No [381]
24 comma-separated weekday heating setpoints
extension/WeekendSetpointTempsHeatingSeason
array
F
No
24 comma-separated weekend heating setpoints
extension/WeekdaySetpointTempsCoolingSeason
array
F
No [382]
24 comma-separated weekday cooling setpoints
extension/WeekendSetpointTempsCoolingSeason
array
F
No
24 comma-separated weekend cooling setpoints
[381] WeekdaySetpointTempsHeatingSeason and WeekendSetpointTempsHeatingSeason only used if there is heating equipment.
[382] WeekdaySetpointTempsCoolingSeason and WeekendSetpointTempsCoolingSeason only used if there is cooling equipment.
HPXML HVAC Distribution
The following distribution system types can be modeled:
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 [383]
Yes
Type of air distribution
DistributionSystemType/AirDistribution/DuctLeakageMeasurement[DuctType="supply"]
element
See [384]
Supply duct leakage value
DistributionSystemType/AirDistribution/DuctLeakageMeasurement[DuctType="return"]
element
See [385]
Return duct leakage value
DistributionSystemType/AirDistribution/Ducts
element
No
Supply/return ducts; multiple are allowed [386]
DistributionSystemType/AirDistribution/NumberofReturnRegisters
integer
>= 0
No
See [387]
Number of return registers
ConditionedFloorAreaServed
double
ft2
> 0
See [388]
Conditioned floor area served
[383] 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.).
[384] Supply duct leakage required if AirDistributionType is “regular velocity” or “gravity” and optional if AirDistributionType is “fan coil”.
[385] Return duct leakage required if AirDistributionType is “regular velocity” or “gravity” and optional if AirDistributionType is “fan coil”.
[386] Provide a Ducts element for each supply duct and each return duct.
[387] If NumberofReturnRegisters not provided and return ducts are present, defaults to one return register per conditioned floor per ASHRAE Standard 152, rounded up to the nearest integer if needed.
[388] ConditionedFloorAreaServed required only when duct surface area is defaulted (i.e.,
AirDistribution/Ducts
are present withoutDuctSurfaceArea
child elements).
Additional information is entered in each DuctLeakageMeasurement
.
Element
Type
Units
Constraints
Required
Default
Notes
DuctLeakage/Units
string
See [389]
Yes
Duct leakage units
DuctLeakage/Value
double
>= 0 [390]
Yes
Duct leakage value [391]
DuctLeakage/TotalOrToOutside
string
See [392]
Yes
Type of duct leakage (outside conditioned space vs total)
[389] Units choices are “CFM25”, “CFM50”, or “Percent”.
[390] Value also must be < 1 if Units is Percent.
[391] If the HVAC system has no return ducts (e.g., a ducted evaporative cooler), use zero for the Value.
[392] TotalOrToOutside only choice is “to outside”.
Additional information is entered in each Ducts
.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
DuctInsulationRValue
and/orDuctEffectiveRValue
double
F-ft2-hr/Btu
>= 0
Yes
Duct R-value [393]
DuctBuriedInsulationLevel
string
See [394]
No
not buried
Duct buried insulation level [395]
DuctLocation
string
See [396]
No
See [397]
Duct location
FractionDuctArea
and/orDuctSurfaceArea
double
frac or ft2
0-1 [398] or >= 0
See [399]
See [400]
Duct fraction/surface area in location
extension/DuctSurfaceAreaMultiplier
double
>= 0
No
1.0
Duct surface area multiplier
[393] It is recommended to provide DuctInsulationRValue and not DuctEffectiveRValue. DuctInsulationRValue should not include the exterior air film (i.e., use 0 for an uninsulated duct). For ducts buried in insulation (using DuctBuriedInsulationLevel), DuctInsulationRValue should only represent any surrounding insulation duct wrap and not the entire attic insulation R-value. On the other hand, DuctEffectiveRValue should include the exterior air film as well as other effects such as adjustments for insulation wrapped around round ducts, or effective heat transfer for ducts buried in attic insulation. DuctEffectiveRValue is used for the actual model heat transfer, and when not provided is calculated as follows:
- Uninsulated: 1.7
- Supply, Insulated: 2.2438 + 0.5619 * DuctInsulationRValue
- Supply, Partially Buried: 3.46 + 1.05 * DuctInsulationRValue
- Supply, Fully Buried: 7.14 + 1.0 * DuctInsulationRValue
- Supply, Deeply Buried: 14.94 + 0.76 * DuctInsulationRValue
- Return, Insulated: 2.0388 + 0.7053 * DuctInsulationRValue
- Return, Partially Buried: 4.62 + 1.31 * DuctInsulationRValue
- Return, Fully Buried: 8.91 + 1.29 * DuctInsulationRValue
- Return, Deeply Buried: 18.64 + 1.0 * DuctInsulationRValue
The uninsulated effective R-value is from ASHRAE Handbook of Fundamentals. The insulated effective R-values are from True R-Values of Round Residential Ductwork. The buried effective R-values are from Table 13 of Reducing Thermal Losses and Gains With Buried and Encapsulated Ducts., where the average supply and return ducts have diameters of 8-inch and 14-in, respectively.
[394] DuctBuriedInsulationLevel choices are “not buried”, “partially buried”, “fully buried”, or “deeply buried”.
[395] 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.
[396] DuctLocation choices are “conditioned space”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - unvented”, “crawlspace - vented”, “crawlspace - conditioned”, “attic - unvented”, “attic - vented”, “garage”, “outside”, “exterior wall”, “under slab”, “roof deck”, “other housing unit”, “other heated space”, “other multifamily buffer space”, “other non-freezing space”, or “manufactured home belly”. See HPXML Locations for descriptions.
[397] If DuctLocation not provided, defaults to the first present space type: “basement - conditioned”, “basement - unconditioned”, “crawlspace - conditioned”, “crawlspace - vented”, “crawlspace - unvented”, “attic - vented”, “attic - unvented”, “garage”, or “conditioned space”. If NumberofConditionedFloorsAboveGrade > 1, secondary ducts will be located in “conditioned space”.
[398] The sum of all
FractionDuctArea
must each equal to 1, both for the supply side and return side.[399] FractionDuctArea or DuctSurfaceArea are required if DuctLocation is provided. If both are provided, DuctSurfaceArea will be used in the model.
[400] If neither DuctSurfaceArea nor FractionDuctArea provided, duct surface areas will be calculated based on ASHRAE Standard 152:
- Primary supply duct area: 0.27 * F_out * ConditionedFloorAreaServed
- Secondary supply duct area: 0.27 * (1 - F_out) * ConditionedFloorAreaServed
- Primary return duct area: b_r * F_out * ConditionedFloorAreaServed
- Secondary return duct area: b_r * (1 - F_out) * ConditionedFloorAreaServed
where F_out is 1.0 when NumberofConditionedFloorsAboveGrade <= 1 and 0.75 when NumberofConditionedFloorsAboveGrade > 1, and b_r is 0.05 * NumberofReturnRegisters with a maximum value of 0.25.
If FractionDuctArea is provided, each duct surface area will be FractionDuctArea times total duct area, which is calculated using the sum of primary and secondary duct areas from the equations above.
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 [401]
Yes
Type of hydronic distribution system
[401] 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 using, e.g., 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
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
UsedForWholeBuildingVentilation
boolean
true
Yes
Ventilation fan use case [402]
IsSharedSystem
boolean
No
false
Whether it serves multiple dwelling units [403]
FanType
string
exhaust only
Yes
Type of ventilation system
RatedFlowRate
orTestedFlowRate
orCalculatedFlowRate
orDeliveredVentilation
double
cfm
>= 0
No
See [404]
Flow rate
HoursInOperation
double
hrs/day
>= 0, <= 24
See [405]
24
Hours per day of operation
FanPower
double
W
>= 0
No
See [406]
Fan power
[402] All other UsedFor… elements (i.e.,
UsedForLocalVentilation
,UsedForSeasonalCoolingLoadReduction
,UsedForGarageVentilation
) must be omitted or false.[403] Additional inputs for shared systems are described in Shared System.
[404] If flow rate not provided, defaults to the required mechanical ventilation rate per ANSI/RESNET/ICC 301-2022:
Qfan = required mechanical ventilation rate (cfm) = ((Qtot^2 – 4*Qinf_eff^2 + 2*Qinf_eff*Qtot + Qinf_eff^2)^0.5 + Qtot - Qinf_eff) / 2
where
Qtot = total required ventilation rate (cfm) = 0.03 * ConditionedFloorArea + 7.5*(NumberofBedrooms + 1)
Qinf_eff = Qinf * Aext
Qinf = infiltration rate (cfm)
Aext = 1 if single-family detached or TypeOfInfiltrationLeakage is “unit exterior only”, otherwise ratio of SFA/MF exterior envelope surface area to total envelope surface area as described in HPXML Air Infiltration
OpenStudio-HPXML does not currently support defaulting flow rates for multiple mechanical ventilation fans.
[405] HoursInOperation is optional 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 (based on the air handler runtime) to maintain the hourly target ventilation rate.
[406] If FanPower not provided, defaults to 0.35 W/cfm based on ANSI/RESNET/ICC 301-2019.
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
UsedForWholeBuildingVentilation
boolean
true
Yes
Ventilation fan use case [407]
IsSharedSystem
boolean
No
false
Whether it serves multiple dwelling units [408]
FanType
string
supply only
Yes
Type of ventilation system
RatedFlowRate
orTestedFlowRate
orCalculatedFlowRate
orDeliveredVentilation
double
cfm
>= 0
No
See [409]
Flow rate
HoursInOperation
double
hrs/day
>= 0, <= 24
See [410]
24
Hours per day of operation
FanPower
double
W
>= 0
No
See [411]
Fan power
[407] All other UsedFor… elements (i.e.,
UsedForLocalVentilation
,UsedForSeasonalCoolingLoadReduction
,UsedForGarageVentilation
) must be omitted or false.[408] Additional inputs for shared systems are described in Shared System.
[409] If flow rate not provided, defaults to the required mechanical ventilation rate per ANSI/RESNET/ICC 301-2022:
Qfan = required mechanical ventilation rate (cfm) = ((Qtot^2 – 4*Qinf_eff^2 + 2*Qinf_eff*Qtot + Qinf_eff^2)^0.5 + Qtot - Qinf_eff) / 2
where
Qtot = total required ventilation rate (cfm) = 0.03 * ConditionedFloorArea + 7.5*(NumberofBedrooms + 1)
Qinf_eff = Qinf * Aext
Qinf = infiltration rate (cfm)
Aext = 1 if single-family detached or TypeOfInfiltrationLeakage is “unit exterior only”, otherwise ratio of SFA/MF exterior envelope surface area to total envelope surface area as described in HPXML Air Infiltration
OpenStudio-HPXML does not currently support defaulting flow rates for multiple mechanical ventilation fans.
[410] HoursInOperation is optional 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 (based on the air handler runtime) to maintain the hourly target ventilation rate.
[411] If FanPower not provided, defaults to 0.35 W/cfm based on ANSI/RESNET/ICC 301-2019.
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
UsedForWholeBuildingVentilation
boolean
true
Yes
Ventilation fan use case [412]
IsSharedSystem
boolean
No
false
Whether it serves multiple dwelling units [413]
FanType
string
balanced
Yes
Type of ventilation system
RatedFlowRate
orTestedFlowRate
orCalculatedFlowRate
orDeliveredVentilation
double
cfm
>= 0
No
See [414]
Flow rate
HoursInOperation
double
hrs/day
>= 0, <= 24
No
24
Hours per day of operation
FanPower
double
W
>= 0
No
See [415]
Fan power
[412] All other UsedFor… elements (i.e.,
UsedForLocalVentilation
,UsedForSeasonalCoolingLoadReduction
,UsedForGarageVentilation
) must be omitted or false.[413] Additional inputs for shared systems are described in Shared System.
[414] If flow rate not provided, defaults to the required mechanical ventilation rate per ANSI/RESNET/ICC 301-2022:
Qfan = required mechanical ventilation rate (cfm) = Qtot - Qinf_eff
where
Qtot = total required ventilation rate (cfm) = 0.03 * ConditionedFloorArea + 7.5*(NumberofBedrooms + 1)
Qinf_eff = Qinf * Aext
Qinf = infiltration rate (cfm)
Aext = 1 if single-family detached or TypeOfInfiltrationLeakage is “unit exterior only”, otherwise ratio of SFA/MF exterior envelope surface area to total envelope surface area as described in HPXML Air Infiltration
OpenStudio-HPXML does not currently support defaulting flow rates for multiple mechanical ventilation fans.
[415] If FanPower not provided, defaults to 0.7 W/cfm based on ANSI/RESNET/ICC 301-2019.
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
UsedForWholeBuildingVentilation
boolean
true
Yes
Ventilation fan use case [416]
IsSharedSystem
boolean
No
false
Whether it serves multiple dwelling units [417]
FanType
string
heat recovery ventilator
Yes
Type of ventilation system
RatedFlowRate
orTestedFlowRate
orCalculatedFlowRate
orDeliveredVentilation
double
cfm
>= 0
No
See [418]
Flow rate
HoursInOperation
double
hrs/day
>= 0, <= 24
No
24
Hours per day of operation
AdjustedSensibleRecoveryEfficiency
orSensibleRecoveryEfficiency
double
frac
> 0, <= 1
Yes
(Adjusted) Sensible recovery efficiency [419]
FanPower
double
W
>= 0
No
See [420]
Fan power
[416] All other UsedFor… elements (i.e.,
UsedForLocalVentilation
,UsedForSeasonalCoolingLoadReduction
,UsedForGarageVentilation
) must be omitted or false.[417] Additional inputs for shared systems are described in Shared System.
[418] If flow rate not provided, defaults to the required mechanical ventilation rate per ANSI/RESNET/ICC 301-2022:
Qfan = required mechanical ventilation rate (cfm) = Qtot - Qinf_eff
where
Qtot = total required ventilation rate (cfm) = 0.03 * ConditionedFloorArea + 7.5*(NumberofBedrooms + 1)
Qinf_eff = Qinf * Aext
Qinf = infiltration rate (cfm)
Aext = 1 if single-family detached or TypeOfInfiltrationLeakage is “unit exterior only”, otherwise ratio of SFA/MF exterior envelope surface area to total envelope surface area as described in HPXML Air Infiltration
OpenStudio-HPXML does not currently support defaulting flow rates for multiple mechanical ventilation fans.
[419] Providing AdjustedSensibleRecoveryEfficiency (ASRE) is preferable to SensibleRecoveryEfficiency (SRE).
[420] If FanPower not provided, defaults to 1.0 W/cfm based on ANSI/RESNET/ICC 301-2019.
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
UsedForWholeBuildingVentilation
boolean
true
Yes
Ventilation fan use case [421]
IsSharedSystem
boolean
No
false
Whether it serves multiple dwelling units [422]
FanType
string
energy recovery ventilator
Yes
Type of ventilation system
RatedFlowRate
orTestedFlowRate
orCalculatedFlowRate
orDeliveredVentilation
double
cfm
>= 0
No
See [423]
Flow rate
HoursInOperation
double
hrs/day
>= 0, <= 24
No
24
Hours per day of operation
AdjustedTotalRecoveryEfficiency
orTotalRecoveryEfficiency
double
frac
> 0, <= 1
Yes
(Adjusted) Total recovery efficiency [424]
AdjustedSensibleRecoveryEfficiency
orSensibleRecoveryEfficiency
double
frac
> 0, <= 1
Yes
(Adjusted) Sensible recovery efficiency [425]
FanPower
double
W
>= 0
No
See [426]
Fan power
[421] All other UsedFor… elements (i.e.,
UsedForLocalVentilation
,UsedForSeasonalCoolingLoadReduction
,UsedForGarageVentilation
) must be omitted or false.[422] Additional inputs for shared systems are described in Shared System.
[423] If flow rate not provided, defaults to the required mechanical ventilation rate per ANSI/RESNET/ICC 301-2022:
Qfan = required mechanical ventilation rate (cfm) = Qtot - Qinf_eff
where
Qtot = total required ventilation rate (cfm) = 0.03 * ConditionedFloorArea + 7.5*(NumberofBedrooms + 1)
Qinf_eff = Qinf * Aext
Qinf = infiltration rate (cfm)
Aext = 1 if single-family detached or TypeOfInfiltrationLeakage is “unit exterior only”, otherwise ratio of SFA/MF exterior envelope surface area to total envelope surface area as described in HPXML Air Infiltration
OpenStudio-HPXML does not currently support defaulting flow rates for multiple mechanical ventilation fans.
[424] Providing AdjustedTotalRecoveryEfficiency (ATRE) is preferable to TotalRecoveryEfficiency (TRE).
[425] Providing AdjustedSensibleRecoveryEfficiency (ASRE) is preferable to SensibleRecoveryEfficiency (SRE).
[426] If FanPower not provided, defaults to 1.0 W/cfm based on ANSI/RESNET/ICC 301-2019.
Central Fan Integrated Supply (CFIS)
Each central fan integrated supply (CFIS) system is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan
.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
UsedForWholeBuildingVentilation
boolean
true
Yes
Ventilation fan use case [427]
FanType
string
central fan integrated supply
Yes
Type of ventilation system
CFISControls/AdditionalRuntimeOperatingMode
string
See [428]
No
air handler fan
How additional ventilation is provided (beyond HVAC system operation)
CFISControls/SupplementalFan
idref
See [429]
See [430]
The supplemental fan providing additional ventilation
RatedFlowRate
orTestedFlowRate
orCalculatedFlowRate
orDeliveredVentilation
double
cfm
>= 0
No
See [431]
Flow rate [432]
HoursInOperation
double
hrs/day
>= 0, <= 24
false
8
Hours per day of operation [433]
FanPower
double
W
>= 0
No
See [434]
Fan power
AttachedToHVACDistributionSystem
idref
See [435]
Yes
ID of attached distribution system
extension/VentilationOnlyModeAirflowFraction
double
>= 0, <= 1
No
1.0
Blower airflow rate fraction during ventilation only mode [436]
[427] All other UsedFor… elements (i.e.,
UsedForLocalVentilation
,UsedForSeasonalCoolingLoadReduction
,UsedForGarageVentilation
) must be omitted or false.[428] AdditionalRuntimeOperatingMode choices are “air handler fan” or “supplemental fan”.
[429] SupplementalFan must reference another
VentilationFan
where UsedForWholeBuildingVentilation=true, IsSharedSystem=false, and FanType=”exhaust only” or “supply only”.[430] SupplementalFan only required if AdditionalRuntimeOperatingMode is “supplemental fan”.
[431] If flow rate not provided, defaults to the required mechanical ventilation rate per ANSI/RESNET/ICC 301-2022:
Qfan = required mechanical ventilation rate (cfm) = ((Qtot^2 – 4*Qinf_eff^2 + 2*Qinf_eff*Qtot + Qinf_eff^2)^0.5 + Qtot - Qinf_eff) / 2
where
Qtot = total required ventilation rate (cfm) = 0.03 * ConditionedFloorArea + 7.5*(NumberofBedrooms + 1)
Qinf_eff = Qinf * Aext
Qinf = infiltration rate (cfm)
Aext = 1 if single-family detached or TypeOfInfiltrationLeakage is “unit exterior only”, otherwise ratio of SFA/MF exterior envelope surface area to total envelope surface area as described in HPXML Air Infiltration
OpenStudio-HPXML does not currently support defaulting flow rates for multiple mechanical ventilation fans.
[432] The flow rate should equal the amount of outdoor air provided to the distribution system, not the total airflow through the distribution system.
[433] The HoursInOperation and the flow rate are combined 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).
[434] If FanPower not provided, defaults to 0.58 W/cfm based on ANSI/RESNET/ICC 301-2022 Addendum C.
[435] HVACDistribution type cannot be Hydronic Distribution.
[436] Blower airflow rate when operating in ventilation only mode (i.e., not heating or cooling mode), as a fraction of the maximum blower airflow rate. This value will depend on whether the blower fan can operate at reduced airflow rates during ventilation only operation. It is used to determine how much conditioned air is recirculated through ducts during ventilation only operation, resulting in additional duct losses. A value of zero will result in no conditioned air recirculation, and thus no additional duct losses.
Note
CFIS systems are automated controllers that use the HVAC system’s air handler fan to draw in outdoor air to meet an hourly ventilation target. CFIS systems are modeled as assuming they A) maximize the use of normal heating/cooling runtime operation to meet the hourly ventilation target, B) block the flow of outdoor air when the hourly ventilation target has been met, and C) provide additional runtime operation (via air handler fan or supplemental fan) to meet the remainder of the hourly ventilation target when space heating/cooling runtime alone is not sufficient.
HPXML Local Ventilation Fans
Each fan that provides local ventilation (e.g., kitchen range fan or bathroom fan) is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan
.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
UsedForLocalVentilation
boolean
true
Yes
Ventilation fan use case [443]
Count
integer
>= 0
No
See [444]
Number of identical fans
RatedFlowRate
orTestedFlowRate
orCalculatedFlowRate
orDeliveredVentilation
double
cfm
>= 0
No
See [445]
Flow rate to outside [446]
HoursInOperation
double
hrs/day
>= 0, <= 24
No
See [447]
Hours per day of operation
FanLocation
string
See [448]
Yes
Location of the fan
FanPower
double
W
>= 0
No
See [449]
Fan power
extension/StartHour
integer
>= 0, <= 23
No
See [450]
Daily start hour of operation
[443] All other UsedFor… elements (i.e.,
UsedForWholeBuildingVentilation
,UsedForSeasonalCoolingLoadReduction
,UsedForGarageVentilation
) must be omitted or false.[444] If Count not provided, defaults to 1 for kitchen fans and NumberofBathrooms for bath fans based on the 2010 BAHSP.
[445] If flow rate not provided, defaults to 100 cfm for kitchen fans and 50 cfm for bath fans based on the 2010 BAHSP.
[446] If the kitchen range fan is a recirculating fan, the flow rate should be described as zero.
[447] If HoursInOperation not provided, defaults to 1 based on the 2010 BAHSP.
[448] FanLocation choices are “kitchen” or “bath”.
[449] If FanPower not provided, defaults to 0.3 W/cfm based on the 2010 BAHSP.
[450] If StartHour not provided, defaults to 18 (6pm) for kitchen fans and 7 (7am) for bath fans based on the 2010 BAHSP.
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 [451]
RatedFlowRate
orTestedFlowRate
orCalculatedFlowRate
orDeliveredVentilation
double
cfm
>= 0
No
2*ConditionedFloorArea
Flow rate
FanPower
double
W
>= 0
No
See [452]
Fan power
[451] All other UsedFor… elements (i.e.,
UsedForWholeBuildingVentilation
,UsedForLocalVentilation
,UsedForGarageVentilation
) must be omitted or false.[452] If FanPower not provided, defaults to 0.1 W/cfm.
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:
If not entered, the simulation will not include water heating.
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 [453]
Yes
Fuel type
WaterHeaterType
string
storage water heater
Yes
Type of water heater
Location
string
See [454]
No
See [455]
Water heater location
IsSharedSystem
boolean
No
false
Whether it serves multiple dwelling units or shared laundry room
TankVolume
double
gal
> 0
No
See [456]
Nominal tank volume
FractionDHWLoadServed
double
frac
>= 0, <= 1 [457]
Yes
Fraction of hot water load served [458]
HeatingCapacity
double
Btu/hr
> 0
No
See [459]
Heating capacity
UniformEnergyFactor
orEnergyFactor
double
frac
< 1
Yes
EnergyGuide label rated efficiency
UsageBin
orFirstHourRating
string or double
str or gal/hr
See [460] or > 0
No
See [461]
EnergyGuide label usage bin/first hour rating
RecoveryEfficiency
double
frac
> 0, <= 1 [462]
No
See [463]
Recovery efficiency
WaterHeaterInsulation/Jacket/JacketRValue
double
F-ft2-hr/Btu
>= 0
No
0
R-value of additional tank insulation wrap
HotWaterTemperature
double
F
> 0
No
125
Water heater setpoint [464]
UsesDesuperheater
boolean
No
false
Presence of desuperheater? [465]
extension/TankModelType
string
See [466]
No
mixed
Tank model type
extension/NumberofBedroomsServed
integer
> NumberofBedrooms
See [467]
Number of bedrooms served directly or indirectly
[453] FuelType choices are “natural gas”, “fuel oil”, “fuel oil 1”, “fuel oil 2”, “fuel oil 4”, “fuel oil 5/6”, “diesel”, “propane”, “kerosene”, “coal”, “coke”, “bituminous coal”, “anthracite coal”, “electricity”, “wood”, or “wood pellets”.
[454] Location choices are “conditioned space”, “basement - unconditioned”, “basement - conditioned”, “attic - unvented”, “attic - vented”, “garage”, “crawlspace - unvented”, “crawlspace - vented”, “crawlspace - conditioned”, “other exterior”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.
[455] If Location not provided, defaults to the first present space type:
- IECC zones 1-3: “garage”, “conditioned space”
- IECC zones 3-8, unknown: “basement - unconditioned”, “basement - conditioned”, “conditioned space”
[456] If TankVolume not provided, defaults based on Table 8 in the 2014 BAHSP.
[457] The sum of all
FractionDHWLoadServed
(across all WaterHeatingSystems) must equal to 1.[458] 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).
[459] If HeatingCapacity not provided, defaults based on Table 8 in the 2014 BAHSP.
[460] UsageBin choices are “very small”, “low”, “medium”, or “high”.
[461] UsageBin/FirstHourRating are only used for water heaters that use UniformEnergyFactor. If neither UsageBin nor FirstHourRating provided, UsageBin defaults to “medium”. If FirstHourRating provided and UsageBin not provided, UsageBin is determined based on the FirstHourRating value.
[462] RecoveryEfficiency must also be greater than the EnergyFactor (or UniformEnergyFactor).
[463] 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
[464] The water heater setpoint can alternatively be defined using Detailed Schedule Inputs.
[465] Additional desuperheater inputs are described in Desuperheater.
[466] TankModelType choices are “mixed” or “stratified”.
[467] 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 [468]
Yes
Fuel type
WaterHeaterType
string
instantaneous water heater
Yes
Type of water heater
Location
string
See [469]
No
See [470]
Water heater location
IsSharedSystem
boolean
No
false
Whether it serves multiple dwelling units or shared laundry room
PerformanceAdjustment
double
frac
>= 0, <= 1
No
See [471]
Multiplier on efficiency, typically to account for cycling
FractionDHWLoadServed
double
frac
>= 0, <= 1 [472]
Yes
Fraction of hot water load served [473]
UniformEnergyFactor
orEnergyFactor
double
frac
< 1
Yes
EnergyGuide label rated efficiency
HotWaterTemperature
double
F
> 0
No
125
Water heater setpoint [474]
UsesDesuperheater
boolean
No
false
Presence of desuperheater? [475]
extension/NumberofBedroomsServed
integer
> NumberofBedrooms
See [476]
Number of bedrooms served directly or indirectly
[468] FuelType choices are “natural gas”, “fuel oil”, “fuel oil 1”, “fuel oil 2”, “fuel oil 4”, “fuel oil 5/6”, “diesel”, “propane”, “kerosene”, “coal”, “coke”, “bituminous coal”, “anthracite coal”, “electricity”, “wood”, or “wood pellets”.
[469] Location choices are “conditioned space”, “basement - unconditioned”, “basement - conditioned”, “attic - unvented”, “attic - vented”, “garage”, “crawlspace - unvented”, “crawlspace - vented”, “crawlspace - conditioned”, “other exterior”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.
[470] If Location not provided, defaults to the first present space type:
- IECC zones 1-3: “garage”, “conditioned space”
- IECC zones 3-8, unknown: “basement - unconditioned”, “basement - conditioned”, “conditioned space”
[471] If PerformanceAdjustment not provided, defaults to 0.94 (UEF) or 0.92 (EF) based on ANSI/RESNET/ICC 301-2019.
[472] The sum of all
FractionDHWLoadServed
(across all WaterHeatingSystems) must equal to 1.[473] 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).
[474] The water heater setpoint can alternatively be defined using Detailed Schedule Inputs.
[475] Additional desuperheater inputs are described in Desuperheater.
[476] 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 [477]
No
See [478]
Water heater location
IsSharedSystem
boolean
No
false
Whether it serves multiple dwelling units or shared laundry room
TankVolume
double
gal
> 0
Yes
Nominal tank volume
FractionDHWLoadServed
double
frac
>= 0, <= 1 [479]
Yes
Fraction of hot water load served [480]
UniformEnergyFactor
orEnergyFactor
double
frac
> 1, <= 5
Yes
EnergyGuide label rated efficiency
HPWHOperatingMode
string
See [481]
No
hybrid/auto
Operating mode [482]
UsageBin
orFirstHourRating
string or double
str or gal/hr
See [483] or > 0
No
See [484]
EnergyGuide label usage bin/first hour rating
WaterHeaterInsulation/Jacket/JacketRValue
double
F-ft2-hr/Btu
>= 0
No
0
R-value of additional tank insulation wrap
HotWaterTemperature
double
F
> 0
No
125
Water heater setpoint [485]
UsesDesuperheater
boolean
No
false
Presence of desuperheater? [486]
extension/NumberofBedroomsServed
integer
> NumberofBedrooms
See [487]
Number of bedrooms served directly or indirectly
[477] Location choices are “conditioned space”, “basement - unconditioned”, “basement - conditioned”, “attic - unvented”, “attic - vented”, “garage”, “crawlspace - unvented”, “crawlspace - vented”, “crawlspace - conditioned”, “other exterior”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.
[478] If Location not provided, defaults to the first present space type:
- IECC zones 1-3: “garage”, “conditioned space”
- IECC zones 3-8, unknown: “basement - unconditioned”, “basement - conditioned”, “conditioned space”
[479] The sum of all
FractionDHWLoadServed
(across all WaterHeatingSystems) must equal to 1.[480] 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).
[481] HPWHOperatingMode choices are “hybrid/auto” or “heat pump only”.
[482] The heat pump water heater operating mode can alternatively be defined using Detailed Schedule Inputs.
[483] UsageBin choices are “very small”, “low”, “medium”, or “high”.
[484] UsageBin/FirstHourRating are only used for water heaters that use UniformEnergyFactor. If neither UsageBin nor FirstHourRating provided, UsageBin defaults to “medium”. If FirstHourRating provided and UsageBin not provided, UsageBin is determined based on the FirstHourRating value.
[485] The water heater setpoint can alternatively be defined using Detailed Schedule Inputs.
[486] Additional desuperheater inputs are described in Desuperheater.
[487] 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/ 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 [488]
No
See [489]
Water heater location
IsSharedSystem
boolean
No
false
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 [490]
Yes
Fraction of hot water load served [491]
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 [492]
Storage tank standby losses
HotWaterTemperature
double
F
> 0
No
125
Water heater setpoint [493]
RelatedHVACSystem
idref
See [494]
Yes
ID of boiler
extension/NumberofBedroomsServed
integer
> NumberofBedrooms
See [495]
Number of bedrooms served directly or indirectly
[488] Location choices are “conditioned space”, “basement - unconditioned”, “basement - conditioned”, “attic - unvented”, “attic - vented”, “garage”, “crawlspace - unvented”, “crawlspace - vented”, “crawlspace - conditioned”, “other exterior”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.
[489] If Location not provided, defaults to the first present space type:
- IECC zones 1-3: “garage”, “conditioned space”
- IECC zones 3-8, unknown: “basement - unconditioned”, “basement - conditioned”, “conditioned space”
[490] The sum of all
FractionDHWLoadServed
(across all WaterHeatingSystems) must equal to 1.[491] 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).
[492] If StandbyLoss not provided, defaults based on a regression analysis of AHRI Directory of Certified Product Performance.
[493] The water heater setpoint can alternatively be defined using Detailed Schedule Inputs.
[494] RelatedHVACSystem must reference a
HeatingSystem
(Boiler).[495] 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 [496]
No
See [497]
Water heater location
IsSharedSystem
boolean
No
false
Whether it serves multiple dwelling units or shared laundry room
FractionDHWLoadServed
double
frac
>= 0, <= 1 [498]
Yes
Fraction of hot water load served [499]
HotWaterTemperature
double
F
> 0
No
125
Water heater setpoint [500]
RelatedHVACSystem
idref
See [501]
Yes
ID of boiler
extension/NumberofBedroomsServed
integer
> NumberofBedrooms
See [502]
Number of bedrooms served directly or indirectly
[496] Location choices are “conditioned space”, “basement - unconditioned”, “basement - conditioned”, “attic - unvented”, “attic - vented”, “garage”, “crawlspace - unvented”, “crawlspace - vented”, “crawlspace - conditioned”, “other exterior”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.
[497] If Location not provided, defaults to the first present space type:
- IECC zones 1-3: “garage”, “conditioned space”
- IECC zones 3-8, unknown: “basement - unconditioned”, “basement - conditioned”, “conditioned space”
[498] The sum of all
FractionDHWLoadServed
(across all WaterHeatingSystems) must equal to 1.[499] 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).
[500] The water heater setpoint can alternatively be defined using Detailed Schedule Inputs.
[501] RelatedHVACSystem must reference a
HeatingSystem
(Boiler).[502] 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 [503]
Yes
ID of heat pump or air conditioner
[503] RelatedHVACSystem must reference a
HeatPump
(air-to-air, mini-split, or ground-to-air) orCoolingSystem
(central air conditioner or mini-split).Warning
A desuperheater is currently not allow if detailed water heater setpoint schedules are used.
HPXML Hot Water Distribution
If any water heating systems are provided, a single hot water distribution system must be described:
Hot water distribution systems are modeled according to the Energy Rating Rated Home in ANSI/RESNET/ICC 301-2019.
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 distribution system
SystemType/Standard/PipingLength
double
ft
> 0
No
See [504]
Length of piping [505]
PipeInsulation/PipeRValue
double
F-ft2-hr/Btu
>= 0
No
0.0
Pipe insulation R-value
DrainWaterHeatRecovery
element
No
<none>
Presence of drain water heat recovery device [506]
[504] If PipingLength not provided, calculated using the following equation from ANSI/RESNET/ICC 301-2019:
PipeL = 2.0 * (CFA / NCfl)^0.5 + 10.0 * NCfl + 5.0 * Bsmnt
where
CFA = conditioned floor area [ft2],
NCfl = number of conditioned floor levels in the residence including conditioned basements,
Bsmnt = presence (1.0) or absence (0.0) of an unconditioned basement in the residence. If a building has both a conditioned and unconditioned basement on the same level, Bsmnt = 0 to avoid double counting.
[505] PipingLength is the length of hot water piping from the hot water heater 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).
[506] 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 distribution system
SystemType/Recirculation/ControlType
string
See [507]
Yes
Recirculation control type
SystemType/Recirculation/RecirculationPipingLoopLength
double
ft
> 0
No
See [508]
Recirculation piping loop length [509]
SystemType/Recirculation/BranchPipingLength
double
ft
> 0
No
10
Branch piping length [510]
SystemType/Recirculation/PumpPower
double
W
>= 0
No
50 [511]
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 [512]
extension/RecirculationPumpWeekdayScheduleFractions
array
No
See [513]
24 comma-separated recirculation pump weekday fractions
extension/RecirculationPumpWeekendScheduleFractions
array
No
24 comma-separated recirculation pump weekend fractions
extension/RecirculationPumpMonthlyScheduleMultipliers
array
No
See [514]
12 comma-separated recirculation pump monthly multipliers
[507] 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.
[508] If RecirculationPipingLoopLength not provided, calculated using the following equation from ANSI/RESNET/ICC 301-2019:
RecircPipeL = 2.0 * (2.0 * (CFA / NCfl)^0.5 + 10.0 * NCfl + 5.0 * Bsmnt) - 20.0
where
CFA = conditioned floor area [ft2],
NCfl = number of conditioned floor levels in the residence including conditioned basements,
Bsmnt = presence (1.0) or absence (0.0) of an unconditioned basement in the residence. If a building has both a conditioned and unconditioned basement on the same level, Bsmnt = 0 to avoid double counting.
[509] 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.
[510] 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.
[511] PumpPower default based on ANSI/RESNET/ICC 301-2019.
[512] Additional drain water heat recovery inputs are described in Drain Water Heat Recovery.
[513] If RecirculationPumpWeekdayScheduleFractions or RecirculationPumpWeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), defaults as:
- no control, timer: “0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042” (based on Equation 4.2-43a of ANSI/RESNET/ICC 301-2022 Addendum C)
- manual demand control, presence sensor demand control: “0.012, 0.006, 0.004, 0.005, 0.010, 0.034, 0.078, 0.086, 0.080, 0.067, 0.056, 0.047, 0.040, 0.035, 0.033, 0.031, 0.038, 0.051, 0.060, 0.060, 0.055, 0.048, 0.038, 0.026” (based on Table C.3(5) of ANSI/RESNET/ICC 301-2022 Addendum C)
- temperature: “0.067, 0.072, 0.074, 0.073, 0.069, 0.048, 0.011, 0.003, 0.009, 0.020, 0.030, 0.037, 0.043, 0.047, 0.050, 0.051, 0.044, 0.034, 0.026, 0.026, 0.030, 0.036, 0.045, 0.055” (based on Table C.3(5) of ANSI/RESNET/ICC 301-2022 Addendum C)
[514] If RecirculationPumpMonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values are used: “1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0”.
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 [523]
Yes
Specifies which facilities are connected
EqualFlow
boolean
Yes
Specifies how the DHWR is configured [524]
Efficiency
double
frac
> 0, <= 1
Yes
Efficiency according to CSA 55.1
[523] 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.
[524] 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.
Drain water heat recovery is modeled according to the Energy Rating Rated Home in ANSI/RESNET/ICC 301-2019.
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 [525]
Yes
Bathroom faucet or shower
Count
integer
> 0
No
See [526]
Number of similar water fixtures
LowFlow
and/orFlowRate
boolean or double
gpm
> 0
Yes
Whether the fixture is considered low-flow and/or the flow rate [527]
[525] WaterFixtureType choices are “shower head” or “faucet”. If the shower stall has multiple shower heads that operate simultaneously, combine them as a single entry.
[526] A WaterFixture is considered low-flow if the fixture’s flow rate (gpm) is <= 2.0. Where a shower stall has multiple shower heads that operate simultaneously, use the sum of their flows.
[527] If Count not provided for any water fixture, assumes that 60% of all fixtures are faucets and 40% are shower heads.
Additional information can be entered in /HPXML/Building/BuildingDetails/Systems/WaterHeating/
.
Element
Type
Units
Constraints
Required
Default
Notes
extension/WaterFixturesUsageMultiplier
double
>= 0
No
1.0
Multiplier on hot water usage
extension/WaterFixturesWeekdayScheduleFractions
array
No
See [528]
24 comma-separated weekday fractions
extension/WaterFixturesWeekendScheduleFractions
array
No
24 comma-separated weekend fractions
extension/WaterFixturesMonthlyScheduleMultipliers
array
No
See [529]
12 comma-separated monthly multipliers
[528] If WaterFixturesWeekdayScheduleFractions or WaterFixturesWeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Table C.3(5) of ANSI/RESNET/ICC 301-2022 Addendum C are used: “0.012, 0.006, 0.004, 0.005, 0.010, 0.034, 0.078, 0.086, 0.080, 0.067, 0.056, 0.047, 0.040, 0.035, 0.033, 0.031, 0.038, 0.051, 0.060, 0.060, 0.055, 0.048, 0.038, 0.026”.
[529] If WaterFixturesMonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values are used: “1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0”.
Water fixture hot water use is calculated per the Energy Rating Rated Home in ANSI/RESNET/ICC 301-2019.
HPXML Solar Thermal
A single solar hot water system can be described with either simple or detailed inputs.
It is recommended to use detailed inputs and allow EnergyPlus to calculate the solar contribution to the hot water load; the simple inputs are provided if equivalent calculations are performed in another software tool.
Simple Inputs
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, <= 1
Yes
Solar fraction [530]
ConnectedTo
idref
See [531]
No [532]
<none>
Connected water heater
[530] Portion of total conventional hot water heating load (delivered energy plus tank standby losses). Can be obtained from Directory of SRCC OG-300 Solar Water Heating System Ratings or NREL’s System Advisor Model or equivalent.
[531] ConnectedTo must reference a
WaterHeatingSystem
. The referenced water heater cannot be a space-heating boiler nor attached to a desuperheater.[532] 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 [533]
Yes
Loop type
CollectorType
string
See [534]
Yes
System type
CollectorAzimuth
orCollectorOrientation
integer or string
deg or direction
>= 0, <= 359 or See [535]
Yes
Direction panels face (clockwise from North)
CollectorTilt
double
deg
>= 0, <= 90
Yes
Tilt relative to horizontal
CollectorRatedOpticalEfficiency
double
frac
> 0, < 1
Yes
Rated optical efficiency [536]
CollectorRatedThermalLosses
double
Btu/hr-ft2-R
> 0
Yes
Rated thermal losses [537]
StorageVolume
double
gal
> 0
No
See [538]
Hot water storage volume
ConnectedTo
idref
See [539]
Yes
Connected water heater
[533] CollectorLoopType choices are “liquid indirect”, “liquid direct”, or “passive thermosyphon”.
[534] CollectorType choices are “single glazing black”, “double glazing black”, “evacuated tube”, or “integrated collector storage”.
[535] CollectorOrientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[536] CollectorRatedOpticalEfficiency is FRTA (y-intercept) from the Directory of SRCC OG-100 Certified Solar Collector Ratings.
[537] CollectorRatedThermalLosses is FRUL (slope) from the Directory of SRCC OG-100 Certified Solar Collector Ratings.
[538] If StorageVolume not provided, calculated as 1.5 gal/ft2 * CollectorArea.
[539] 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
.
If not entered, the simulation will not include photovoltaics.
Many of the inputs are adopted from the PVWatts model.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
IsSharedSystem
boolean
No
false
Whether it serves multiple dwelling units
Location
string
See [540]
No
roof
Mounting location
ModuleType
string
See [541]
No
standard
Type of module
Tracking
string
See [542]
No
fixed
Type of tracking
ArrayAzimuth
orArrayOrientation
integer or string
deg or direction
>= 0, <= 359 or See [543]
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
orYearModulesManufactured
double or integer
frac or #
>= 0, <= 1 or > 1600
No
0.14 [544]
System losses [545]
AttachedToInverter
idref
See [546]
Yes
ID of attached inverter
extension/NumberofBedroomsServed
integer
> NumberofBedrooms
See [547]
Number of bedrooms served
[540] Location choices are “ground” or “roof” mounted.
[541] ModuleType choices are “standard”, “premium”, or “thin film”.
[542] Tracking choices are “fixed”, “1-axis”, “1-axis backtracked”, or “2-axis”.
[543] ArrayOrientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[544] SystemLossesFraction default is derived from the PVWatts documentation, which breaks down the losses 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%
If YearModulesManufactured provided but not SystemLossesFraction, calculated as:
SystemLossesFraction = 1.0 - (1.0 - 0.14) * (1.0 - (1.0 - 0.995^(CurrentYear - YearModulesManufactured))).
[545] System losses due to soiling, shading, snow, mismatch, wiring, degradation, etc.
[546] AttachedToInverter must reference an
Inverter
.[547] 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.
HPXML Inverters
In addition, the PVSystem must be connected to an inverter that is entered as a /HPXML/Building/BuildingDetails/Systems/Photovoltaics/Inverter
.
HPXML Batteries
A single battery can be entered as a /HPXML/Building/BuildingDetails/Systems/Batteries/Battery
.
If not entered, the simulation will not include batteries.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
IsSharedSystem
boolean
No
false
Whether it serves multiple dwelling units
Location
string
See [549]
No
See [550]
Location
BatteryType
string
See [551]
Yes
Battery type
NominalCapacity[Units="kWh" or Units="Ah"]/Value
double
kWh or Ah
>= 0
No
See [552]
Nominal (total) capacity
UsableCapacity[Units="kWh" or Units="Ah"]/Value
double
kWh or Ah
>= 0, < NominalCapacity
No
See [553]
Usable capacity
RatedPowerOutput
double
W
>= 0
No
See [554]
Power output under non-peak conditions
NominalVoltage
double
V
>= 0
No
50
Nominal voltage
RoundTripEfficiency
double
frac
> 0, <= 1
No
0.925
Round trip efficiency
extension/NumberofBedroomsServed
integer
> NumberofBedrooms
See [555]
Number of bedrooms served
[549] Location choices are “conditioned space”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “crawlspace - conditioned”, “attic - vented”, “attic - unvented”, “garage”, or “outside”.
[550] If Location not provided, defaults to “garage” if a garage is present, otherwise “outside”.
[551] BatteryType only choice is “Li-ion”.
[552] If NominalCapacity not provided, defaults to UsableCapacity / 0.9 if UsableCapacity provided, else (RatedPowerOutput / 1000) / 0.5 if RatedPowerOutput provided, else 10 kWh.
[553] If UsableCapacity not provided, defaults to 0.9 * NominalCapacity.
[554] If RatedPowerOutput not provided, defaults to 0.5 * NominalCapacity * 1000.
[555] 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
An unscheduled battery in a home with photovoltaics (PV) will be controlled using a simple control strategy designed to maximize on site consumption of energy. The battery will charge if PV production is greater than the building electrical load and the battery is below its maximum capacity, while the battery will discharge if the building electrical load is greater than PV production and the battery is above its minimum capacity.
A battery can alternatively be controlled using Detailed Schedule Inputs, where charging and discharging schedules are defined. Positive schedule values control timing and magnitude of charging storage. Negative schedule values control timing and magnitude of discharging storage. Simultaneous charging and discharging of the battery is not allowed. The round trip efficiency affects charging and discharging; the reported charging and discharging rates will be larger than the schedule value by an amount equal to the losses due to the round trip efficiency.
A battery in a home without PV or charging/discharging schedules is assumed to operate as backup and is not modeled.
HPXML Generators
Each generator that provides on-site power is entered as a /HPXML/Building/BuildingDetails/Systems/extension/Generators/Generator
.
If not entered, the simulation will not include generators.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
IsSharedSystem
boolean
No
false
Whether it serves multiple dwelling units
FuelType
string
See [556]
Yes
Fuel type
AnnualConsumptionkBtu
double
kBtu/yr
> 0
Yes
Annual fuel consumed
AnnualOutputkWh
double
kWh/yr
> 0 [557]
Yes
Annual electricity produced
NumberofBedroomsServed
integer
> NumberofBedrooms
See [558]
Number of bedrooms served
[556] FuelType choices are “natural gas”, “fuel oil”, “fuel oil 1”, “fuel oil 2”, “fuel oil 4”, “fuel oil 5/6”, “diesel”, “propane”, “kerosene”, “coal”, “coke”, “bituminous coal”, “anthracite coal”, “wood”, or “wood pellets”.
[557] AnnualOutputkWh must also be < AnnualConsumptionkBtu*3.412 (i.e., the generator must consume more energy than it produces).
[558] 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
.
If not entered, the simulation will not include a clothes washer.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
IsSharedAppliance
boolean
No
false
Whether it serves multiple dwelling units [559]
Location
string
See [560]
No
conditioned space
Location
IntegratedModifiedEnergyFactor
orModifiedEnergyFactor
double
ft3/kWh/cyc
> 0
No
See [561]
Efficiency [562]
AttachedToWaterHeatingSystem
orAttachedToHotWaterDistribution
idref
See [563]
See [564]
ID of attached water heater or distribution system
extension/UsageMultiplier
double
>= 0
No
1.0
Multiplier on energy & hot water usage
extension/WeekdayScheduleFractions
array
No
See [565]
24 comma-separated weekday fractions
extension/WeekendScheduleFractions
array
No
24 comma-separated weekend fractions
extension/MonthlyScheduleMultipliers
array
No
See [566]
12 comma-separated monthly multipliers
[559] For example, a clothes washer in a shared laundry room of a MF building.
[560] 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.
[561] If neither IntegratedModifiedEnergyFactor nor ModifiedEnergyFactor provided, the following default values representing a standard clothes washer from 2006 will be used: IntegratedModifiedEnergyFactor = 1.0, RatedAnnualkWh = 400, LabelElectricRate = 0.12, LabelGasRate = 1.09, LabelAnnualGasCost = 27.0, LabelUsage = 6, Capacity = 3.0.
[562] 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.
[563] AttachedToWaterHeatingSystem must reference a
WaterHeatingSystem
; AttachedToHotWaterDistribution must reference aHotWaterDistribution
.[564] AttachedToWaterHeatingSystem (or AttachedToHotWaterDistribution) only required if IsSharedAppliance is true.
[565] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Table C.3(1) of ANSI/RESNET/ICC 301-2022 Addendum C are used: “0.009, 0.007, 0.004, 0.004, 0.007, 0.011, 0.022, 0.049, 0.073, 0.086, 0.084, 0.075, 0.067, 0.060, 0.049, 0.051, 0.050, 0.049, 0.049, 0.049, 0.049, 0.047, 0.032, 0.017”.
[566] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values are used: “1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0”.
If IntegratedModifiedEnergyFactor or ModifiedEnergyFactor is provided, a complete set of EnergyGuide label information is entered in ClothesWasher
.
Element
Type
Units
Constraints
Required
Default
Notes
RatedAnnualkWh
double
kWh/yr
> 0
Yes
EnergyGuide label annual consumption
LabelElectricRate
double
$/kWh
> 0
Yes
EnergyGuide label electricity rate
LabelGasRate
double
$/therm
> 0
Yes
EnergyGuide label natural gas rate
LabelAnnualGasCost
double
$
> 0
Yes
EnergyGuide label annual gas cost
LabelUsage
double
cyc/wk
> 0
Yes
EnergyGuide label number of cycles
Capacity
double
ft3
> 0
Yes
Clothes washer volume
Clothes washer energy use and hot water use is calculated per the Energy Rating Rated Home in ANSI/RESNET/ICC 301-2019 Addendum A.
HPXML Clothes Dryer
A single clothes dryer can be entered as a /HPXML/Building/BuildingDetails/Appliances/ClothesDryer
.
If not entered, the simulation will not include a clothes dryer.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
IsSharedAppliance
boolean
No
false
Whether it serves multiple dwelling units [567]
Location
string
See [568]
No
conditioned space
Location
FuelType
string
See [569]
Yes
Fuel type
CombinedEnergyFactor
orEnergyFactor
double
lb/kWh
> 0
No
See [570]
Efficiency [571]
Vented
boolean
No
true
Whether dryer is vented
VentedFlowRate
double
cfm
>= 0
No
100 [572]
Exhaust flow rate during operation
extension/UsageMultiplier
double
>= 0
No
1.0
Multiplier on energy use
extension/WeekdayScheduleFractions
array
No
See [573]
24 comma-separated weekday fractions
extension/WeekendScheduleFractions
array
No
24 comma-separated weekend fractions
extension/MonthlyScheduleMultipliers
array
No
See [574]
12 comma-separated monthly multipliers
[567] For example, a clothes dryer in a shared laundry room of a MF building.
[568] 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.
[569] FuelType choices are “natural gas”, “fuel oil”, “fuel oil 1”, “fuel oil 2”, “fuel oil 4”, “fuel oil 5/6”, “diesel”, “propane”, “kerosene”, “coal”, “coke”, “bituminous coal”, “anthracite coal”, “electricity”, “wood”, or “wood pellets”.
[570] If neither CombinedEnergyFactor nor EnergyFactor provided, the following default values representing a standard clothes dryer from 2006 will be used: CombinedEnergyFactor = 3.01.
[571] 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. CEF may be found using the manufacturer’s data sheet, the California Energy Commission Appliance Database, the EPA ENERGY STAR website, or another reputable source.
[572] VentedFlowRate default based on the 2010 BAHSP.
[573] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Table C.3(1) of ANSI/RESNET/ICC 301-2022 Addendum C are used: “0.010, 0.006, 0.004, 0.002, 0.004, 0.006, 0.016, 0.032, 0.048, 0.068, 0.078, 0.081, 0.074, 0.067, 0.058, 0.061, 0.055, 0.054, 0.051, 0.051, 0.052, 0.054, 0.044, 0.024”.
[574] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values are used: “1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0”.
Clothes dryer energy use is calculated per the Energy Rating Rated Home in ANSI/RESNET/ICC 301-2019 Addendum A.
HPXML Dishwasher
A single dishwasher can be entered as a /HPXML/Building/BuildingDetails/Appliances/Dishwasher
.
If not entered, the simulation will not include a dishwasher.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
IsSharedAppliance
boolean
No
false
Whether it serves multiple dwelling units [575]
Location
string
See [576]
No
conditioned space
Location
RatedAnnualkWh
orEnergyFactor
double
kWh/yr or #
> 0
No
See [577]
EnergyGuide label consumption/efficiency [578]
AttachedToWaterHeatingSystem
orAttachedToHotWaterDistribution
idref
See [579]
See [580]
ID of attached water heater or distribution system
extension/UsageMultiplier
double
>= 0
No
1.0
Multiplier on energy & hot water usage
extension/WeekdayScheduleFractions
array
No
See [581]
24 comma-separated weekday fractions
extension/WeekendScheduleFractions
array
No
24 comma-separated weekend fractions
extension/MonthlyScheduleMultipliers
array
No
See [582]
12 comma-separated monthly multipliers
[575] For example, a dishwasher in a shared mechanical room of a MF building.
[576] 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.
[577] If neither RatedAnnualkWh nor EnergyFactor provided, the following default values representing a standard dishwasher from 2006 will be used: RatedAnnualkWh = 467, LabelElectricRate = 0.12, LabelGasRate = 1.09, LabelAnnualGasCost = 33.12, LabelUsage = 4, PlaceSettingCapacity = 12.
[578] 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.
[579] AttachedToWaterHeatingSystem must reference a
WaterHeatingSystem
; AttachedToHotWaterDistribution must reference aHotWaterDistribution
.[580] AttachedToWaterHeatingSystem (or AttachedToHotWaterDistribution) only required if IsSharedAppliance is true.
[581] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Table C.3(1) of ANSI/RESNET/ICC 301-2022 Addendum C are used: “0.015, 0.007, 0.005, 0.003, 0.003, 0.010, 0.020, 0.031, 0.058, 0.065, 0.056, 0.048, 0.042, 0.046, 0.036, 0.038, 0.038, 0.049, 0.087, 0.111, 0.090, 0.067, 0.044, 0.031”.
[582] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values are used: “1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0”.
If the RatedAnnualkWh or EnergyFactor is provided, a complete set of EnergyGuide label information is entered in Dishwasher
.
Element
Type
Units
Constraints
Required
Default
Notes
LabelElectricRate
double
$/kWh
> 0
Yes
EnergyGuide label electricity rate
LabelGasRate
double
$/therm
> 0
Yes
EnergyGuide label natural gas rate
LabelAnnualGasCost
double
$
> 0
Yes
EnergyGuide label annual gas cost
LabelUsage
double
cyc/wk
> 0
Yes
EnergyGuide label number of cycles
PlaceSettingCapacity
integer
#
> 0
Yes
Number of place settings
Dishwasher energy use and hot water use is calculated per the Energy Rating Rated Home in ANSI/RESNET/ICC 301-2019 Addendum A.
HPXML Refrigerators
Each refrigerator can be entered as a /HPXML/Building/BuildingDetails/Appliances/Refrigerator
.
If not entered, the simulation will not include a refrigerator.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
Location
string
See [583]
No
See [584]
Location
RatedAnnualkWh
double
kWh/yr
> 0
No
See [585]
Annual consumption
PrimaryIndicator
boolean
See [586]
Primary refrigerator?
extension/UsageMultiplier
double
>= 0
No
1.0
Multiplier on energy use
extension/WeekdayScheduleFractions
array
See [587]
No
See [588]
24 comma-separated weekday fractions
extension/WeekendScheduleFractions
array
No
24 comma-separated weekend fractions
extension/MonthlyScheduleMultipliers
array
No
See [589]
12 comma-separated monthly multipliers
extension/ConstantScheduleCoefficients
array
No
See [590]
24 comma-separated constant coefficients
extension/TemperatureScheduleCoefficients
array
No
See [591]
24 comma-separated temperature coefficients
[583] 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.
[584] If Location not provided and is the primary refrigerator, defaults to “conditioned space”. If Location not provided and is a secondary refrigerator, defaults to the first present space type: “garage”, “basement - unconditioned”, “basement - conditioned”, or “conditioned space”.
[585] If RatedAnnualkWh not provided, it will be defaulted to represent a standard refrigerator from 2006 using the following equation based on ANSI/RESNET/ICC 301-2019: RatedAnnualkWh = 637.0 + 18.0 * NumberofBedrooms.
[586] If multiple refrigerators are specified, there must be exactly one refrigerator described with PrimaryIndicator=true.
[587] Either schedule fraction inputs (WeekdayScheduleFractions/WeekendScheduleFractions/MonthlyScheduleMultipliers) or schedule coefficient inputs (ConstantScheduleCoefficients/TemperatureScheduleCoefficients) may be used, but not both.
[588] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs or schedule coefficients not used), default values from Figure 16 of the 2010 BAHSP are used: “0.040, 0.039, 0.038, 0.037, 0.036, 0.036, 0.038, 0.040, 0.041, 0.041, 0.040, 0.040, 0.042, 0.042, 0.042, 0.041, 0.044, 0.048, 0.050, 0.048, 0.047, 0.046, 0.044, 0.041”.
[589] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs or schedule coefficients not used), default values from Figure 24 of the 2010 BAHSP are used: “0.837, 0.835, 1.084, 1.084, 1.084, 1.096, 1.096, 1.096, 1.096, 0.931, 0.925, 0.837”.
[590] If ConstantScheduleCoefficients not provided (and Detailed Schedule Inputs or schedule fractions not used), default values from Table C.3(2) of ANSI/RESNET/ICC 301-2022 Addendum C are used: “-0.487, -0.340, -0.370, -0.361, -0.515, -0.684, -0.471, -0.159, -0.079, -0.417, -0.411, -0.386, -0.240, -0.314, -0.160, -0.121, -0.469, -0.412, -0.091, 0.077, -0.118, -0.247, -0.445, -0.544”.
[591] If TemperatureScheduleCoefficients not provided (and Detailed Schedule Inputs or schedule fractions not used), default values from Table C.3(2) of ANSI/RESNET/ICC 301-2022 Addendum C are used: “0.019, 0.016, 0.017, 0.016, 0.018, 0.021, 0.019, 0.015, 0.015, 0.019, 0.018, 0.018, 0.016, 0.017, 0.015, 0.015, 0.020, 0.020, 0.017, 0.014, 0.016, 0.017, 0.019, 0.020”.
Note
Refrigerator energy use is affected by its ambient temperature when ConstantScheduleCoefficients and TemperatureScheduleCoefficients are used, in which case hourly energy for refrigerators is determined following Equation 4.2-X2 of ANSI/RESNET/ICC 301-2022 Addendum C:
((RatedAnnualkWh / 8760) * (ConstantScheduleCoefficients[hr] + TemperatureScheduleCoefficients[hr] * T_space)
where T_space is the ambient temperature (F) where the refrigerator is located and hr is the hour of the day.
HPXML Freezers
Each standalone freezer can be entered as a /HPXML/Building/BuildingDetails/Appliances/Freezer
.
If not entered, the simulation will not include a standalone freezer.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
Location
string
See [592]
No
See [593]
Location
RatedAnnualkWh
double
kWh/yr
> 0
No
319.8 [594]
Annual consumption
extension/UsageMultiplier
double
>= 0
No
1.0
Multiplier on energy use
extension/WeekdayScheduleFractions
array
See [595]
No
See [596]
24 comma-separated weekday fractions
extension/WeekendScheduleFractions
array
No
24 comma-separated weekend fractions
extension/MonthlyScheduleMultipliers
array
No
See [597]
12 comma-separated monthly multipliers
extension/ConstantScheduleCoefficients
array
No
24 comma-separated constant coefficients
extension/TemperatureScheduleCoefficients
array
No
24 comma-separated temperature coefficients
[592] 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.
[593] If Location not provided, defaults to “garage” if present, otherwise “basement - unconditioned” if present, otherwise “basement - conditioned” if present, otherwise “conditioned space”.
[594] RatedAnnualkWh default based on the 2010 BAHSP.
[595] Either schedule fraction inputs (WeekdayScheduleFractions/WeekendScheduleFractions/MonthlyScheduleMultipliers) or schedule coefficient inputs (ConstantScheduleCoefficients/TemperatureScheduleCoefficients) may be used, but not both.
[596] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs or schedule coefficients not used), default values from Figure 16 of the 2010 BAHSP are used: “0.040, 0.039, 0.038, 0.037, 0.036, 0.036, 0.038, 0.040, 0.041, 0.041, 0.040, 0.040, 0.042, 0.042, 0.042, 0.041, 0.044, 0.048, 0.050, 0.048, 0.047, 0.046, 0.044, 0.041”.
[597] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs or schedule coefficients not used), default values from Figure 24 of the 2010 BAHSP are used: “0.837, 0.835, 1.084, 1.084, 1.084, 1.096, 1.096, 1.096, 1.096, 0.931, 0.925, 0.837”.
Note
Freezer energy use is affected by its ambient temperature when ConstantScheduleCoefficients and TemperatureScheduleCoefficients are used, in which case hourly energy for freezers is determined following Equation 4.2-X2 of ANSI/RESNET/ICC 301-2022 Addendum C:
((RatedAnnualkWh / 8760) * (ConstantScheduleCoefficients[hr] + TemperatureScheduleCoefficients[hr] * T_space)
where T_space is the ambient temperature (F) where the freezer is located and hr is the hour of the day.
HPXML Dehumidifier
Each dehumidifier can be entered as a /HPXML/Building/BuildingDetails/Appliances/Dehumidifier
.
If not entered, the simulation will not include a dehumidifier.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
Type
string
See [598]
Yes
Type of dehumidifier
Location
string
See [599]
Yes
Location of dehumidifier
Capacity
double
pints/day
> 0
Yes
Dehumidification capacity
IntegratedEnergyFactor
orEnergyFactor
double
liters/kWh
> 0
Yes
Rated efficiency
DehumidistatSetpoint
double
frac
>= 0, <= 1 [600]
Yes
Relative humidity setpoint
FractionDehumidificationLoadServed
double
frac
>= 0, <= 1 [601]
Yes
Fraction of dehumidification load served
[598] Type choices are “portable” or “whole-home”.
[599] Location only choice is “conditioned space”.
[600] If multiple dehumidifiers are entered, they must all have the same setpoint or an error will be generated.
[601] The sum of all
FractionDehumidificationLoadServed
(across all Dehumidifiers) must be less than or equal to 1.
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
.
If not entered, the simulation will not include a cooking range/oven.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
Location
string
See [602]
No
conditioned space
Location
FuelType
string
See [603]
Yes
Fuel type
IsInduction
boolean
No
false
Induction range?
extension/UsageMultiplier
double
>= 0
No
1.0
Multiplier on energy use
extension/WeekdayScheduleFractions
array
No
See [604]
24 comma-separated weekday fractions
extension/WeekendScheduleFractions
array
No
24 comma-separated weekend fractions
extension/MonthlyScheduleMultipliers
array
No
See [605]
12 comma-separated monthly multipliers
[602] 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.
[603] FuelType choices are “natural gas”, “fuel oil”, “fuel oil 1”, “fuel oil 2”, “fuel oil 4”, “fuel oil 5/6”, “diesel”, “propane”, “kerosene”, “coal”, “coke”, “bituminous coal”, “anthracite coal”, “electricity”, “wood”, or “wood pellets”.
[604] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Table C.3(1) of ANSI/RESNET/ICC 301-2022 Addendum C are used: “0.008, 0.008, 0.008, 0.008, 0.008, 0.015, 0.023, 0.039, 0.046, 0.046, 0.046, 0.054, 0.062, 0.046, 0.039, 0.054, 0.076, 0.134, 0.114, 0.058, 0.039, 0.031, 0.023, 0.015”.
[605] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values are used: “1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0”.
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
No
false
Convection oven?
Cooking range/oven energy use is calculated per the Energy Rating Rated Home in ANSI/RESNET/ICC 301-2019.
HPXML Lighting & Ceiling Fans
Lighting and ceiling fans are entered in /HPXML/Building/BuildingDetails/Lighting
.
HPXML Lighting
Lighting is described using multiple LightingGroup
elements for each location (interior, exterior, or garage).
If no LightingGroup elements are provided for a given location (e.g., exterior), the simulation will not include that lighting use.
Lighting can be specified in one of two ways:
With either lighting specification, additional information can be entered in /HPXML/Building/BuildingDetails/Lighting
.
Element
Type
Units
Constraints
Required
Default
Notes
extension/InteriorUsageMultiplier
double
>= 0
No
1.0
Multiplier on interior lighting use
extension/GarageUsageMultiplier
double
>= 0
No
1.0
Multiplier on garage lighting use
extension/ExteriorUsageMultiplier
double
>= 0
No
1.0
Multiplier on exterior lighting use
extension/InteriorWeekdayScheduleFractions
array
No
See [606]
24 comma-separated interior weekday fractions
extension/InteriorWeekendScheduleFractions
array
No
24 comma-separated interior weekend fractions
extension/InteriorMonthlyScheduleMultipliers
array
No
See [607]
12 comma-separated interior monthly multipliers
extension/GarageWeekdayScheduleFractions
array
No
See [608]
24 comma-separated garage weekday fractions
extension/GarageWeekendScheduleFractions
array
No
24 comma-separated garage weekend fractions
extension/GarageMonthlyScheduleMultipliers
array
No
See [609]
12 comma-separated garage monthly multipliers
extension/ExteriorWeekdayScheduleFractions
array
No
See [610]
24 comma-separated exterior weekday fractions
extension/ExteriorWeekendScheduleFractions
array
No
24 comma-separated exterior weekend fractions
extension/ExteriorMonthlyScheduleMultipliers
array
No
See [611]
12 comma-separated exterior monthly multipliers
[606] If InteriorWeekdayScheduleFractions or InteriorWeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Table C.3(3) of ANSI/RESNET/ICC 301-2022 Addendum C are used: “0.012, 0.010, 0.010, 0.010, 0.011, 0.018, 0.030, 0.038, 0.041, 0.041, 0.039, 0.037, 0.036, 0.035, 0.037, 0.041, 0.050, 0.065, 0.086, 0.106, 0.110, 0.079, 0.040, 0.018”.
[607] If InteriorMonthlyScheduleMultipliers not provided (or Detailed Schedule Inputs not used), default values from Table C.3(4) of ANSI/RESNET/ICC 301-2022 Addendum C are used: “1.19, 1.11, 1.02, 0.93, 0.84, 0.80, 0.82, 0.88, 0.98, 1.07, 1.16, 1.20”.
[608] If GarageWeekdayScheduleFractions or GarageWeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Table C.3(3) of ANSI/RESNET/ICC 301-2022 Addendum C are used: “0.023, 0.019, 0.015, 0.017, 0.021, 0.031, 0.042, 0.041, 0.034, 0.029, 0.027, 0.025, 0.021, 0.021, 0.021, 0.026, 0.031, 0.044, 0.084, 0.117, 0.113, 0.096, 0.063, 0.039”.
[609] If GarageMonthlyScheduleMultipliers not provided (or Detailed Schedule Inputs not used), default values from Table C.3(4) of ANSI/RESNET/ICC 301-2022 Addendum C are used: “1.19, 1.11, 1.02, 0.93, 0.84, 0.80, 0.82, 0.88, 0.98, 1.07, 1.16, 1.20”.
[610] If ExteriorWeekdayScheduleFractions or ExteriorWeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Table C.3(3) of ANSI/RESNET/ICC 301-2022 Addendum C are used: “0.040, 0.037, 0.037, 0.035, 0.035, 0.039, 0.044, 0.041, 0.031, 0.025, 0.024, 0.024, 0.025, 0.028, 0.030, 0.035, 0.044, 0.056, 0.064, 0.068, 0.070, 0.065, 0.056, 0.047”.
[611] If ExteriorMonthlyScheduleMultipliers not provided (or Detailed Schedule Inputs not used), default values from Table C.3(4) of ANSI/RESNET/ICC 301-2022 Addendum C are used: “1.19, 1.11, 1.02, 0.93, 0.84, 0.80, 0.82, 0.88, 0.98, 1.07, 1.16, 1.20”.
Lighting Type Fractions
If specifying lighting type fractions, three /HPXML/Building/BuildingDetails/Lighting/LightingGroup
elements (one for each possible LightingType
) are entered for each lighting location:
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
LightingType
element
See [612]
Yes
Lighting type
Location
string
See [613]
Yes
Lighting location [614]
FractionofUnitsInLocation
double
frac
>= 0, <= 1 [615]
Yes
Fraction of light fixtures in the location with the specified lighting type
[612] LightingType child element choices are
LightEmittingDiode
,CompactFluorescent
, orFluorescentTube
.[613] Location choices are “interior”, “garage”, or “exterior”.
[614] Garage lighting is ignored if the building has no garage specified elsewhere.
[615] 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.
Interior, exterior, and garage lighting energy use is calculated per the Energy Rating Rated Home in ANSI/RESNET/ICC 301-2019.
Annual Energy Consumption
If specifying annual energy consumption, a single /HPXML/Building/BuildingDetails/Lighting/LightingGroup
element is entered for each lighting location:
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
Location
string
See [616]
Yes
Lighting location [617]
Load[Units="kWh/year"]/Value
double
kWh/yr
>= 0
Yes
Lighting energy use
[616] Location choices are “interior”, “garage”, or “exterior”.
[617] Garage lighting is ignored if the building has no garage specified elsewhere.
Exterior Holiday Lighting
If exterior holiday lighting is specified, additional information is entered in /HPXML/Building/BuildingDetails/Lighting/extension/ExteriorHolidayLighting
.
Element
Type
Units
Constraints
Required
Default
Notes
Load[Units="kWh/day"]/Value
double
kWh/day
>= 0
No
See [618]
Holiday lighting energy use per day
PeriodBeginMonth
integer
>= 1, <= 12
No
11 (November)
Holiday lighting start date
PeriodBeginDayOfMonth
integer
>= 1, <= 31
No
24
Holiday lighting start date
PeriodEndMonth
integer
>= 1, <= 12
No
1 (January)
Holiday lighting end date
PeriodEndDayOfMonth
integer
>= 1, <= 31
No
6
Holiday lighting end date
WeekdayScheduleFractions
array
No
See [619]
24 comma-separated holiday weekday fractions
WeekendScheduleFractions
array
No
24 comma-separated holiday weekend fractions
[618] If Value not provided, defaults to 1.1 for single-family detached and 0.55 for others.
[619] If WeekdayScheduleFractions not provided (and Detailed Schedule Inputs not used), defaults to: 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0.008, 0.098, 0.168, 0.194, 0.284, 0.192, 0.037, 0.019.
HPXML Ceiling Fans
Each ceiling fan is entered as a /HPXML/Building/BuildingDetails/Lighting/CeilingFan
.
If not entered, the simulation will not include a ceiling fan.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
Airflow[FanSpeed="medium"]/Efficiency
and/orLabelEnergyUse
double
cfm/W or W
> 0
No
See [620]
Efficiency at medium speed or EnergyGuide label average energy use
Count
integer
> 0
No
See [621]
Number of similar ceiling fans
extension/WeekdayScheduleFractions
array
No
See [622]
24 comma-separated weekday fractions
extension/WeekendScheduleFractions
array
No
24 comma-separated weekend fractions
extension/MonthlyScheduleMultipliers
array
No
See [623]
12 comma-separated monthly multipliers
[620] If Efficiency and LabelEnergyUse not provided, LabelEnergyUse defaults to 42.6 W based on ANSI/RESNET/ICC 301-2022 Addendum C. If both are provided, LabelEnergyUse will be used in the model.
[621] If Count not provided, defaults to NumberofBedrooms + 1 based on ANSI/RESNET/ICC 301-2019.
[622] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Table C.3(5) of ANSI/RESNET/ICC 301-2022 Addendum C are used: “0.057, 0.057, 0.057, 0.057, 0.057, 0.057, 0.057, 0.024, 0.024, 0.024, 0.024, 0.024, 0.024, 0.024, 0.024, 0.024, 0.024, 0.024, 0.052, 0.057, 0.057, 0.057, 0.057, 0.057”.
[623] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), defaults based on monthly average outdoor temperatures per ANSI/RESNET/ICC 301-2019
Ceiling fan energy use is calculated per the Energy Rating Rated Home in ANSI/RESNET/ICC 301-2019.
Note
A reduced cooling setpoint can be specified for months when ceiling fans are operating. See HPXML HVAC Control for more information.
HPXML Pools & Permanent Spas
HPXML Pools
A single pool can be entered as a /HPXML/Building/BuildingDetails/Pools/Pool
.
If not entered, the simulation will not include a pool.
Pool Pump
If a pool is specified, a single pool pump can be entered as a Pool/Pumps/Pump
.
If not entered, the simulation will not include a pool pump.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
Type
string
See [625]
Yes
Pool pump type
Load[Units="kWh/year"]/Value
double
kWh/yr
>= 0
No
See [626]
Pool pump energy use
extension/UsageMultiplier
double
>= 0
No
1.0
Multiplier on pool pump energy use
extension/WeekdayScheduleFractions
array
No
See [627]
24 comma-separated weekday fractions
extension/WeekendScheduleFractions
array
No
24 comma-separated weekend fractions
extension/MonthlyScheduleMultipliers
array
No
See [628]
12 comma-separated monthly multipliers
[625] Type choices are “single speed”, “multi speed”, “variable speed”, “variable flow”, “other”, “unknown”, or “none”. If “none” is entered, the simulation will not include a pool pump.
[626] If Value not provided, defaults based on the 2010 BAHSP: 158.5 / 0.070 * (0.5 + 0.25 * NumberofBedrooms / 3 + 0.25 * ConditionedFloorArea / 1920). If NumberofResidents provided, this value will be adjusted using the HPXML Building Occupancy.
[627] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Figure 23 of the 2010 BAHSP are used: “0.003, 0.003, 0.003, 0.004, 0.008, 0.015, 0.026, 0.044, 0.084, 0.121, 0.127, 0.121, 0.120, 0.090, 0.075, 0.061, 0.037, 0.023, 0.013, 0.008, 0.004, 0.003, 0.003, 0.003”.
[628] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values from Figure 24 of the 2010 BAHSP are used: “1.154, 1.161, 1.013, 1.010, 1.013, 0.888, 0.883, 0.883, 0.888, 0.978, 0.974, 1.154”.
Pool Heater
If a pool is specified, a pool heater can be entered as a Pool/Heater
.
If not entered, the simulation will not include a pool heater.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
Type
string
See [629]
Yes
Pool heater type
Load[Units="kWh/year" or Units="therm/year"]/Value
double
kWh/yr or therm/yr
>= 0
No
See [630]
Pool heater energy use
extension/UsageMultiplier
double
>= 0
No
1.0
Multiplier on pool heater energy use
extension/WeekdayScheduleFractions
array
No
See [631]
24 comma-separated weekday fractions
extension/WeekendScheduleFractions
array
No
24 comma-separated weekend fractions
extension/MonthlyScheduleMultipliers
array
No
See [632]
12 comma-separated monthly multipliers
[629] Type choices are “none, “gas fired”, “electric resistance”, or “heat pump”. If “none” is entered, the simulation will not include a pool heater.
[630] If Value not provided, defaults as follows:
- gas fired [therm/year]: 3.0 / 0.014 * (0.5 + 0.25 * NumberofBedrooms / 3 + 0.25 * ConditionedFloorArea / 1920) (based on the 2010 BAHSP)
- electric resistance [kWh/year]: 8.3 / 0.004 * (0.5 + 0.25 * NumberofBedrooms / 3 + 0.25 * ConditionedFloorArea / 1920) (based on the 2010 BAHSP)
- heat pump [kWh/year]: (electric resistance [kWh/year]) / 5.0 (based on an average COP of 5 from Energy Saver)
If NumberofResidents provided, this value will be adjusted using the HPXML Building Occupancy.
[631] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Figure 23 of the 2010 BAHSP are used: “0.003, 0.003, 0.003, 0.004, 0.008, 0.015, 0.026, 0.044, 0.084, 0.121, 0.127, 0.121, 0.120, 0.090, 0.075, 0.061, 0.037, 0.023, 0.013, 0.008, 0.004, 0.003, 0.003, 0.003”.
[632] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values from Figure 24 of the 2010 BAHSP are used: “1.154, 1.161, 1.013, 1.010, 1.013, 0.888, 0.883, 0.883, 0.888, 0.978, 0.974, 1.154”.
HPXML Permanent Spas
A single permanent spa can be entered as a /HPXML/Building/BuildingDetails/Spas/PermanentSpa
.
If not entered, the simulation will not include a permanent spa.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
Type
string
See [633]
Yes
Permanent spa type
[633] Type choices are “in ground”, “on ground”, “above ground”, “other”, “unknown”, or “none”. If “none” is entered, the simulation will not include a permanent spa.
Permanent Spa Pump
If a permanent spa is specified, a single permanent spa pump can be entered as a PermanentSpa/Pumps/Pump
.
If not entered, the simulation will not include a permanent spa pump.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
Type
string
See [634]
Yes
Permanent spa pump type
Load[Units="kWh/year"]/Value
double
kWh/yr
>= 0
No
See [635]
Permanent spa pump energy use
extension/UsageMultiplier
double
>= 0
No
1.0
Multiplier on permanent spa pump energy use
extension/WeekdayScheduleFractions
array
No
See [636]
24 comma-separated weekday fractions
extension/WeekendScheduleFractions
array
No
24 comma-separated weekend fractions
extension/MonthlyScheduleMultipliers
array
No
See [637]
12 comma-separated monthly multipliers
[634] Type choices are “single speed”, “multi speed”, “variable speed”, “variable flow”, “other”, “unknown”, or “none”. If “none” is entered, the simulation will not include a permanent spa pump.
[635] If Value not provided, defaults based on the 2010 BAHSP: 59.5 / 0.059 * (0.5 + 0.25 * NumberofBedrooms / 3 + 0.25 * ConditionedFloorArea / 1920). If NumberofResidents provided, this value will be adjusted using the HPXML Building Occupancy.
[636] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Figure 23 of the 2010 BAHSP are used: “0.024, 0.029, 0.024, 0.029, 0.047, 0.067, 0.057, 0.024, 0.024, 0.019, 0.015, 0.014, 0.014, 0.014, 0.024, 0.058, 0.126, 0.122, 0.068, 0.061, 0.051, 0.043, 0.024, 0.024”.
[637] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values from Figure 24 of the 2010 BAHSP are used: “0.921, 0.928, 0.921, 0.915, 0.921, 1.160, 1.158, 1.158, 1.160, 0.921, 0.915, 0.921”.
Permanent Spa Heater
If a permanent spa is specified, a permanent spa heater can be entered as a PermanentSpa/Heater
.
If not entered, the simulation will not include a permanent spa heater.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
Type
string
See [638]
Yes
Permanent spa heater type
Load[Units="kWh/year" or Units="therm/year"]/Value
double
kWh/yr or therm/yr
>= 0
No
See [639]
Permanent spa heater energy use
extension/UsageMultiplier
double
>= 0
No
1.0
Multiplier on permanent spa heater energy use
extension/WeekdayScheduleFractions
array
No
See [640]
24 comma-separated weekday fractions
extension/WeekendScheduleFractions
array
No
24 comma-separated weekend fractions
extension/MonthlyScheduleMultipliers
array
No
See [641]
12 comma-separated monthly multipliers
[638] Type choices are “none, “gas fired”, “electric resistance”, or “heat pump”. If “none” is entered, the simulation will not include a permanent spa heater.
[639] If Value not provided, defaults as follows:
- gas fired [therm/year]: 0.87 / 0.011 * (0.5 + 0.25 * NumberofBedrooms / 3 + 0.25 * ConditionedFloorArea / 1920) (based on the 2010 BAHSP)
- electric resistance [kWh/year]: 49.0 / 0.048 * (0.5 + 0.25 * NumberofBedrooms / 3 + 0.25 * ConditionedFloorArea / 1920) (based on the 2010 BAHSP)
- heat pump [kWh/year] = (electric resistance) / 5.0 (based on an average COP of 5 from Energy Saver)
If NumberofResidents provided, this value will be adjusted using the HPXML Building Occupancy.
[640] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Figure 23 of the 2010 BAHSP are used: “0.024, 0.029, 0.024, 0.029, 0.047, 0.067, 0.057, 0.024, 0.024, 0.019, 0.015, 0.014, 0.014, 0.014, 0.024, 0.058, 0.126, 0.122, 0.068, 0.061, 0.051, 0.043, 0.024, 0.024”.
[641] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values from Figure 24 of the 2010 BAHSP are used: “0.837, 0.835, 1.084, 1.084, 1.084, 1.096, 1.096, 1.096, 1.096, 0.931, 0.925, 0.837”.
HPXML Misc Loads
Miscellaneous loads are entered in /HPXML/Building/BuildingDetails/MiscLoads
.
HPXML Plug Loads
Each type of plug load can be entered as a /HPXML/Building/BuildingDetails/MiscLoads/PlugLoad
.
It is required to include miscellaneous plug loads (PlugLoadType=”other”), which represents all residual plug loads not explicitly captured elsewhere. It is common to include television plug loads (PlugLoadType=”TV other”), which represents all television energy use in the home. It is less common to include the other plug load types, as they are less frequently found in homes. If not entered, the simulation will not include that type of plug load.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
PlugLoadType
string
See [642]
Yes
Type of plug load
Load[Units="kWh/year"]/Value
double
kWh/yr
>= 0
No
See [643]
Annual electricity consumption
extension/FracSensible
double
>= 0, <= 1
No
See [644]
Fraction that is sensible heat gain to conditioned space [645]
extension/FracLatent
double
>= 0, <= 1
No
See [646]
Fraction that is latent heat gain to conditioned space
extension/UsageMultiplier
double
>= 0
No
1.0
Multiplier on electricity use
extension/WeekdayScheduleFractions
array
No
See [647]
24 comma-separated weekday fractions
extension/WeekendScheduleFractions
array
No
24 comma-separated weekend fractions
extension/MonthlyScheduleMultipliers
array
No
See [648]
12 comma-separated monthly multipliers
[642] PlugLoadType choices are “other”, “TV other”, “well pump”, or “electric vehicle charging”.
[643] If Value not provided, defaults as:
- other: 0.91 * ConditionedFloorArea (based on ANSI/RESNET/ICC 301-2019)
- TV other: 413.0 + 69.0 * NumberofBedrooms (based on ANSI/RESNET/ICC 301-2019)
- well pump: 50.8 / 0.127 * (0.5 + 0.25 * NumberofBedrooms / 3 + 0.25 * ConditionedFloorArea / 1920) (based on the 2010 BAHSP)
- electric vehicle charging: 1666.67 (calculated using AnnualMiles * kWhPerMile / (ChargerEfficiency * BatteryEfficiency) where AnnualMiles=4500, kWhPerMile=0.3, ChargerEfficiency=0.9, and BatteryEfficiency=0.9)
If NumberofResidents provided, any value based on NumberofBedrooms will be adjusted using the HPXML Building Occupancy.
[644] If FracSensible not provided, defaults as:
- other: 0.855
- TV other: 1.0
- well pump: 0.0
- electric vehicle charging: 0.0
[645] The remaining fraction (i.e., 1.0 - FracSensible - FracLatent) must be > 0 and is assumed to be heat gain outside conditioned space and thus lost.
[646] If FracLatent not provided, defaults as:
- other: 0.045
- TV other: 0.0
- well pump: 0.0
- electric vehicle charging: 0.0
[647] If WeekdayScheduleFractions or WeekdendScheduleFractions not provided (and Detailed Schedule Inputs not used), defaults as:
- other: “0.036, 0.036, 0.036, 0.036, 0.036, 0.036, 0.038, 0.041, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.044, 0.047, 0.050, 0.051, 0.050, 0.048, 0.044, 0.040, 0.037” (based on Table C.3(1) of ANSI/RESNET/ICC 301-2022 Addendum C)
- TV other: “0.014, 0.007, 0.004, 0.003, 0.004, 0.006, 0.010, 0.015, 0.020, 0.025, 0.028, 0.031, 0.033, 0.038, 0.042, 0.046, 0.054, 0.062, 0.080, 0.110, 0.132, 0.125, 0.077, 0.034” (based on Table C.3(1) of ANSI/RESNET/ICC 301-2022 Addendum C)
- well pump: “0.044, 0.023, 0.019, 0.015, 0.016, 0.018, 0.026, 0.033, 0.033, 0.032, 0.033, 0.033, 0.032, 0.032, 0.032, 0.033, 0.045, 0.057, 0.066, 0.076, 0.081, 0.086, 0.075, 0.065” (based on Figure 23 of the 2010 BAHSP)
- electric vehicle charging: “0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042, 0.042”
[648] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values are used: “1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0”.
HPXML Fuel Loads
Each fuel load can be entered as a /HPXML/Building/BuildingDetails/MiscLoads/FuelLoad
.
It is less common to include fuel load types, as they are less frequently found in homes. If not entered, the simulation will not include that type of fuel load.
Element
Type
Units
Constraints
Required
Default
Notes
SystemIdentifier
id
Yes
Unique identifier
FuelLoadType
string
See [649]
Yes
Type of fuel load
Load[Units="therm/year"]/Value
double
therm/yr
>= 0
No
See [650]
Annual fuel consumption
FuelType
string
See [651]
Yes
Fuel type
extension/FracSensible
double
>= 0, <= 1
No
See [652]
Fraction that is sensible heat gain to conditioned space [653]
extension/FracLatent
double
>= 0, <= 1
No
See [654]
Fraction that is latent heat gain to conditioned space
extension/UsageMultiplier
double
>= 0
No
1.0
Multiplier on fuel use
extension/WeekdayScheduleFractions
array
No
See [655]
24 comma-separated weekday fractions
extension/WeekendScheduleFractions
array
No
24 comma-separated weekend fractions
extension/MonthlyScheduleMultipliers
array
No
See [656]
12 comma-separated monthly multipliers
[649] FuelLoadType choices are “grill”, “fireplace”, or “lighting”.
[650] If Value not provided, calculated as based on the 2010 BAHSP:
- grill: 0.87 / 0.029 * (0.5 + 0.25 * NumberofBedrooms / 3 + 0.25 * ConditionedFloorArea / 1920)
- fireplace: 1.95 / 0.032 * (0.5 + 0.25 * NumberofBedrooms / 3 + 0.25 * ConditionedFloorArea / 1920)
- lighting: 0.22 / 0.012 * (0.5 + 0.25 * NumberofBedrooms / 3 + 0.25 * ConditionedFloorArea / 1920)
If NumberofResidents provided, this value will be adjusted using the HPXML Building Occupancy.
[651] FuelType choices are “natural gas”, “fuel oil”, “fuel oil 1”, “fuel oil 2”, “fuel oil 4”, “fuel oil 5/6”, “diesel”, “propane”, “kerosene”, “coal”, “coke”, “bituminous coal”, “anthracite coal”, “wood”, or “wood pellets”.
[652] If FracSensible not provided, defaults to 0.5 for fireplace and 0.0 for all other types.
[653] The remaining fraction (i.e., 1.0 - FracSensible - FracLatent) must be > 0 and is assumed to be heat gain outside conditioned space and thus lost.
[654] If FracLatent not provided, defaults to 0.1 for fireplace and 0.0 for all other types.
[655] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Figure 23 of the 2010 BAHSP are used:
- grill: “0.004, 0.001, 0.001, 0.002, 0.007, 0.012, 0.029, 0.046, 0.044, 0.041, 0.044, 0.046, 0.042, 0.038, 0.049, 0.059, 0.110, 0.161, 0.115, 0.070, 0.044, 0.019, 0.013, 0.007”;
- fireplace: “0.044, 0.023, 0.019, 0.015, 0.016, 0.018, 0.026, 0.033, 0.033, 0.032, 0.033, 0.033, 0.032, 0.032, 0.032, 0.033, 0.045, 0.057, 0.066, 0.076, 0.081, 0.086, 0.075, 0.065”;
- lighting: “0.044, 0.023, 0.019, 0.015, 0.016, 0.018, 0.026, 0.033, 0.033, 0.032, 0.033, 0.033, 0.032, 0.032, 0.032, 0.033, 0.045, 0.057, 0.066, 0.076, 0.081, 0.086, 0.075, 0.065”.
[656] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values are used: “1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0”.
HPXML Locations
The various locations used in an HPXML file are defined as follows:
Value
Description
Temperature
Building Type
outside
Ambient environment
Weather data
Any
ground
EnergyPlus calculation
Any
conditioned space
Above-grade conditioned space maintained at setpoint
EnergyPlus calculation
Any
attic - vented
EnergyPlus calculation
Any
attic - unvented
EnergyPlus calculation
Any
basement - conditioned
Below-grade conditioned space maintained at setpoint
EnergyPlus calculation
Any
basement - unconditioned
EnergyPlus calculation
Any
crawlspace - vented
EnergyPlus calculation
Any
crawlspace - unvented
EnergyPlus calculation
Any
crawlspace - conditioned
Below-grade conditioned space maintained at setpoint
EnergyPlus calculation
Any
garage
Unconditioned garage (not shared parking garage) [657]
EnergyPlus calculation
Any
manufactured home underbelly
Underneath the belly, ambient environment
Weather data
Manufactured only
manufactured home belly
Within the belly
Same as conditioned space
Manufactured only
other housing unit
E.g., conditioned adjacent unit or conditioned corridor
Same as conditioned space
SFA/MF only
other heated space
E.g., shared laundry/equipment space
Avg of conditioned space/outside; min of heating setpoint
SFA/MF only
other multifamily buffer space
E.g., enclosed unconditioned stairwell
Avg of conditioned space/outside; min of 50F
SFA/MF only
other non-freezing space
E.g., shared parking garage ceiling
Floats with outside; minimum of 40F
SFA/MF only
other exterior
Water heater outside
Weather data
Any
exterior wall
Ducts in exterior wall
Avg of conditioned space/outside
Any
under slab
Ducts under slab (ground)
EnergyPlus calculation
Any
roof deck
Ducts on roof deck (outside)
Weather data
Any
[657] OpenStudio-HPXML 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:
An HPXML file provided is invalid (either relative to the HPXML schema or the EnergyPlus Use Case).
An unexpected EnergyPlus simulation error occurred.
If an error occurs, first look in the run.log for details. If there are no errors in that log file, then the error may be in the EnergyPlus simulation – see 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.