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 atHPXMLtoOpenStudio/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 atHPXMLtoOpenStudio/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.
Important
Usage of both validation approaches (XSD and Schematron) is recommended for developers actively working on creating HPXML files for EnergyPlus simulations:
- Validation against XSD for general correctness and usage of HPXML
- Validation against Schematron for understanding XML document requirements specific to running EnergyPlus
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'>living 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 model will proceed without refrigerator energy use. On the other hand, if there is aRefrigerator
element but with no values defined (i.e., noLocation
orRatedAnnualkWh
), 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]
[1] BeginMonth/BeginDayOfMonth date must occur before EndMonth/EndDayOfMonth date (e.g., a run period from 10/1 to 3/31 is invalid).
[2] If a leap year is specified (e.g., 2008), the EPW weather file must contain 8784 hours.
[3] CalendarYear only applies to TMY (Typical Meteorological Year) weather. For AMY (Actual Meteorological Year) weather, the AMY year will be used regardless of what is specified.
[4] TemperatureCapacitanceMultiplier affects the transient calculation of indoor air temperatures. Values greater than 1.0 have the effect of smoothing or damping the rate of change in the indoor air temperature from timestep to timestep. This heat capacitance effect is modeled on top of any other individual mass inputs (e.g., furniture mass, partition wall mass, interior drywall, etc.) in the HPXML.
HPXML HVAC Sizing Control¶
HVAC equipment sizing controls are entered in /HPXML/SoftwareInfo/extension/HVACSizingControl
.
Element Type Units Constraints Required Default Description AllowIncreasedFixedCapacities
boolean No false Logic for fixed capacity HVAC equipment [5] HeatPumpSizingMethodology
string See [6] No HERS Logic for autosized heat pumps [7]
[5] 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.
[6] HeatPumpSizingMethodology choices are ‘ACCA’, ‘HERS’, or ‘MaxLoad’.
[7] If HeatPumpSizingMethodology is ‘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. If HeatPumpSizingMethodology is ‘HERS’, autosized heat pumps have their nominal capacity sized equal to the larger of heating/cooling design loads. If HeatPumpSizingMethodology is ‘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.
HPXML Schedules¶
Schedules for a variety of building features can be 1) specified via simple inputs, 2) specified via detailed inputs, or 3) defaulted. It is allowed to use simple, detailed, and defaulted values in the same HPXML run.
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 smooth schedules, or they can 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/SoftwareInfo/extension/SchedulesFilePath
elements.
The column names available in the schedule CSV files are:
Column Name Units Description Affected by Vacancy occupants
frac Occupant heat gain schedule. Yes lighting_interior
frac Interior lighting energy use schedule. Yes lighting_exterior
frac Exterior lighting energy use schedule. Yes lighting_garage
frac Garage lighting energy use schedule. Yes lighting_exterior_holiday
frac Exterior holiday lighting energy use schedule. Yes 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. Yes plug_loads_well_pump
frac Well pump plug load energy use schedule. Yes fuel_loads_grill
frac Grill fuel load energy use schedule. Yes fuel_loads_lighting
frac Lighting fuel load energy use schedule. Yes fuel_loads_fireplace
frac Fireplace fuel load energy use schedule. Yes pool_pump
frac Pool pump energy use schedule. No pool_heater
frac Pool heater energy use schedule. No hot_tub_pump
frac Hot tub pump energy use schedule. No hot_tub_heater
frac Hot tub 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 heating_setpoint
F Thermostat heating setpoint schedule. No cooling_setpoint
F Thermostat cooling setpoint schedule. No water_heater_setpoint
F Water heater setpoint schedule. No water_heater_operating_mode
0/1 Heat pump water heater operating mode schedule. 0=standard, 1=heat pump only. No battery
frac Battery schedule. Positive for charging, negative for discharging. No vacancy
0/1 Vacancy schedule. 0=occupied, 1=vacant. Automatically overrides other columns. N/A
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.
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 or smooth occupancy schedule CSV file can also be automatically generated for you; see the Usage Instructions for the commands.
Inputs for the schedule generator are entered in /HPXML/Building/BuildingDetails/BuildingSummary/BuildingOccupancy/NumberofResidents
and /HPXML/Building/Site/Address/StateCode
.
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 Occupancy Calculation Type¶
The occupancy calculation type is entered in /HPXML/SoftwareInfo/extension/OccupancyCalculationType
: either “asset” or “operational”; it defaults to “asset”.
If OccupancyCalculationType is “asset”, various end uses (e.g., clothes washer) are calculated using number of bedrooms and/or conditioned floor area.
If OccupancyCalculationType is “operational”, end uses based on number of bedrooms are adjusted for the number of occupants using the relationship 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
HPXML Emissions Scenarios¶
One or more emissions scenarios can be entered as an /HPXML/SoftwareInfo/extension/EmissionsScenarios/EmissionsScenario
.
Element Type Units Constraints Required Default Notes Name
string Yes Name of the scenario (which shows up in the output file) EmissionsType
string See [8] Yes Type of emissions (e.g., CO2e) EmissionsFactor
element >= 1 See [9] Emissions factor(s) for a given fuel type
[8] EmissionsType can be anything. But if certain values are provided (e.g., “CO2e”), then some emissions factors can be defaulted as described further below.
[9] 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 [10] Yes Emissions factor units Value
orScheduleFilePath
double or string See [11] Yes Emissions factor annual value or schedule file with hourly values
[10] Units choices are “lb/MWh” and “kg/MWh”.
[11] 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 [12] Yes Emissions factor fuel type Units
string See [13] Yes Emissions factor units Value
double Yes Emissions factor annual value
[12] FuelType choices are “natural gas”, “propane”, “fuel oil”, “coal”, “wood”, and “wood pellets”.
[13] Units choices are “lb/MBtu” and “kg/MBtu”.
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 are from Table 5.1.2(1) National Average Emission Factors for Household Fuels from ANSI/RESNET/ICCC 301 Standard for the Calculation and Labeling of the Energy Performance of Dwelling and Sleeping Units using an Energy Rating Index 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
.
Element Type Units Constraints Required Default Notes Name
string Yes Name of the scenario (which shows up in the output file) UtilityRate
element >= 0 Utility rate(s) for a given fuel type PVCompensation
element <= 1 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 MarginalRate
double $/kWh No See [14] Marginal flat rate
[14] If MarginalRate not provided, defaults to state, regional, or national average based on 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 [15]
[15] 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 [16] Yes Fuel type FixedCharge
double $/month No See [17] Monthly fixed charge MarginalRate
double See [18] No See [19] Marginal flat rate
[16] FuelType choices are “natural gas”, “propane”, “fuel oil”, “coal”, “wood”, and “wood pellets”.
[17] FixedCharge defaults to $12/month for natural gas and $0/month for other fuels.
[18] MarginalRate units are $/therm for natural gas, $/gallon for propane and fuel oil, and $/kBtu for other fuels.
[19] If MarginalRate not provided, defaults to state, regional, or national average based on 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 [20] No User-Specified Net metering annual excess sellback rate type [21] AnnualExcessSellbackRate
double $/kWh No [22] 0.03 User-specified net metering annual excess sellback rate [23]
[20] AnnualExcessSellbackRateType choices are “User-Specified” and “Retail Electricity Cost”.
[21] 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.
[22] AnnualExcessSellbackRate is only used when AnnualExcessSellbackRateType=”User-Specified”.
[23] 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 [24]
[24] 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 Site¶
Building site information can be entered in /HPXML/Building/Site
.
Element Type Units Constraints Required Default Description SiteID
id Yes Unique identifier Address/StateCode
string No See [25] State/territory where the home is located Address/ZipCode
string See [26] No ZIP Code where the home is located TimeZone/UTCOffset
double See [27] No See [28] Difference in decimal hours between the home’s time zone and UTC TimeZone/DSTObserved
boolean No true Daylight saving time observed?
[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] UTCOffset ranges from -12 to 14.
[28] 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) [29] Start date DSTEndMonth
andDSTEndDayOfMonth
integer 1 - 12 and 1 - 31 No EPW else 11/5 (November 5) End date
[29] 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 [30] No suburban Terrain type for infiltration model ShieldingofHome
string See [31] No normal Presence of nearby buildings, trees, obstructions for infiltration model extension/GroundConductivity
double Btu/hr-ft-F > 0 No 1.0 Thermal conductivity of the ground soil [32] extension/Neighbors
element >= 0 No <none> Presence of neighboring buildings for solar shading
[30] SiteType choices are “rural”, “suburban”, or “urban”.
[31] ShieldingofHome choices are “normal”, “exposed”, or “well-shielded”.
[32] GroundConductivity used for foundation heat transfer and ground source heat pumps.
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 [33] 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 [34] Height of neighbor
[33] Orientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[34] 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 See [35] <number of bedrooms> Number of occupants [36] extension/WeekdayScheduleFractions
array No See [37] 24 comma-separated weekday fractions extension/WeekendScheduleFractions
array No 24 comma-separated weekend fractions extension/MonthlyScheduleMultipliers
array No See [38] 12 comma-separated monthly multipliers
[35] NumberofResidents is required if OccupancyCalculationType is “operational”, .
[36] If OccupancyCalculationType is “asset”, NumberofResidents is only used to define the heat gain from occupants; various end uses (e.g., clothes washer) are calculated using number of bedrooms and/or conditioned floor area. If OccupancyCalculationType is “operational”, end uses based on number of bedrooms are adjusted for the number of occupants.
[37] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Figures 25 of the 2010 BAHSP are used: “0.061, 0.061, 0.061, 0.061, 0.061, 0.061, 0.061, 0.053, 0.025, 0.015, 0.015, 0.015, 0.015, 0.015, 0.015, 0.015, 0.018, 0.033, 0.054, 0.054, 0.054, 0.061, 0.061, 0.061”.
[38] 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 Building Construction¶
Building construction is entered in /HPXML/Building/BuildingDetails/BuildingSummary/BuildingConstruction
.
Element Type Units Constraints Required Default Notes ResidentialFacilityType
string See [39] Yes Type of dwelling unit 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) NumberofBedrooms
integer > 0 Yes Number of bedrooms NumberofBathrooms
integer > 0 No See [40] Number of bathrooms ConditionedFloorArea
double ft2 > 0 Yes Floor area within conditioned space boundary (excluding conditioned crawlspace floor area) ConditionedBuildingVolume
orAverageCeilingHeight
double ft3 or ft > 0 No See [41] Volume/ceiling height within conditioned space boundary (including a conditioned basement/crawlspace) extension/HasFlueOrChimney
boolean No See [42] Presence of flue or chimney for infiltration model
[39] ResidentialFacilityType choices are “single-family detached”, “single-family attached”, “apartment unit”, or “manufactured home”.
[40] If NumberofBathrooms not provided, calculated as NumberofBedrooms/2 + 0.5 based on the 2010 BAHSP.
[41] If neither ConditionedBuildingVolume nor AverageCeilingHeight provided, AverageCeilingHeight defaults to the lesser of 8.0 and InfiltrationVolume / ConditionedFloorArea. If needed, additional defaulting is performed using the following relationship: ConditionedBuildingVolume = ConditionedFloorArea * AverageCeilingHeight + ConditionedCrawlspaceVolume.
[42] If HasFlueOrChimney not provided, assumed to be true if any of the following conditions are met:
- heating system is non-electric Furnace, Boiler, WallFurnace, FloorFurnace, Stove, PortableHeater, or FixedHeater and AFUE/Percent is less than 0.89,
- heating system is non-electric Fireplace, or
- water heater is non-electric with energy factor (or equivalent calculated from uniform energy factor) less than 0.63.
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 [43] Yes IECC year ClimateZone
string See [44] Yes IECC zone
[43] Year choices are 2003, 2006, 2009, 2012, 2015, 2018, or 2021.
[44] 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) [45]
[45] 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 BuildingAirLeakage/UnitofMeasure
string See [46] Yes Units for air leakage HousePressure
double Pa > 0 See [47] House pressure with respect to outside [48] BuildingAirLeakage/AirLeakage
double > 0 Yes Value for air leakage InfiltrationVolume
double ft3 > 0 No ConditionedBuildingVolume Volume associated with infiltration measurement InfiltrationHeight
double ft > 0 No See [49] Height associated with infiltration measurement [50]
[46] UnitofMeasure choices are “ACH” (air changes per hour at user-specified pressure), “CFM” (cubic feet per minute at user-specified pressure), or “ACHnatural” (natural air changes per hour).
[47] HousePressure only required if BuildingAirLeakage/UnitofMeasure is not “ACHnatural”.
[48] HousePressure typical value is 50 Pa.
[49] 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.).
[50] InfiltrationHeight is defined as the vertical distance between the lowest and highest above-grade points within the pressure boundary, per ASHRAE 62.2.
HPXML Attics¶
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 [51] No SLA Units for ventilation rate Value
double > 0 No 1/300 [52] Value for ventilation rate
[51] UnitofMeasure choices are “SLA” (specific leakage area) or “ACHnatural” (natural air changes per hour).
[52] Value default based on ANSI/RESNET/ICC 301-2019.
HPXML Foundations¶
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 [53] No SLA Units for ventilation rate Value
double > 0 No 1/150 [54] Value for ventilation rate
[53] UnitofMeasure only choice is “SLA” (specific leakage area).
[54] Value default based on ANSI/RESNET/ICC 301-2019.
HPXML Roofs¶
Each pitched or flat roof surface that is exposed to ambient conditions is entered as an /HPXML/Building/BuildingDetails/Enclosure/Roofs/Roof
.
For a multifamily building where the dwelling unit has another dwelling unit above it, the surface between the two dwelling units should be considered a Floor
and not a Roof
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier InteriorAdjacentTo
string See [55] 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 [56] No See [57] Direction (clockwise from North) RoofType
string See [58] No asphalt or fiberglass shingles Roof type RoofColor
orSolarAbsorptance
string or double See [59] or 0 - 1 No medium Roof color or solar absorptance [60] Emittance
double 0 - 1 No 0.90 Emittance InteriorFinish/Type
string See [61] No See [62] Interior finish material InteriorFinish/Thickness
double in >= 0 No 0.5 Interior finish thickness Pitch
integer ?:12 >= 0 Yes Pitch RadiantBarrier
boolean No false Presence of radiant barrier 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 [63]
[55] InteriorAdjacentTo choices are “attic - vented”, “attic - unvented”, “living space”, or “garage”. See HPXML Locations for descriptions.
[56] Orientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[57] 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.
[58] 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”.
[59] RoofColor choices are “light”, “medium”, “medium dark”, “dark”, or “reflective”.
[60] 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
[61] InteriorFinish/Type choices are “gypsum board”, “gypsum composite board”, “plaster”, “wood”, “other”, or “none”.
[62] InteriorFinish/Type defaults to “gypsum board” if InteriorAdjacentTo is living space, otherwise “none”.
[63] 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 an /HPXML/Building/BuildingDetails/Enclosure/RimJoists/RimJoist
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier ExteriorAdjacentTo
string See [64] Yes Exterior adjacent space type InteriorAdjacentTo
string See [65] Yes Interior adjacent space type Area
double ft2 > 0 Yes Gross area Azimuth
orOrientation
integer or string deg or direction 0 - 359 or See [66] No See [67] Direction (clockwise from North) Siding
string See [68] No wood siding Siding material Color
orSolarAbsorptance
string or double See [69] or 0 - 1 No medium Color or solar absorptance [70] 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 [71]
[64] 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.
[65] InteriorAdjacentTo choices are “living space”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “crawlspace - conditioned”, or “garage”. See HPXML Locations for descriptions.
[66] Orientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[67] 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.
[68] 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”.
[69] Color choices are “light”, “medium”, “medium dark”, “dark”, or “reflective”.
[70] If SolarAbsorptance not provided, defaults based on Color:
- dark: 0.95
- medium dark: 0.85
- medium: 0.70
- light: 0.50
- reflective: 0.30
[71] AssemblyEffectiveRValue includes all material layers, interior/exterior air films, and insulation installation grade.
HPXML Walls¶
Each wall that has no contact with the ground and bounds a space type is entered as an /HPXML/Building/BuildingDetails/Enclosure/Walls/Wall
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier ExteriorAdjacentTo
string See [72] Yes Exterior adjacent space type InteriorAdjacentTo
string See [73] Yes Interior adjacent space type WallType
element 1 [74] 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 [75] No See [76] Direction (clockwise from North) Siding
string See [77] No wood siding Siding material Color
orSolarAbsorptance
string or double See [78] or 0 - 1 No medium Color or solar absorptance [79] Emittance
double 0 - 1 No 0.90 Emittance InteriorFinish/Type
string See [80] No See [81] Interior finish material InteriorFinish/Thickness
double in >= 0 No 0.5 Interior finish thickness Insulation/SystemIdentifier
id Yes Unique identifier Insulation/AssemblyEffectiveRValue
double F-ft2-hr/Btu > 0 Yes Assembly R-value [82]
[72] 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.
[73] InteriorAdjacentTo choices are “living space”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “crawlspace - conditioned”, or “garage”. See HPXML Locations for descriptions.
[74] WallType child element choices are WoodStud
,DoubleWoodStud
,ConcreteMasonryUnit
,StructuralInsulatedPanel
,InsulatedConcreteForms
,SteelFrame
,SolidConcrete
,StructuralBrick
,StrawBale
,Stone
,LogWall
, orAdobe
.
[75] Orientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[76] 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 living space and garage).
[77] 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”.
[78] Color choices are “light”, “medium”, “medium dark”, “dark”, or “reflective”.
[79] If SolarAbsorptance not provided, defaults based on Color:
- dark: 0.95
- medium dark: 0.85
- medium: 0.70
- light: 0.50
- reflective: 0.30
[80] InteriorFinish/Type choices are “gypsum board”, “gypsum composite board”, “plaster”, “wood”, “other”, or “none”.
[81] InteriorFinish/Type defaults to “gypsum board” if InteriorAdjacentTo is living space or basement - conditioned, otherwise “none”.
[82] AssemblyEffectiveRValue includes all material layers, interior/exterior air films, and insulation installation grade.
HPXML Foundation Walls¶
Each wall that is in contact with the ground should be specified as an /HPXML/Building/BuildingDetails/Enclosure/FoundationWalls/FoundationWall
.
Other walls (e.g., wood framed walls) that are connected to a below-grade space but have no contact with the ground should be specified as a Wall
and not a FoundationWall
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier ExteriorAdjacentTo
string See [83] Yes Exterior adjacent space type [84] InteriorAdjacentTo
string See [85] Yes Interior adjacent space type Type
string See [86] 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 [87] No See [88] Direction (clockwise from North) Thickness
double in > 0 No 8.0 Thickness excluding interior framing DepthBelowGrade
double ft 0 - Height Yes Depth below grade [89] InteriorFinish/Type
string See [90] No See [91] 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 0 - 1 See [92] Interior insulation layer Insulation/Layer[InstallationType="continuous - exterior"]
element 0 - 1 See [93] Exterior insulation layer Insulation/AssemblyEffectiveRValue
double F-ft2-hr/Btu > 0 See [94] Assembly R-value [95]
[83] 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.
[84] InteriorAdjacentTo choices are “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “crawlspace - conditioned”, or “garage”. See HPXML Locations for descriptions.
[85] 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.
[86] 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”.
[87] Orientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[88] 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).
[89] 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.
[90] InteriorFinish/Type choices are “gypsum board”, “gypsum composite board”, “plaster”, “wood”, “other”, or “none”.
[91] InteriorFinish/Type defaults to “gypsum board” if InteriorAdjacentTo is basement - conditioned, otherwise “none”.
[92] Layer[InstallationType=”continuous - interior”] only required if AssemblyEffectiveRValue is not provided.
[93] Layer[InstallationType=”continuous - exterior”] only required if AssemblyEffectiveRValue is not provided.
[94] AssemblyEffectiveRValue only required if Layer elements are not provided.
[95] 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 [96] No Height Vertical distance from top of foundation wall to bottom of insulation
[96] 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 an /HPXML/Building/BuildingDetails/Enclosure/Floors/Floor
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier ExteriorAdjacentTo
string See [97] Yes Exterior adjacent space type InteriorAdjacentTo
string See [98] Yes Interior adjacent space type FloorType
element 1 [99] Yes Floor type (for thermal mass) Area
double ft2 > 0 Yes Gross area InteriorFinish/Type
string See [100] No See [101] Interior finish material InteriorFinish/Thickness
double in >= 0 No 0.5 Interior finish thickness Insulation/SystemIdentifier
id Yes Unique identifier Insulation/AssemblyEffectiveRValue
double F-ft2-hr/Btu > 0 Yes Assembly R-value [102]
[97] 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.
[98] InteriorAdjacentTo choices are “living space”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “crawlspace - conditioned”, or “garage”. See HPXML Locations for descriptions.
[99] FloorType child element choices are WoodFrame
,StructuralInsulatedPanel
,SteelFrame
, orSolidConcrete
.
[100] InteriorFinish/Type choices are “gypsum board”, “gypsum composite board”, “plaster”, “wood”, “other”, or “none”.
[101] InteriorFinish/Type defaults to “gypsum board” if InteriorAdjacentTo is living space and the surface is a ceiling, otherwise “none”.
[102] AssemblyEffectiveRValue includes all material layers, interior/exterior air films, and insulation installation grade.
For floors adjacent to “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”, additional information is entered in Floor
.
HPXML Slabs¶
Each space type that borders the ground (i.e., basements, crawlspaces, garages, and slab-on-grade foundations) should have a slab entered as an /HPXML/Building/BuildingDetails/Enclosure/Slabs/Slab
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier InteriorAdjacentTo
string See [104] Yes Interior adjacent space type Area
double ft2 > 0 Yes Gross area Thickness
double in >= 0 No See [105] Thickness [106] ExposedPerimeter
double ft >= 0 Yes Perimeter exposed to ambient conditions [107] DepthBelowGrade
double ft >= 0 See [108] 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 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 UnderSlabInsulation/Layer/InsulationWidth
double ft >= 0 See [109] Width from slab edge inward of horizontal insulation UnderSlabInsulation/Layer/InsulationSpansEntireSlab
boolean See [110] Whether horizontal insulation spans entire slab extension/CarpetFraction
double frac 0 - 1 No See [111] Fraction of slab covered by carpet extension/CarpetRValue
double F-ft2-hr/Btu >= 0 No See [112] Carpet R-value
[104] InteriorAdjacentTo choices are “living space”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “crawlspace - conditioned”, or “garage”. See HPXML Locations for descriptions.
[105] If Thickness not provided, defaults to 0 when adjacent to crawlspace and 4 inches for all other cases.
[106] For a crawlspace with a dirt floor, enter a thickness of zero.
[107] 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.
[108] DepthBelowGrade only required if the attached foundation has no FoundationWalls
. For foundation types with walls, the the slab’s position relative to grade is determined by theFoundationWall/DepthBelowGrade
value.
[109] InsulationWidth only required if InsulationSpansEntireSlab=true is not provided.
[110] InsulationSpansEntireSlab=true only required if InsulationWidth is not provided.
[111] If CarpetFraction not provided, defaults to 0.8 when adjacent to conditioned space, otherwise 0.0.
[112] If CarpetRValue not provided, defaults to 2.0 when adjacent to conditioned space, otherwise 0.0.
HPXML Windows¶
Each window or glass door area is entered as an /HPXML/Building/BuildingDetails/Enclosure/Windows/Window
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier Area
double ft2 > 0 Yes Total area Azimuth
orOrientation
integer or string deg or direction 0 - 359 or See [113] Yes Direction (clockwise from North) UFactor
and/orGlassLayers
double or string Btu/F-ft2-hr > 0 or See [114] 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) ExteriorShading/WinterShadingCoefficient
double frac 0 - 1 No 1.00 Exterior winter shading coefficient (1=transparent, 0=opaque) InteriorShading/SummerShadingCoefficient
double frac 0 - 1 No 0.70 [115] Interior summer shading coefficient (1=transparent, 0=opaque) InteriorShading/WinterShadingCoefficient
double frac 0 - 1 No 0.85 [116] Interior winter shading coefficient (1=transparent, 0=opaque) StormWindow/GlassType
string See [117] No Type of storm window glass Overhangs
element 0 - 1 No <none> Presence of overhangs (including roof eaves) FractionOperable
double frac 0 - 1 No 0.67 Operable fraction [118] AttachedToWall
idref See [119] Yes ID of attached wall
[113] Orientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”.
[114] GlassLayers choices are “single-pane”, “double-pane”, “triple-pane”, or “glass block”.
[115] InteriorShading/SummerShadingCoefficient default value indicates 30% reduction in solar heat gain, based on ANSI/RESNET/ICC 301-2019.
[116] InteriorShading/WinterShadingCoefficient default value indicates 15% reduction in solar heat gain, based on ANSI/RESNET/ICC 301-2019.
[117] 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.
[118] 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 (e.g., 4), the value should be between 0 and 1 (e.g., 0, 0.25, 0.5, 0.75, or 1). 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.
[119] AttachedToWall must reference a Wall
orFoundationWall
.
If operable windows are defined, the availability of natural ventilation is entered in /HPXML/SoftwareInfo/extension
.
Element Type Units Constraints Required Default Notes NaturalVentilationAvailabilityDaysperWeek
integer days/week 0 - 7 No 3 [120] How often windows can be opened by occupants for natural ventilation
[120] Default of 3 days per week (Monday/Wednesday/Friday) is based on 2010 BAHSP.
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 [121] Yes Type of frame FrameType/*/ThermalBreak
boolean See [122] No false Whether the Aluminum or Metal frame has a thermal break GlassType
string See [123] No clear Type of glass GasFill
string See [124] No See [125] Type of gas inside double/triple-pane windows
[121] FrameType child element choices are Aluminum
,Fiberglass
,Metal
,Vinyl
, orWood
.
[122] ThermalBreak is only valid if FrameType is Aluminum
orMetal
.
[123] GlassType choices are “clear”, “low-e”, “tinted”, “tinted/reflective”, or “reflective”.
[124] GasFill choices are “air”, “argon”, “krypton”, “xenon”, “nitrogen”, or “other”.
[125] If GasFill not provided, defaults to “air” for double-pane windows and “argon” for 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 – 1.27 0.75 single-pane Fiberglass, Vinyl, Wood – clear – 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 air 0.81 0.67 double-pane Aluminum, Metal true clear air 0.60 0.67 double-pane Fiberglass, Vinyl, Wood – clear 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 air 0.42 0.52 double-pane Aluminum, Metal true low-e <any but air> 0.47 0.62 double-pane Fiberglass, Vinyl, Wood – low-e <any but air> 0.39 0.52 double-pane Aluminum, Metal false reflective air 0.67 0.37 double-pane Aluminum, Metal true reflective air 0.47 0.37 double-pane Fiberglass, Vinyl, Wood – reflective air 0.39 0.31 double-pane Fiberglass, Vinyl, Wood – reflective <any but air> 0.36 0.31 triple-pane Fiberglass, Vinyl, Wood – low-e <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.
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 [126] Yes Vertical distance from overhang to bottom of window [127]
[126] The difference between DistanceToBottomOfWindow and DistanceToTopOfWindow defines the height of the window.
[127] When Depth is non-zero, DistanceToBottomOfWindow must be greater than DistanceToTopOfWindow.
HPXML Skylights¶
Each skylight is entered as an /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 [128] Yes Direction (clockwise from North) UFactor
and/orGlassLayers
double or string Btu/F-ft2-hr > 0 or See [129] 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) 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 [130] No Type of storm window glass AttachedToRoof
idref See [131] Yes ID of attached roof
[128] Orientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[129] GlassLayers choices are “single-pane”, “double-pane”, or “triple-pane”.
[130] 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.
[131] AttachedToRoof must reference a Roof
.
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 [132] Yes Type of frame FrameType/*/ThermalBreak
boolean See [133] No false Whether the Aluminum or Metal frame has a thermal break GlassType
string See [134] No <none> Type of glass GasFill
string See [135] No See [136] Type of gas inside double/triple-pane skylights
[132] FrameType child element choices are Aluminum
,Fiberglass
,Metal
,Vinyl
, orWood
.
[133] ThermalBreak is only valid if FrameType is Aluminum
orMetal
.
[134] GlassType choices are “clear”, “low-e”, “tinted”, “tinted/reflective”, or “reflective”. Do not specify this element if the skylight has clear glass.
[135] GasFill choices are “air”, “argon”, “krypton”, “xenon”, “nitrogen”, or “other”.
[136] If GasFill not provided, defaults to “air” for double-pane skylights and “argon” for 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 – 1.98 0.75 single-pane Fiberglass, Vinyl, Wood – clear – 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 air 1.30 0.67 double-pane Aluminum, Metal true clear air 1.10 0.67 double-pane Fiberglass, Vinyl, Wood – clear 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 air 0.74 0.52 double-pane Aluminum, Metal true low-e <any but air> 0.95 0.62 double-pane Fiberglass, Vinyl, Wood – low-e <any but air> 0.68 0.52 double-pane Aluminum, Metal false reflective air 1.17 0.37 double-pane Aluminum, Metal true reflective air 0.98 0.37 double-pane Fiberglass, Vinyl, Wood – reflective air 0.71 0.31 double-pane Fiberglass, Vinyl, Wood – reflective <any but air> 0.65 0.31 triple-pane Fiberglass, Vinyl, Wood – low-e <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 an /HPXML/Building/BuildingDetails/Enclosure/Doors/Door
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier AttachedToWall
idref See [137] Yes ID of attached wall Area
double ft2 > 0 Yes Total area Azimuth
orOrientation
integer or string deg 0 - 359 or See [138] No See [139] Direction (clockwise from North) RValue
double F-ft2-hr/Btu > 0 Yes R-value (including any storm door)
[137] AttachedToWall must reference a Wall
orFoundationWall
.
[138] Orientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[139] 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 [140] No gypsum board Interior finish material InteriorFinish/Thickness
double in >= 0 No 0.5 Interior finish thickness
[140] 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¶
Each heating system (other than a heat pump) is entered as an /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatingSystem
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier HeatingSystemType
element 1 [142] Yes Type of heating system HeatingSystemFuel
string See [143] Yes Fuel type HeatingCapacity
double Btu/hr >= 0 No autosized Heating output capacity FractionHeatLoadServed
double frac 0 - 1 [144] See [145] Fraction of heating load served
[142] HeatingSystemType child element choices are ElectricResistance
,Furnace
,WallFurnace
,FloorFurnace
,Boiler
,Stove
,PortableHeater
,FixedHeater
, orFireplace
.
[143] 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”. For ElectricResistance
, “electricity” is required.
[144] The sum of all FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.
[145] 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.
Electric Resistance¶
If electric resistance heating is specified, additional information is entered in HeatingSystem
.
Element Type Units Constraints Required Default Notes AnnualHeatingEfficiency[Units="Percent"]/Value
double frac 0 - 1 Yes Efficiency
Furnace¶
If a furnace is specified, additional information is entered in HeatingSystem
.
Element Type Units Constraints Required Default Notes DistributionSystem
idref See [146] Yes ID of attached distribution system AnnualHeatingEfficiency[Units="AFUE"]/Value
double frac 0 - 1 Yes Rated efficiency extension/FanPowerWattsPerCFM
double W/cfm >= 0 No See [147] Blower fan efficiency at maximum fan speed [148] extension/AirflowDefectRatio
double frac -0.9 - 9 No 0.0 Deviation between design/installed airflows [149]
[146] HVACDistribution type must be AirDistribution (type: “regular velocity” or “gravity”) or DSE.
[147] 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.
[148] If there is a cooling system attached to the DistributionSystem, the heating and cooling systems cannot have different values for FanPowerWattsPerCFM.
[149] AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information.
Wall/Floor Furnace¶
If a wall furnace or floor furnace is specified, additional information is entered in HeatingSystem
.
Element Type Units Constraints Required Default Notes AnnualHeatingEfficiency[Units="AFUE"]/Value
double frac 0 - 1 Yes Rated efficiency extension/FanPowerWatts
double W >= 0 No 0 Fan power
Boiler¶
If a boiler is specified, additional information is entered in HeatingSystem
.
Element Type Units Constraints Required Default Notes IsSharedSystem
boolean No false Whether it serves multiple dwelling units DistributionSystem
idref See [150] Yes ID of attached distribution system AnnualHeatingEfficiency[Units="AFUE"]/Value
double frac 0 - 1 Yes Rated efficiency
[150] For in-unit boilers, HVACDistribution type must be HydronicDistribution (type: “radiator”, “baseboard”, “radiant floor”, or “radiant ceiling”) or DSE. For shared boilers, HVACDistribution type must be HydronicDistribution (type: “radiator”, “baseboard”, “radiant floor”, “radiant ceiling”, or “water loop”) or AirDistribution (type: “fan coil”). If the shared boiler has “water loop” distribution, a Water-Loop-to-Air Heat Pump must also be specified.
If an in-unit boiler if specified, additional information is entered in HeatingSystem
.
If instead a shared boiler is specified, additional information is entered in HeatingSystem
.
Element Type Units Constraints Required Default Notes NumberofUnitsServed
integer > 1 Yes Number of dwelling units served ElectricAuxiliaryEnergy
orextension/SharedLoopWatts
double kWh/yr or W >= 0 No See [152] Electric auxiliary energy or shared loop power ElectricAuxiliaryEnergy
orextension/FanCoilWatts
double kWh/yr or W >= 0 No [153] Electric auxiliary energy or fan coil power
[152] If ElectricAuxiliaryEnergy nor SharedLoopWatts provided, defaults as follows:
- Shared boiler w/ baseboard: 220 kWh/yr
- Shared boiler w/ water loop heat pump: 265 kWh/yr
- Shared boiler w/ fan coil: 438 kWh/yr
[153] FanCoilWatts only used if boiler connected to fan coil and SharedLoopWatts provided.
Stove¶
If a stove is specified, additional information is entered in HeatingSystem
.
Element Type Units Constraints Required Default Notes AnnualHeatingEfficiency[Units="Percent"]/Value
double frac 0 - 1 Yes Efficiency extension/FanPowerWatts
double W >= 0 No 40 Fan power
Portable/Fixed Heater¶
If a portable heater or fixed heater is specified, additional information is entered in HeatingSystem
.
Element Type Units Constraints Required Default Notes AnnualHeatingEfficiency[Units="Percent"]/Value
double frac 0 - 1 Yes Efficiency extension/FanPowerWatts
double W >= 0 No 0 Fan power
Fireplace¶
If a fireplace is specified, additional information is entered in HeatingSystem
.
Element Type Units Constraints Required Default Notes AnnualHeatingEfficiency[Units="Percent"]/Value
double frac 0 - 1 Yes Efficiency extension/FanPowerWatts
double W >= 0 No 0 Fan power
HPXML Cooling Systems¶
Each cooling system (other than a heat pump) is entered as an /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/CoolingSystem
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier CoolingSystemType
string See [154] Yes Type of cooling system CoolingSystemFuel
string See [155] Yes Fuel type FractionCoolLoadServed
double frac 0 - 1 [156] Yes Fraction of cooling load served
[154] CoolingSystemType choices are “central air conditioner”, “room air conditioner”, “evaporative cooler”, “mini-split”, “chiller”, “cooling tower”, or “packaged terminal air conditioner”.
[155] CoolingSystemFuel only choice is “electricity”.
[156] The sum of all FractionCoolLoadServed
(across all HVAC systems) must be less than or equal to 1.
Central Air Conditioner¶
If a central air conditioner is specified, additional information is entered in CoolingSystem
.
Element Type Units Constraints Required Default Notes DistributionSystem
idref See [157] Yes ID of attached distribution system AnnualCoolingEfficiency[Units="SEER" or Units="SEER2"]/Value
double Btu/Wh or # > 0 Yes Rated efficiency [158] CoolingCapacity
double Btu/hr >= 0 No autosized Cooling output capacity SensibleHeatFraction
double frac 0 - 1 No Sensible heat fraction CompressorType
string See [159] No See [160] Type of compressor extension/FanPowerWattsPerCFM
double W/cfm >= 0 No See [161] Blower fan efficiency at maximum fan speed [162] extension/AirflowDefectRatio
double frac -0.9 - 9 No 0.0 Deviation between design/installed airflows [163] extension/ChargeDefectRatio
double frac -0.9 - 9 No 0.0 Deviation between design/installed charges [164]
[157] HVACDistribution type must be AirDistribution (type: “regular velocity”) or DSE.
[158] 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).
[159] CompressorType choices are “single stage”, “two stage”, or “variable speed”.
[160] If CompressorType not provided, defaults to “single stage” if SEER <= 15, else “two stage” if SEER <= 21, else “variable speed”.
[161] 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.
[162] If there is a heating system attached to the DistributionSystem, the heating and cooling systems cannot have different values for FanPowerWattsPerCFM.
[163] AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information.
[164] 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 pre-charged on site. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information.
Room Air Conditioner¶
If a room air conditioner is specified, additional information is entered in CoolingSystem
.
Element Type Units Constraints Required Default Notes AnnualCoolingEfficiency[Units="EER" or Units="CEER"]/Value
double Btu/Wh > 0 Yes Rated efficiency CoolingCapacity
double Btu/hr >= 0 No autosized Cooling output capacity SensibleHeatFraction
double frac 0 - 1 No Sensible heat fraction IntegratedHeatingSystemFuel
string See [165] No <none> Fuel type of integrated heater
[165] 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 Heating output capacity of integrated heater IntegratedHeatingSystemAnnualEfficiency[Units="Percent"]/Value
double frac 0 - 1 Yes Efficiency of integrated heater IntegratedHeatingSystemFractionHeatLoadServed
double frac 0 - 1 [166] Yes Fraction of heating load served
[166] The sum of all FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.
Packaged Terminal Air Conditioner¶
If a PTAC is specified, additional information is entered in CoolingSystem
.
Element Type Units Constraints Required Default Notes AnnualCoolingEfficiency[Units="EER" or Units="CEER"]/Value
double Btu/Wh > 0 Yes Rated efficiency CoolingCapacity
double Btu/hr >= 0 No autosized Cooling output capacity SensibleHeatFraction
double frac 0 - 1 No Sensible heat fraction IntegratedHeatingSystemFuel
string See [167] No <none> Fuel type of integrated heater
[167] 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 Heating output capacity of integrated heater IntegratedHeatingSystemAnnualEfficiency[Units="Percent"]/Value
double frac 0 - 1 Yes Efficiency of integrated heater IntegratedHeatingSystemFractionHeatLoadServed
double frac 0 - 1 [168] Yes Fraction of heating load served
[168] The sum of all FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.
Evaporative Cooler¶
If an evaporative cooler is specified, additional information is entered in CoolingSystem
.
Mini-Split Air Conditioner¶
If a mini-split air conditioner is specified, additional information is entered in CoolingSystem
.
Element Type Units Constraints Required Default Notes DistributionSystem
idref See [170] No ID of attached distribution system AnnualCoolingEfficiency[Units="SEER" or Units="SEER2"]/Value
double Btu/Wh > 0 Yes Rated cooling efficiency [171] CoolingCapacity
double Btu/hr >= 0 No autosized Cooling output capacity SensibleHeatFraction
double frac 0 - 1 No Sensible heat fraction extension/FanPowerWattsPerCFM
double W/cfm >= 0 No See [172] Blower fan efficiency at maximum fan speed extension/AirflowDefectRatio
double frac -0.9 - 9 No 0.0 Deviation between design/installed airflows [173] extension/ChargeDefectRatio
double frac -0.9 - 9 No 0.0 Deviation between design/installed charges [174]
[170] If provided, HVACDistribution type must be AirDistribution (type: “regular velocity”) or DSE.
[171] 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.
[172] FanPowerWattsPerCFM defaults to 0.07 W/cfm for ductless systems and 0.18 W/cfm for ducted systems.
[173] AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect. A non-zero airflow defect should typically only be applied for systems attached to ducts. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information.
[174] 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 pre-charged on site. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information.
Note
Mini-splits do not have a CompressorType
input because they are assumed to be inverter driven (variable speed).
Chiller¶
If a chiller is specified, additional information is entered in CoolingSystem
.
Element Type Units Constraints Required Default Notes IsSharedSystem
boolean true Yes Whether it serves multiple dwelling units DistributionSystem
idref See [175] Yes ID of attached distribution system NumberofUnitsServed
integer > 1 Yes Number of dwelling units served CoolingCapacity
double Btu/hr >= 0 Yes Total cooling output capacity AnnualCoolingEfficiency[Units="kW/ton"]/Value
double kW/ton > 0 Yes Rated efficiency extension/SharedLoopWatts
double W >= 0 Yes Pumping and fan power serving the system extension/FanCoilWatts
double W >= 0 See [176] Fan coil power
[175] HVACDistribution type must be HydronicDistribution (type: “radiator”, “baseboard”, “radiant floor”, “radiant ceiling”, or “water loop”) or AirDistribution (type: “fan coil”). If the chiller has “water loop” distribution, a Water-Loop-to-Air Heat Pump must also be specified.
[176] FanCoilWatts only required if chiller connected to fan coil.
Note
Chillers are modeled as central air conditioners with a SEER equivalent using the equation from ANSI/RESNET/ICC 301-2019.
Cooling Tower¶
If a cooling tower is specified, additional information is entered in CoolingSystem
.
Element Type Units Constraints Required Default Notes IsSharedSystem
boolean true Yes Whether it serves multiple dwelling units DistributionSystem
idref See [177] Yes ID of attached distribution system NumberofUnitsServed
integer > 1 Yes Number of dwelling units served extension/SharedLoopWatts
double W >= 0 Yes Pumping and fan power serving the system
[177] HVACDistribution type must be HydronicDistribution (type: “water loop”). A Water-Loop-to-Air Heat Pump must also be specified.
Note
Cooling towers w/ water loop heat pumps are modeled as central air conditioners with a SEER equivalent using the equation from ANSI/RESNET/ICC 301-2019.
HPXML Heat Pumps¶
Each heat pump is entered as an /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatPump
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier HeatPumpType
string See [178] Yes Type of heat pump HeatPumpFuel
string See [179] Yes Fuel type BackupType
string See [180] No <none> Type of backup heating
[178] HeatPumpType choices are “air-to-air”, “mini-split”, “ground-to-air”, “water-loop-to-air”, “packaged terminal heat pump”, or “room air conditioner with reverse cycle”.
[179] HeatPumpFuel only choice is “electricity”.
[180] BackupType choices are “integrated” or “separate”. 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).
If a backup type of “integrated” is provided, additional information is entered in HeatPump
.
Element Type Units Constraints Required Default Notes BackupSystemFuel
string See [181] 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 Integrated backup heating output capacity BackupHeatingSwitchoverTemperature
orBackupHeatingLockoutTemperature
double F No See [182] Integrated backup heating switchover/lockout temperature [183]
[181] 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”.
[182] BackupHeatingLockoutTemperature defaults to 40 deg-F if neither BackupHeatingSwitchoverTemperature nor BackupHeatingLockoutTemperature are provided.
[183] Provide BackupHeatingSwitchoverTemperature for a situation where there is a discrete outdoor temperature when the heat pump stops operating and the backup heating system starts operating. Alternatively, provide BackupHeatingLockoutTemperature for a situation where the backup heating is disabled above a certain temperature in order to prevent backup heating operation during, e.g., a thermostat heating setback recovery event. If neither provided, the backup heating system will operate as needed for hours when the heat pump has insufficient capacity.
If a backup type of “separate” is provided, additional information is entered in HeatPump
.
Element Type Units Constraints Required Default Notes BackupSystem
idref See [184] Yes ID of separate backup heating system BackupHeatingSwitchoverTemperature
double F No <none> Separate backup heating system switchover temperature [185]
[184] BackupSystem must reference a HeatingSystem
.
[185] Provide BackupHeatingSwitchoverTemperature for a situation where there is a discrete outdoor temperature when the heat pump stops operating and the backup heating system starts operating. If not provided, the backup heating system will operate as needed for hours when the heat pump has insufficient capacity. 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.
Air-to-Air Heat Pump¶
If an air-to-air heat pump is specified, additional information is entered in HeatPump
.
Element Type Units Constraints Required Default Notes DistributionSystem
idref See [186] Yes ID of attached distribution system CompressorType
string See [187] No See [188] Type of compressor HeatingCapacity
double Btu/hr >= 0 No autosized 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 Cooling output capacity CoolingSensibleHeatFraction
double frac 0 - 1 No Sensible heat fraction FractionHeatLoadServed
double frac 0 - 1 [189] Yes Fraction of heating load served FractionCoolLoadServed
double frac 0 - 1 [190] Yes Fraction of cooling load served AnnualCoolingEfficiency[Units="SEER" or Units="SEER2"]/Value
double Btu/Wh > 0 Yes Rated cooling efficiency [191] AnnualHeatingEfficiency[Units="HSPF" or Units="HSPF2"]/Value
double Btu/Wh > 0 Yes Rated heating efficiency [192] extension/FanPowerWattsPerCFM
double W/cfm >= 0 No See [193] Blower fan efficiency at maximum fan speed extension/AirflowDefectRatio
double frac -0.9 - 9 No 0.0 Deviation between design/installed airflows [194] extension/ChargeDefectRatio
double frac -0.9 - 9 No 0.0 Deviation between design/installed charges [195]
[186] HVACDistribution type must be AirDistribution (type: “regular velocity”) or DSE.
[187] CompressorType choices are “single stage”, “two stage”, or “variable speed”.
[188] If CompressorType not provided, defaults to “single stage” if SEER <= 15, else “two stage” if SEER <= 21, else “variable speed”.
[189] The sum of all FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.
[190] The sum of all FractionCoolLoadServed
(across all HVAC systems) must be less than or equal to 1.
[191] 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).
[192] 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).
[193] If FanPowerWattsPerCFM not provided, defaulted to 0.5 W/cfm if HSPF <= 8.75, else 0.375 W/cfm.
[194] AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information.
[195] 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 pre-charged on site. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information.
Mini-Split Heat Pump¶
If a mini-split heat pump is specified, additional information is entered in HeatPump
.
Element Type Units Constraints Required Default Notes DistributionSystem
idref See [196] No ID of attached distribution system, if present HeatingCapacity
double Btu/hr >= 0 No autosized 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 Cooling output capacity CoolingSensibleHeatFraction
double frac 0 - 1 No Sensible heat fraction FractionHeatLoadServed
double frac 0 - 1 [197] Yes Fraction of heating load served FractionCoolLoadServed
double frac 0 - 1 [198] Yes Fraction of cooling load served AnnualCoolingEfficiency[Units="SEER" or Units="SEER2"]/Value
double Btu/Wh > 0 Yes Rated cooling efficiency [199] AnnualHeatingEfficiency[Units="HSPF" or Units="HSPF2"]/Value
double Btu/Wh > 0 Yes Rated heating efficiency [200] extension/FanPowerWattsPerCFM
double W/cfm >= 0 No See [201] Blower fan efficiency at maximum fan speed extension/AirflowDefectRatio
double frac -0.9 - 9 No 0.0 Deviation between design/installed airflows [202] extension/ChargeDefectRatio
double frac -0.9 - 9 No 0.0 Deviation between design/installed charges [203]
[196] If provided, HVACDistribution type must be AirDistribution (type: “regular velocity”) or DSE.
[197] The sum of all FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.
[198] The sum of all FractionCoolLoadServed
(across all HVAC systems) must be less than or equal to 1.
[199] 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.
[200] 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.
[201] FanPowerWattsPerCFM defaults to 0.07 W/cfm for ductless systems and 0.18 W/cfm for ducted systems.
[202] AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect. A non-zero airflow defect should typically only be applied for systems attached to ducts. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information.
[203] 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 pre-charged on site. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information.
Note
Mini-splits do not have a CompressorType
input because they are assumed to be inverter driven (variable speed).
Packaged Terminal Heat Pump¶
If a packaged terminal heat pump is specified, additional information is entered in HeatPump
.
Element Type Units Constraints Required Default Notes HeatingCapacity
double Btu/hr >= 0 No autosized Heating output capacity (excluding any backup heating) CoolingCapacity
double Btu/hr >= 0 No autosized Cooling output capacity CoolingSensibleHeatFraction
double frac 0 - 1 No Sensible heat fraction FractionHeatLoadServed
double frac 0 - 1 [204] Yes Fraction of heating load served FractionCoolLoadServed
double frac 0 - 1 [205] 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 Btu/Wh > 0 Yes Rated heating efficiency
[204] The sum of all FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.
[205] The sum of all FractionCoolLoadServed
(across all HVAC systems) must be less than or equal to 1.
Room Air Conditioner w/ Reverse Cycle¶
If a room air conditioner with reverse cycle is specified, additional information is entered in HeatPump
.
Element Type Units Constraints Required Default Notes HeatingCapacity
double Btu/hr >= 0 No autosized Heating output capacity (excluding any backup heating) CoolingCapacity
double Btu/hr >= 0 No autosized Cooling output capacity CoolingSensibleHeatFraction
double frac 0 - 1 No Sensible heat fraction FractionHeatLoadServed
double frac 0 - 1 [206] Yes Fraction of heating load served FractionCoolLoadServed
double frac 0 - 1 [207] 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 Btu/Wh > 0 Yes Rated heating efficiency
[206] The sum of all FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.
[207] The sum of all FractionCoolLoadServed
(across all HVAC systems) must be less than or equal to 1.
Ground-to-Air Heat Pump¶
If a ground-to-air heat pump is specified, additional information is entered in HeatPump
.
Element Type Units Constraints Required Default Notes IsSharedSystem
boolean No false Whether it has a shared hydronic circulation loop [208] DistributionSystem
idref See [209] Yes ID of attached distribution system HeatingCapacity
double Btu/hr >= 0 No autosized Heating output capacity (excluding any backup heating) CoolingCapacity
double Btu/hr >= 0 No autosized Cooling output capacity CoolingSensibleHeatFraction
double frac 0 - 1 No Sensible heat fraction FractionHeatLoadServed
double frac 0 - 1 [210] Yes Fraction of heating load served FractionCoolLoadServed
double frac 0 - 1 [211] 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 [212] Number of dwelling units served extension/PumpPowerWattsPerTon
double W/ton >= 0 No See [213] Pump power [214] extension/SharedLoopWatts
double W >= 0 See [215] Shared pump power [216] extension/FanPowerWattsPerCFM
double W/cfm >= 0 No See [217] Blower fan efficiency at maximum fan speed extension/AirflowDefectRatio
double frac -0.9 - 9 No 0.0 Deviation between design/installed airflows [218] extension/ChargeDefectRatio
double frac -0.9 - 9 No 0.0 Deviation between design/installed charges [219]
[208] IsSharedSystem should be true if the SFA/MF building has multiple ground source heat pumps connected to a shared hydronic circulation loop.
[209] HVACDistribution type must be AirDistribution (type: “regular velocity”) or DSE.
[210] The sum of all FractionHeatLoadServed
(across all HVAC systems) must be less than or equal to 1.
[211] The sum of all FractionCoolLoadServed
(across all HVAC systems) must be less than or equal to 1.
[212] NumberofUnitsServed only required if IsSharedSystem is true, in which case it must be > 1.
[213] If PumpPowerWattsPerTon not provided, defaults to 30 W/ton per ANSI/RESNET/ICC 301-2019 for a closed loop system.
[214] 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.
[215] SharedLoopWatts only required if IsSharedSystem is true.
[216] Shared loop pump power attributed to the dwelling unit is calculated as SharedLoopWatts / NumberofUnitsServed.
[217] If FanPowerWattsPerCFM not provided, defaulted to 0.5 W/cfm if COP <= 8.75/3.2, else 0.375 W/cfm.
[218] AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information.
[219] 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 pre-charged on site. See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information.
Water-Loop-to-Air Heat Pump¶
If a water-loop-to-air heat pump is specified, additional information is entered in HeatPump
.
Element Type Units Constraints Required Default Notes DistributionSystem
idref See [220] Yes ID of attached distribution system HeatingCapacity
double Btu/hr > 0 No autosized Heating output capacity CoolingCapacity
double Btu/hr > 0 See [221] Cooling output capacity AnnualCoolingEfficiency[Units="EER"]/Value
double Btu/Wh > 0 See [222] Rated cooling efficiency AnnualHeatingEfficiency[Units="COP"]/Value
double W/W > 0 See [223] Rated heating efficiency
[220] HVACDistribution type must be AirDistribution (type: “regular velocity”) or DSE.
[221] CoolingCapacity required if there is a shared chiller or cooling tower with water loop distribution.
[222] AnnualCoolingEfficiency required if there is a shared chiller or cooling tower with water loop distribution.
[223] 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) and/or one shared cooling system (i.e., Chiller or Cooling Tower) specified with water loop distribution.
HPXML HVAC Control¶
If any HVAC systems are specified, a single thermostat is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACControl
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier HeatingSeason
element No See [224] Heating season CoolingSeason
element No See [225] Cooling season extension/CeilingFanSetpointTempCoolingSeasonOffset
double F >= 0 No 0 Cooling setpoint temperature offset [226]
[224] If HeatingSeason not provided, defaults to year-round.
[225] If CoolingSeason not provided, defaults to year-round.
[226] CeilingFanSetpointTempCoolingSeasonOffset should only be used if there are sufficient ceiling fans present to warrant a reduced cooling setpoint.
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
Thermostat setpoints are additionally entered using either simple inputs or hourly inputs. Alternatively, setpoints can be defined using 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 [227] 68 Heating setpoint temperature SetpointTempCoolingSeason
double F No [228] 78 Cooling setpoint temperature
[227] SetpointTempHeatingSeason only used if there is heating equipment.
[228] 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 [229] extension/SetbackStartHourHeating
integer 0 - 23 No 23 (11pm) Daily setback start hour
[229] 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 [230] extension/SetupStartHourCooling
integer 0 - 23 No 9 (9am) Daily setup start hour
[230] 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 [231] 24 comma-separated weekday heating setpoints extension/WeekendSetpointTempsHeatingSeason
array F No 24 comma-separated weekend heating setpoints extension/WeekdaySetpointTempsCoolingSeason
array F No [232] 24 comma-separated weekday cooling setpoints extension/WeekendSetpointTempsCoolingSeason
array F No 24 comma-separated weekend cooling setpoints
[231] WeekdaySetpointTempsHeatingSeason and WeekendSetpointTempsHeatingSeason only used if there is heating equipment.
[232] WeekdaySetpointTempsCoolingSeason and WeekendSetpointTempsCoolingSeason only used if there is cooling equipment.
HPXML HVAC Distribution¶
Each separate HVAC distribution system is entered as a /HPXML/Building/BuildingDetails/Systems/HVAC/HVACDistribution
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier DistributionSystemType
element 1 [233] Yes Type of distribution system ConditionedFloorAreaServed
double ft2 > 0 See [234] Conditioned floor area served
[233] DistributionSystemType child element choices are AirDistribution
,HydronicDistribution
, orOther=DSE
.
[234] ConditionedFloorAreaServed required only when DistributionSystemType is AirDistribution and duct surface area is defaulted (i.e., AirDistribution/Ducts
are present withoutDuctSurfaceArea
child elements).
Note
There should 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 DistributionSystemType is allowed for which HVAC system. Also note that some HVAC systems (e.g., room air conditioners) are not allowed to be attached to a distribution system.
Air Distribution¶
To define an air distribution system, additional information is entered in HVACDistribution/DistributionSystemType/AirDistribution
.
Element Type Units Constraints Required Default Notes AirDistributionType
string See [235] Yes Type of air distribution DuctLeakageMeasurement[DuctType="supply"]
element 1 See [236] Supply duct leakage value DuctLeakageMeasurement[DuctType="return"]
element 1 See [237] Return duct leakage value Ducts
element >= 0 No Supply/return ducts [238] NumberofReturnRegisters
integer >= 0 No See [239] Number of return registers
[235] 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.).
[236] Supply duct leakage required if AirDistributionType is “regular velocity” or “gravity” and optional if AirDistributionType is “fan coil”.
[237] Return duct leakage required if AirDistributionType is “regular velocity” or “gravity” and optional if AirDistributionType is “fan coil”.
[238] Provide a Ducts element for each supply duct and each return duct.
[239] 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.
Additional information is entered in each DuctLeakageMeasurement
.
Element Type Units Constraints Required Default Notes DuctLeakage/Units
string See [240] Yes Duct leakage units DuctLeakage/Value
double >= 0 [241] Yes Duct leakage value [242] DuctLeakage/TotalOrToOutside
string See [243] Yes Type of duct leakage (outside conditioned space vs total)
[240] Units choices are “CFM25”, “CFM50”, or “Percent”.
[241] Value also must be < 1 if Units is Percent.
[242] If the HVAC system has no return ducts (e.g., a ducted evaporative cooler), use zero for the Value.
[243] 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
double F-ft2-hr/Btu >= 0 Yes R-value of duct insulation [244] DuctLocation
string See [245] No See [246] Duct location FractionDuctArea
and/orDuctSurfaceArea
double frac or ft2 0-1 [247] or >= 0 See [248] See [249] Duct fraction/surface area in location extension/DuctSurfaceAreaMultiplier
double >= 0 No 1.0 Duct surface area multiplier
[244] DuctInsulationRValue should not include air films (i.e., use 0 for an uninsulated duct).
[245] DuctLocation choices are “living 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”, or “other non-freezing space”. See HPXML Locations for descriptions.
[246] 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 “living space”. If NumberofConditionedFloorsAboveGrade > 1, secondary ducts will be located in “living space”.
[247] The sum of all [DuctType="supply"]/FractionDuctArea
and[DuctType="return"]/FractionDuctArea
must each equal to 1.
[248] FractionDuctArea and/or DuctSurfaceArea are required if DuctLocation is provided.
[249] 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¶
To define a hydronic distribution system, additional information is entered in HVACDistribution/DistributionSystemType/HydronicDistribution
.
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. Also note that when specifying a DSE system, its effect is reflected in the Workflow Outputs but is not reflected in the raw EnergyPlus simulation outputs.
To define a DSE system, additional information is entered in HVACDistribution
.
Element Type Units Constraints Required Default Notes AnnualHeatingDistributionSystemEfficiency
double frac 0 - 1 Yes Seasonal distribution system efficiency for heating AnnualCoolingDistributionSystemEfficiency
double frac 0 - 1 Yes Seasonal distribution system efficiency for cooling DSE values can be calculated from ASHRAE Standard 152.
HPXML Ventilation Fan¶
Each ventilation fan system is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier UsedForWholeBuildingVentilation
orUsedForLocalVentilation
orUsedForSeasonalCoolingLoadReduction
orUsedForGarageVentilation
boolean See [251] See [252] Ventilation fan use case
[251] One (and only one) of the UsedFor...
elements must have a value of true. If UsedForWholeBuildingVentilation is true, see Whole Ventilation Fan. If UsedForLocalVentilation is true, see Local Ventilation Fan. If UsedForSeasonalCoolingLoadReduction is true, see Whole House Fan. If UsedForGarageVentilation is true, garage ventilation is currently ignored.
[252] Only the UsedFor...
element that is true is required.
Whole Ventilation Fan¶
Each mechanical ventilation system that provides ventilation to the whole dwelling unit is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan[UsedForWholeBuildingVentilation=true]
.
If not entered, the simulation will not include mechanical ventilation.
Element Type Units Constraints Required Default Notes IsSharedSystem
boolean See [253] No false Whether it serves multiple dwelling units FanType
string See [254] Yes Type of ventilation system RatedFlowRate
orTestedFlowRate
orCalculatedFlowRate
orDeliveredVentilation
double cfm >= 0 No See [255] Flow rate [256] HoursInOperation
double hrs/day 0 - 24 See [257] See [258] Hours per day of operation FanPower
double W >= 0 No See [259] Fan power
[253] For central fan integrated supply systems, IsSharedSystem must be false.
[254] FanType choices are “energy recovery ventilator”, “heat recovery ventilator”, “exhaust only”, “supply only”, “balanced”, or “central fan integrated supply”.
[255] If flow rate not provided, defaults to the required mechanical ventilation rate per ASHRAE 62.2-2019, including adjustments for A) infiltration credit, B) balanced vs imbalanced systems, and C) adiabatic surfaces for SFA/MF buildings.
[256] For a central fan integrated supply system, the flow rate should equal the amount of outdoor air provided to the distribution system.
[257] HoursInOperation is optional unless the VentilationFan refers to the supplemental fan of a CFIS system, in which case it is not allowed.
[258] If HoursInOperation not provided, defaults to 24 (i.e., running continuously) for all system types other than central fan integrated supply (CFIS), and 8.0 (i.e., running intermittently) for CFIS systems. For a CFIS system, 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). For a CFIS system with a supplemental fan, the supplemental fan’s runtime is automatically calculated for each hour (based on the air handler runtime) to maintain the hourly target ventilation rate.
[259] If FanPower not provided, defaults based on ANSI/RESNET/ICC 301-2019:
- “energy recovery ventilator”, “heat recovery ventilator”, or shared system: 1.0 W/cfm
- “balanced”: 0.7 W/cfm
- “central fan integrated supply”: 0.5 W/cfm
- “exhaust only” or “supply only”: 0.35 W/cfm
Exhaust/Supply Only
If a supply only or exhaust only system is specified, no additional information is entered.
Balanced
If a balanced system is specified, no additional information is entered.
Heat Recovery Ventilator
If a heat recovery ventilator system is specified, additional information is entered in VentilationFan
.
Element Type Units Constraints Required Default Notes SensibleRecoveryEfficiency
orAdjustedSensibleRecoveryEfficiency
double frac 0 - 1 Yes (Adjusted) Sensible recovery efficiency
Energy Recovery Ventilator
If an energy recovery ventilator system is specified, additional information is entered in VentilationFan
.
Element Type Units Constraints Required Default Notes TotalRecoveryEfficiency
orAdjustedTotalRecoveryEfficiency
double frac 0 - 1 Yes (Adjusted) Total recovery efficiency SensibleRecoveryEfficiency
orAdjustedSensibleRecoveryEfficiency
double frac 0 - 1 Yes (Adjusted) Sensible recovery efficiency
Central Fan Integrated Supply
If a central fan integrated supply (CFIS) system is specified, additional information is entered in VentilationFan
.
Element Type Units Constraints Required Default Notes CFISControls/AdditionalRuntimeOperatingMode
string See [260] No air handler fan How additional ventilation is provided (beyond when the HVAC system is running) CFISControls/SupplementalFan
idref See [261] See [262] The supplemental fan providing additional ventilation AttachedToHVACDistributionSystem
idref See [263] Yes ID of attached distribution system extension/VentilationOnlyModeAirflowFraction
double 0 - 1 No 1.0 Blower airflow rate fraction during ventilation only mode [264]
[260] AdditionalRuntimeOperatingMode choices are “air handler fan” or “supplemental fan”.
[261] SupplementalFan must reference another VentilationFan
where UsedForWholeBuildingVentilation=true, IsSharedSystem=false, and FanType=”exhaust only” or “supply only”.
[262] SupplementalFan only required if AdditionalRuntimeOperatingMode is “supplemental fan”.
[263] HVACDistribution type cannot be HydronicDistribution.
[264] 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.
Shared System
If the specified system is a shared system (i.e., serving multiple dwelling units), additional information is entered in VentilationFan
.
Element Type Units Constraints Required Default Notes FractionRecirculation
double frac 0 - 1 Yes Fraction of supply air that is recirculated [265] extension/InUnitFlowRate
double cfm >= 0 [266] Yes Flow rate delivered to the dwelling unit extension/PreHeating
element 0 - 1 No <none> Supply air preconditioned by heating equipment? [267] extension/PreCooling
element 0 - 1 No <none> Supply air preconditioned by cooling equipment? [268]
[265] 1-FractionRecirculation is assumed to be the fraction of supply air that is provided from outside. The value must be 0 for exhaust only systems.
[266] InUnitFlowRate must also be < (RatedFlowRate or TestedFlowRate or CalculatedFlowRate or DeliveredVentilation).
[267] PreHeating not allowed for exhaust only systems.
[268] PreCooling not allowed for exhaust only systems.
If pre-heating is specified, additional information is entered in extension/PreHeating
.
Element Type Units Constraints Required Default Notes Fuel
string See [269] Yes Pre-heating equipment fuel type AnnualHeatingEfficiency[Units="COP"]/Value
double W/W > 0 Yes Pre-heating equipment annual COP FractionVentilationHeatLoadServed
double frac 0 - 1 Yes Fraction of ventilation heating load served by pre-heating equipment
[269] Fuel 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”.
If pre-cooling is specified, additional information is entered in extension/PreCooling
.
Element Type Units Constraints Required Default Notes Fuel
string See [270] Yes Pre-cooling equipment fuel type AnnualCoolingEfficiency[Units="COP"]/Value
double W/W > 0 Yes Pre-cooling equipment annual COP FractionVentilationCoolLoadServed
double frac 0 - 1 Yes Fraction of ventilation cooling load served by pre-cooling equipment
[270] Fuel only choice is “electricity”.
Local Ventilation Fan¶
Each kitchen range fan or bathroom fan that provides local ventilation is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan[UsedForLocalVentilation=true]
.
If not entered, the simulation will not include kitchen/bathroom fans.
Element Type Units Constraints Required Default Notes Quantity
integer >= 0 No See [271] Number of identical fans RatedFlowRate
orTestedFlowRate
orCalculatedFlowRate
orDeliveredVentilation
double cfm >= 0 No See [272] Flow rate to outside [273] HoursInOperation
double hrs/day 0 - 24 No See [274] Hours per day of operation FanLocation
string See [275] Yes Location of the fan FanPower
double W >= 0 No See [276] Fan power extension/StartHour
integer 0 - 23 No See [277] Daily start hour of operation
[271] If Quantity not provided, defaults to 1 for kitchen fans and NumberofBathrooms for bath fans based on the 2010 BAHSP.
[272] If flow rate not provided, defaults to 100 cfm for kitchen fans and 50 cfm for bath fans based on the 2010 BAHSP.
[273] If the kitchen range fan is a recirculating fan, the flow rate should be described as zero.
[274] If HoursInOperation not provided, defaults to 1 based on the 2010 BAHSP.
[275] FanLocation choices are “kitchen” or “bath”.
[276] If FanPower not provided, defaults to 0.3 W/cfm based on the 2010 BAHSP.
[277] If StartHour not provided, defaults to 18 (6pm) for kitchen fans and 7 (7am) for bath fans based on the 2010 BAHSP.
Whole House Fan¶
Each whole house fan that provides cooling load reduction is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan[UsedForSeasonalCoolingLoadReduction=true]
.
If not entered, the simulation will not include whole house fans.
Note
The whole house fan is assumed to operate during hours of favorable outdoor conditions and will take priority over operable windows (natural ventilation).
HPXML Water Heating Systems¶
Each water heater is entered as a /HPXML/Building/BuildingDetails/Systems/WaterHeating/WaterHeatingSystem
.
If not entered, the simulation will not include water heating.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier IsSharedSystem
boolean No false Whether it serves multiple dwelling units or shared laundry room WaterHeaterType
string See [279] Yes Type of water heater Location
string See [280] No See [281] Water heater location FractionDHWLoadServed
double frac 0 - 1 [282] Yes Fraction of hot water load served [283] HotWaterTemperature
double F > 0 No 125 Water heater setpoint [284] UsesDesuperheater
boolean No false Presence of desuperheater? NumberofUnitsServed
integer > 0 See [285] Number of dwelling units served directly or indirectly
[279] WaterHeaterType choices are “storage water heater”, “instantaneous water heater”, “heat pump water heater”, “space-heating boiler with storage tank”, or “space-heating boiler with tankless coil”.
[280] Location choices are “living 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.
[281] If Location not provided, defaults to the first present space type:
- IECC zones 1-3, excluding 3A: “garage”, “living space”
- IECC zones 3A, 4-8, unknown: “basement - conditioned”, “basement - unconditioned”, “living space”
[282] The sum of all FractionDHWLoadServed
(across all WaterHeatingSystems) must equal to 1.
[283] 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).
[284] The water heater setpoint can alternatively be defined using Detailed Schedule Inputs.
[285] NumberofUnitsServed only required if IsSharedSystem is true, in which case it must be > 1.
Conventional Storage¶
If a conventional storage water heater is specified, additional information is entered in WaterHeatingSystem
.
Element Type Units Constraints Required Default Notes FuelType
string See [286] Yes Fuel type TankVolume
double gal > 0 No See [287] Nominal tank volume HeatingCapacity
double Btu/hr > 0 No See [288] Heating capacity UniformEnergyFactor
orEnergyFactor
double frac < 1 Yes EnergyGuide label rated efficiency UsageBin
orFirstHourRating
string or double str or gal/hr See [289] or > 0 No See [290] EnergyGuide label usage bin/first hour rating RecoveryEfficiency
double frac 0 - 1 [291] No See [292] Recovery efficiency WaterHeaterInsulation/Jacket/JacketRValue
double F-ft2-hr/Btu >= 0 No 0 R-value of additional tank insulation wrap extension/TankModelType
string See [293] No mixed Tank model type
[286] 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”.
[287] If TankVolume not provided, defaults based on Table 8 in the 2014 BAHSP.
[288] If HeatingCapacity not provided, defaults based on Table 8 in the 2014 BAHSP.
[289] UsageBin choices are “very small”, “low”, “medium”, or “high”.
[290] 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.
[291] RecoveryEfficiency must also be greater than the EnergyFactor (or UniformEnergyFactor).
[292] 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
[293] TankModelType choices are “mixed” or “stratified”.
Tankless¶
If an instantaneous tankless water heater is specified, additional information is entered in WaterHeatingSystem
.
Element Type Units Constraints Required Default Notes FuelType
string See [294] Yes Fuel type PerformanceAdjustment
double frac No See [295] Multiplier on efficiency, typically to account for cycling UniformEnergyFactor
orEnergyFactor
double frac < 1 Yes EnergyGuide label rated efficiency
[294] 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”.
[295] If PerformanceAdjustment not provided, defaults to 0.94 (UEF) or 0.92 (EF) based on ANSI/RESNET/ICC 301-2019.
Heat Pump¶
If a heat pump water heater is specified, additional information is entered in WaterHeatingSystem
.
Element Type Units Constraints Required Default Notes FuelType
string See [296] Yes Fuel type TankVolume
double gal > 0 Yes Nominal tank volume UniformEnergyFactor
orEnergyFactor
double frac > 1, <= 5 Yes EnergyGuide label rated efficiency UsageBin
orFirstHourRating
string or double str or gal/hr See [297] or > 0 No See [298] 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 extension/OperatingMode
string See [299] No standard Operating mode [300]
[296] FuelType only choice is “electricity”.
[297] UsageBin choices are “very small”, “low”, “medium”, or “high”.
[298] 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.
[299] OperatingMode choices are “standard” or “heat pump only”.
[300] The heat pump water heater operating mode can alternatively be defined using Detailed Schedule Inputs.
Combi Boiler w/ Storage¶
If a combination boiler w/ storage tank (sometimes referred to as an indirect water heater) is specified, additional information is entered in WaterHeatingSystem
.
Element Type Units Constraints Required Default Notes RelatedHVACSystem
idref See [301] Yes ID of boiler TankVolume
double gal > 0 Yes Nominal volume of the storage tank WaterHeaterInsulation/Jacket/JacketRValue
double F-ft2-hr/Btu >= 0 No 0 R-value of additional storage tank insulation wrap StandbyLoss[Units="F/hr"]/Value
double F/hr > 0 No See [302] Storage tank standby losses
[301] RelatedHVACSystem must reference a HeatingSystem
(Boiler).
[302] If StandbyLoss not provided, defaults based on a regression analysis of AHRI Directory of Certified Product Performance.
Combi Boiler w/ Tankless Coil¶
If a combination boiler w/ tankless coil is specified, additional information is entered in WaterHeatingSystem
.
Desuperheater¶
If the water heater uses a desuperheater, additional information is entered in WaterHeatingSystem
.
Element Type Units Constraints Required Default Notes RelatedHVACSystem
idref See [304] Yes ID of heat pump or air conditioner
[304] 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 is entered as a /HPXML/Building/BuildingDetails/Systems/WaterHeating/HotWaterDistribution
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier SystemType
element 1 [305] Yes Type of in-unit distribution system serving the dwelling unit PipeInsulation/PipeRValue
double F-ft2-hr/Btu >= 0 No 0.0 Pipe insulation R-value DrainWaterHeatRecovery
element 0 - 1 No <none> Presence of drain water heat recovery device extension/SharedRecirculation
element 0 - 1 [306] No <none> Presence of shared recirculation system serving multiple dwelling units
[305] SystemType child element choices are Standard
andRecirculation
.
[306] If SharedRecirculation is provided, SystemType must be Standard
. This is because a stacked recirculation system (i.e., shared recirculation loop plus an additional in-unit recirculation system) is more likely to indicate input errors than reflect an actual real-world scenario.
Note
In attached/multifamily buildings, only the hot water distribution system serving the dwelling unit should be defined. The hot water distribution associated with, e.g., a shared laundry room should not be defined.
Standard¶
If the in-unit distribution system is specified as standard, additional information is entered in SystemType/Standard
.
Element Type Units Constraints Required Default Notes PipingLength
double ft > 0 No See [307] Length of piping [308]
[307] 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 * BsmntwhereCFA = conditioned floor area [ft2],NCfl = number of conditioned floor levels 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.
[308] PipingLength is the length of hot water piping from the hot water heater (or from a shared recirculation loop serving multiple dwelling units) to the farthest hot water fixture, measured longitudinally from plans, assuming the hot water piping does not run diagonally, plus 10 feet of piping for each floor level, plus 5 feet of piping for unconditioned basements (if any).
Recirculation¶
If the in-unit distribution system is specified as recirculation, additional information is entered in SystemType/Recirculation
.
Element Type Units Constraints Required Default Notes ControlType
string See [309] Yes Recirculation control type RecirculationPipingLoopLength
double ft > 0 No See [310] Recirculation piping loop length [311] BranchPipingLength
double ft > 0 No 10 Branch piping length [312] PumpPower
double W >= 0 No 50 [313] Recirculation pump power
[309] ControlType choices are “manual demand control”, “presence sensor demand control”, “temperature”, “timer”, or “no control”.
[310] 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.0whereCFA = conditioned floor area [ft2],NCfl = number of conditioned floor levels 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.
[311] 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.
[312] 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.
[313] PumpPower default based on ANSI/RESNET/ICC 301-2019.
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 [316] Yes Specifies which facilities are connected EqualFlow
boolean Yes Specifies how the DHWR is configured [317] Efficiency
double frac 0 - 1 Yes Efficiency according to CSA 55.1
[316] 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.
[317] EqualFlow should be true if the DWHR supplies pre-heated water to both the fixture cold water piping and the hot water heater potable supply piping.
HPXML Water Fixtures¶
Each water fixture is entered as a /HPXML/Building/BuildingDetails/Systems/WaterHeating/WaterFixture
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier WaterFixtureType
string See [318] Yes Bathroom faucet or shower LowFlow
boolean Yes Whether the fixture is considered low-flow [319]
[318] WaterFixtureType choices are “shower head” or “faucet”. If the shower stall has multiple shower heads that operate simultaneously, combine them as a single entry.
[319] LowFlow should be true if the fixture’s flow rate (gpm) is <= 2.0. Where a shower stall has multiple shower heads that operate simultaneously, the sum of their flows must be <= 2.0.
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 [320] 24 comma-separated weekday fractions extension/WaterFixturesWeekendScheduleFractions
array No 24 comma-separated weekend fractions extension/WaterFixturesMonthlyScheduleMultipliers
array No See [321] 12 comma-separated monthly multipliers
[320] If WaterFixturesWeekdayScheduleFractions or WaterFixturesWeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Figures 9-11 of the 2010 BAHSP are used: “0.012, 0.006, 0.004, 0.005, 0.010, 0.034, 0.078, 0.087, 0.080, 0.067, 0.056, 0.047, 0.040, 0.035, 0.033, 0.031, 0.039, 0.051, 0.060, 0.060, 0.055, 0.048, 0.038, 0.026”.
[321] 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”.
HPXML Solar Thermal¶
A single solar hot water system can be entered as a /HPXML/Building/BuildingDetails/Systems/SolarThermal/SolarThermalSystem
.
If not entered, the simulation will not include solar hot water.
Solar hot water systems can be described with either simple or detailed inputs.
Simple Inputs¶
To define a simple solar hot water system, additional information is entered in SolarThermalSystem
.
Element Type Units Constraints Required Default Notes SolarFraction
double frac 0 - 1 Yes Solar fraction [323] ConnectedTo
idref See [324] No [325] <none> Connected water heater
[323] 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.
[324] ConnectedTo must reference a WaterHeatingSystem
. The referenced water heater cannot be a space-heating boiler nor attached to a desuperheater.
[325] If ConnectedTo not provided, solar fraction will apply to all water heaters in the building.
Detailed Inputs¶
To define a detailed solar hot water system, additional information is entered in SolarThermalSystem
.
Element Type Units Constraints Required Default Notes CollectorArea
double ft2 > 0 Yes Area CollectorLoopType
string See [326] Yes Loop type CollectorType
string See [327] Yes System type CollectorAzimuth
orCollectorOrientation
integer or string deg or direction 0 - 359 or See [328] 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 [329] CollectorRatedThermalLosses
double Btu/hr-ft2-R > 0 Yes Rated thermal losses [330] StorageVolume
double gal > 0 No See [331] Hot water storage volume ConnectedTo
idref See [332] Yes Connected water heater
[326] CollectorLoopType choices are “liquid indirect”, “liquid direct”, or “passive thermosyphon”.
[327] CollectorType choices are “single glazing black”, “double glazing black”, “evacuated tube”, or “integrated collector storage”.
[328] CollectorOrientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[329] CollectorRatedOpticalEfficiency is FRTA (y-intercept) from the Directory of SRCC OG-100 Certified Solar Collector Ratings.
[330] CollectorRatedThermalLosses is FRUL (slope) from the Directory of SRCC OG-100 Certified Solar Collector Ratings.
[331] If StorageVolume not provided, calculated as 1.5 gal/ft2 * CollectorArea.
[332] 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 [333] No roof Mounting location ModuleType
string See [334] No standard Type of module Tracking
string See [335] No fixed Type of tracking ArrayAzimuth
orArrayOrientation
integer or string deg or direction 0 - 359 or See [336] Yes Direction panels face (clockwise from North) ArrayTilt
double deg 0 - 90 Yes Tilt relative to horizontal MaxPowerOutput
double W >= 0 Yes Peak power InverterEfficiency
double frac 0 - 1 [337] No 0.96 Inverter efficiency SystemLossesFraction
orYearModulesManufactured
double or integer frac or # 0 - 1 or > 1600 No 0.14 System losses [338] extension/NumberofBedroomsServed
integer > 1 See [339] Number of bedrooms served
[333] Location choices are “ground” or “roof” mounted.
[334] ModuleType choices are “standard”, “premium”, or “thin film”.
[335] Tracking choices are “fixed”, “1-axis”, “1-axis backtracked”, or “2-axis”.
[336] ArrayOrientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, or “north”
[337] For homes with multiple PV arrays, all InverterEfficiency elements must have the same value.
[338] System losses due to soiling, shading, snow, mismatch, wiring, degradation, etc. If YearModulesManufactured provided but not SystemLossesFraction, system losses calculated as: SystemLossesFraction = 1.0 - (1.0 - 0.14) * (1.0 - (1.0 - 0.995^(CurrentYear - YearModulesManufactured))).
[339] NumberofBedroomsServed only required if IsSharedSystem is true, in which case it must be > NumberofBedrooms. 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.
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 Location
string See [340] No outside Location BatteryType
string See [341] Yes Battery type NominalCapacity[Units="kWh" or Units="Ah"]/Value
double kWh or Ah >= 0 No See [342] Nominal (total) capacity UsableCapacity[Units="kWh" or Units="Ah"]/Value
double kWh or Ah >= 0, < NominalCapacity No See [343] Usable capacity RatedPowerOutput
double W >= 0 No See [344] 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
[340] Location choices are “living space”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “crawlspace - conditioned”, “attic - vented”, “attic - unvented”, “garage”, or “outside”.
[341] BatteryType only choice is “Li-ion”.
[342] If NominalCapacity not provided, defaults to UsableCapacity / 0.9 if UsableCapacity provided, else (RatedPowerOutput / 1000) / 0.5 if RatedPowerOutput provided, else 10 kWh.
[343] If UsableCapacity not provided, defaults to 0.9 * NominalCapacity.
[344] If RatedPowerOutput not provided, defaults to 0.5 * NominalCapacity * 1000. 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 load and the battery is below its maximum capacity, while the battery will discharge if the building 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; the reported charging rate 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 [345] Yes Fuel type AnnualConsumptionkBtu
double kBtu/yr > 0 Yes Annual fuel consumed AnnualOutputkWh
double kWh/yr > 0 [346] Yes Annual electricity produced NumberofBedroomsServed
integer > 1 See [347] Number of bedrooms served
[345] 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”.
[346] AnnualOutputkWh must also be < AnnualConsumptionkBtu*3.412 (i.e., the generator must consume more energy than it produces).
[347] NumberofBedroomsServed only required if IsSharedSystem is true, in which case it must be > NumberofBedrooms. 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.
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 [348] Location
string See [349] No living space Location IntegratedModifiedEnergyFactor
orModifiedEnergyFactor
double ft3/kWh/cyc > 0 No See [350] Efficiency [351] AttachedToWaterHeatingSystem
orAttachedToHotWaterDistribution
idref See [352] See [353] 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 [354] 24 comma-separated weekday fractions extension/WeekendScheduleFractions
array No 24 comma-separated weekend fractions extension/MonthlyScheduleMultipliers
array No See [355] 12 comma-separated monthly multipliers
[348] For example, a clothes washer in a shared laundry room of a MF building.
[349] Location choices are “living 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.
[350] 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.
[351] 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.
[352] AttachedToWaterHeatingSystem must reference a WaterHeatingSystem
; AttachedToHotWaterDistribution must reference aHotWaterDistribution
.
[353] AttachedToWaterHeatingSystem (or AttachedToHotWaterDistribution) only required if IsSharedAppliance is true.
[354] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Figure 17 of the 2010 BAHSP 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.052, 0.050, 0.049, 0.049, 0.049, 0.049, 0.047, 0.032, 0.017”.
[355] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values from Figure 24 of the 2010 BAHSP are used: “1.011, 1.002, 1.022, 1.020, 1.022, 0.996, 0.999, 0.999, 0.996, 0.964, 0.959, 1.011”.
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 [356] Location
string See [357] No living space Location FuelType
string See [358] Yes Fuel type CombinedEnergyFactor
orEnergyFactor
double lb/kWh > 0 No See [359] Efficiency [360] Vented
boolean No true Whether dryer is vented VentedFlowRate
double cfm >= 0 No 100 [361] Exhaust flow rate during operation extension/UsageMultiplier
double >= 0 No 1.0 Multiplier on energy use extension/WeekdayScheduleFractions
array No See [362] 24 comma-separated weekday fractions extension/WeekendScheduleFractions
array No 24 comma-separated weekend fractions extension/MonthlyScheduleMultipliers
array No See [363] 12 comma-separated monthly multipliers
[356] For example, a clothes dryer in a shared laundry room of a MF building.
[357] Location choices are “living 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.
[358] 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”.
[359] If neither CombinedEnergyFactor nor EnergyFactor provided, the following default values representing a standard clothes dryer from 2006 will be used: CombinedEnergyFactor = 3.01.
[360] 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.
[361] VentedFlowRate default based on the 2010 BAHSP.
[362] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Figure 18 of the 2010 BAHSP 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.057, 0.061, 0.055, 0.054, 0.051, 0.051, 0.052, 0.054, 0.044, 0.024”.
[363] 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 [364] Location
string See [365] No living space Location RatedAnnualkWh
orEnergyFactor
double kWh/yr or # > 0 No See [366] EnergyGuide label consumption/efficiency [367] AttachedToWaterHeatingSystem
orAttachedToHotWaterDistribution
idref See [368] See [369] 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 [370] 24 comma-separated weekday fractions extension/WeekendScheduleFractions
array No 24 comma-separated weekend fractions extension/MonthlyScheduleMultipliers
array No See [371] 12 comma-separated monthly multipliers
[364] For example, a dishwasher in a shared mechanical room of a MF building.
[365] Location choices are “living 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.
[366] 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.
[367] 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.
[368] AttachedToWaterHeatingSystem must reference a WaterHeatingSystem
; AttachedToHotWaterDistribution must reference aHotWaterDistribution
.
[369] AttachedToWaterHeatingSystem (or AttachedToHotWaterDistribution) only required if IsSharedAppliance is true.
[370] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Figure 21 of the 2010 BAHSP 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.041, 0.046, 0.036, 0.038, 0.038, 0.049, 0.087, 0.111, 0.090, 0.067, 0.044, 0.031”.
[371] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values from Figure 24 of the 2010 BAHSP are used: “1.097, 1.097, 0.991, 0.987, 0.991, 0.890, 0.896, 0.896, 0.890, 1.085, 1.085, 1.097”.
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 [372] No See [373] Location RatedAnnualkWh
double kWh/yr > 0 No See [374] Annual consumption PrimaryIndicator
boolean See [375] Primary refrigerator? extension/UsageMultiplier
double >= 0 No 1.0 Multiplier on energy use extension/WeekdayScheduleFractions
array No See [376] 24 comma-separated weekday fractions extension/WeekendScheduleFractions
array No 24 comma-separated weekend fractions extension/MonthlyScheduleMultipliers
array No See [377] 12 comma-separated monthly multipliers
[372] Location choices are “living 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.
[373] If Location not provided and is the primary refrigerator, defaults to “living space”. If Location not provided and is a secondary refrigerator, defaults to the first present space type: “garage”, “basement - unconditioned”, “basement - conditioned”, or “living space”.
[374] 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.
[375] If multiple refrigerators are specified, there must be exactly one refrigerator described with PrimaryIndicator=true.
[376] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs 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”.
[377] 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 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 [378] No See [379] Location RatedAnnualkWh
double kWh/yr > 0 No 319.8 [380] Annual consumption extension/UsageMultiplier
double >= 0 No 1.0 Multiplier on energy use extension/WeekdayScheduleFractions
array No See [381] 24 comma-separated weekday fractions extension/WeekendScheduleFractions
array No 24 comma-separated weekend fractions extension/MonthlyScheduleMultipliers
array No See [382] 12 comma-separated monthly multipliers
[378] Location choices are “living 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.
[379] If Location not provided, defaults to “garage” if present, otherwise “basement - unconditioned” if present, otherwise “basement - conditioned” if present, otherwise “living space”.
[380] RatedAnnualkWh default based on the 2010 BAHSP.
[381] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs 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”.
[382] 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 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 [383] Yes Type of dehumidifier Location
string See [384] 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 [385] Yes Relative humidity setpoint FractionDehumidificationLoadServed
double frac 0 - 1 [386] Yes Fraction of dehumidification load served
[383] Type choices are “portable” or “whole-home”.
[384] Location only choice is “living space”.
[385] If multiple dehumidifiers are entered, they must all have the same setpoint or an error will be generated.
[386] 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 “living 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 [387] No living space Location FuelType
string See [388] 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 [389] 24 comma-separated weekday fractions extension/WeekendScheduleFractions
array No 24 comma-separated weekend fractions extension/MonthlyScheduleMultipliers
array No See [390] 12 comma-separated monthly multipliers
[387] Location choices are “living 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.
[388] 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”.
[389] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Figure 22 of the 2010 BAHSP are used: “0.007, 0.007, 0.004, 0.004, 0.007, 0.011, 0.025, 0.042, 0.046, 0.048, 0.042, 0.050, 0.057, 0.046, 0.057, 0.044, 0.092, 0.150, 0.117, 0.060, 0.035, 0.025, 0.016, 0.011”.
[390] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values from Figure 24 of the 2010 BAHSP are used: “1.097, 1.097, 0.991, 0.987, 0.991, 0.890, 0.896, 0.896, 0.890, 1.085, 1.085, 1.097”.
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¶
Nine /HPXML/Building/BuildingDetails/Lighting/LightingGroup
elements must be provided, each of which is the combination of:
LightingType
: ‘LightEmittingDiode’, ‘CompactFluorescent’, and ‘FluorescentTube’Location
: ‘interior’, ‘garage’, and ‘exterior’
Information is entered in each LightingGroup
.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier LightingType
element 1 [391] Yes Lighting type Location
string See [392] Yes See [393] FractionofUnitsInLocation
double frac 0 - 1 [394] Yes Fraction of light fixtures in the location with the specified lighting type
[391] LightingType child element choices are LightEmittingDiode
,CompactFluorescent
, orFluorescentTube
.
[392] Location choices are “interior”, “garage”, or “exterior”.
[393] Garage lighting is ignored if the building has no garage specified elsewhere.
[394] 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.
Additional information is entered in 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 [395] 24 comma-separated interior weekday fractions extension/InteriorWeekendScheduleFractions
array No 24 comma-separated interior weekend fractions extension/InteriorMonthlyScheduleMultipliers
array No 12 comma-separated interior monthly multipliers extension/GarageWeekdayScheduleFractions
array No See [396] 24 comma-separated garage weekday fractions extension/GarageWeekendScheduleFractions
array No 24 comma-separated garage weekend fractions extension/GarageMonthlyScheduleMultipliers
array No 12 comma-separated garage monthly multipliers extension/ExteriorWeekdayScheduleFractions
array No See [397] 24 comma-separated exterior weekday fractions extension/ExteriorWeekendScheduleFractions
array No 24 comma-separated exterior weekend fractions extension/ExteriorMonthlyScheduleMultipliers
array No 12 comma-separated exterior monthly multipliers extension/ExteriorHolidayLighting
element 0 - 1 No <none> Presence of additional holiday lighting?
[395] If interior schedule values not provided (and Detailed Schedule Inputs not used), they will be calculated using Lighting Calculation Option 2 (location-dependent lighting profile) of the 2010 BAHSP.
[396] If garage schedule values not provided (and Detailed Schedule Inputs not used), they will be defaulted using Appendix C Table 8 of the Title 24 2016 Res. ACM Manual.
[397] If exterior schedule values not provided (and Detailed Schedule Inputs not used), they will be defaulted using Appendix C Table 8 of the Title 24 2016 Res. ACM Manual.
If exterior holiday lighting is specified, additional information is entered in extension/ExteriorHolidayLighting
.
Element Type Units Constraints Required Default Notes Load[Units="kWh/day"]/Value
double kWh/day >= 0 No See [398] 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 [399] 24 comma-separated holiday weekday fractions WeekendScheduleFractions
array No 24 comma-separated holiday weekend fractions
[398] If Value not provided, defaults to 1.1 for single-family detached and 0.55 for others.
[399] 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”.
Interior, exterior, and garage lighting energy use is calculated per the Energy Rating Rated Home in ANSI/RESNET/ICC 301-2019.
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
double cfm/W > 0 No See [400] Efficiency at medium speed Quantity
integer > 0 No See [401] Number of similar ceiling fans extension/WeekdayScheduleFractions
array No See [402] 24 comma-separated weekday fractions extension/WeekendScheduleFractions
array No 24 comma-separated weekend fractions extension/MonthlyScheduleMultipliers
array No See [403] 12 comma-separated monthly multipliers
[400] If Efficiency not provided, defaults to 3000 / 42.6 based on ANSI/RESNET/ICC 301-2019.
[401] If Quantity not provided, defaults to NumberofBedrooms + 1 based on ANSI/RESNET/ICC 301-2019.
[402] If WeekdayScheduleFractions or WeekendScheduleFractions not provided (and Detailed Schedule Inputs not used), default values from Figure 23 of the 2010 BAHSP 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.057, 0.057, 0.057, 0.057, 0.057, 0.057”.
[403] 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 summer months when ceiling fans are operating. See HPXML HVAC Control for more information.
HPXML Pools & Hot Tubs¶
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/PoolPumps/PoolPump
.
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 [405] Yes Pool pump type Load[Units="kWh/year"]/Value
double kWh/yr >= 0 No See [406] Pool pump energy use extension/UsageMultiplier
double >= 0 No 1.0 Multiplier on pool pump energy use extension/WeekdayScheduleFractions
array No See [407] 24 comma-separated weekday fractions extension/WeekendScheduleFractions
array No 24 comma-separated weekend fractions extension/MonthlyScheduleMultipliers
array No See [408] 12 comma-separated monthly multipliers
[405] 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.
[406] 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 OccupancyCalculationType is “operational”, this value will be adjusted for the NumberofResidents.
[407] 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”.
[408] 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 [409] Yes Pool heater type Load[Units="kWh/year" or Units="therm/year"]/Value
double kWh/yr or therm/yr >= 0 No See [410] Pool heater energy use extension/UsageMultiplier
double >= 0 No 1.0 Multiplier on pool heater energy use extension/WeekdayScheduleFractions
array No See [411] 24 comma-separated weekday fractions extension/WeekendScheduleFractions
array No 24 comma-separated weekend fractions extension/MonthlyScheduleMultipliers
array No See [412] 12 comma-separated monthly multipliers
[409] Type choices are “none, “gas fired”, “electric resistance”, or “heat pump”. If “none” is entered, the simulation will not include a pool heater.
[410] If Value not provided, defaults as follows:
- gas fired: 3.0 / 0.014 * (0.5 + 0.25 * NumberofBedrooms / 3 + 0.25 * ConditionedFloorArea / 1920) (based on the 2010 BAHSP)
- electric resistance: 8.3 / 0.004 * (0.5 + 0.25 * NumberofBedrooms / 3 + 0.25 * ConditionedFloorArea / 1920) (based on the 2010 BAHSP)
- heat pump: (electric resistance) / 5.0 (based on an average COP of 5 from Energy Saver)
If OccupancyCalculationType is “operational”, this value will be adjusted for the NumberofResidents.
[411] 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”.
[412] 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 Hot Tubs¶
A single hot tub can be entered as a /HPXML/Building/BuildingDetails/HotTubs/HotTub
.
If not entered, the simulation will not include a hot tub.
Hot Tub Pump¶
If a hot tub is specified, a single hot tub pump can be entered as a HotTub/HotTubPumps/HotTubPump
.
If not entered, the simulation will not include a hot tub pump.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier Type
string See [414] Yes Hot tub pump type Load[Units="kWh/year"]/Value
double kWh/yr >= 0 No See [415] Hot tub pump energy use extension/UsageMultiplier
double >= 0 No 1.0 Multiplier on hot tub pump energy use extension/WeekdayScheduleFractions
array No See [416] 24 comma-separated weekday fractions extension/WeekendScheduleFractions
array No 24 comma-separated weekend fractions extension/MonthlyScheduleMultipliers
array No See [417] 12 comma-separated monthly multipliers
[414] 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 hot tub pump.
[415] 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 OccupancyCalculationType is “operational”, this value will be adjusted for the NumberofResidents.
[416] 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”.
[417] 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”.
Hot Tub Heater¶
If a hot tub is specified, a hot tub heater can be entered as a HotTub/Heater
.
If not entered, the simulation will not include a hot tub heater.
Element Type Units Constraints Required Default Notes SystemIdentifier
id Yes Unique identifier Type
string See [418] Yes Hot tub heater type Load[Units="kWh/year" or Units="therm/year"]/Value
double kWh/yr or therm/yr >= 0 No See [419] Hot tub heater energy use extension/UsageMultiplier
double >= 0 No 1.0 Multiplier on hot tub heater energy use extension/WeekdayScheduleFractions
array No See [420] 24 comma-separated weekday fractions extension/WeekendScheduleFractions
array No 24 comma-separated weekend fractions extension/MonthlyScheduleMultipliers
array No See [421] 12 comma-separated monthly multipliers
[418] Type choices are “none, “gas fired”, “electric resistance”, or “heat pump”. If “none” is entered, the simulation will not include a hot tub heater.
[419] 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 OccupancyCalculationType is “operational”, this value will be adjusted for the NumberofResidents.
[420] 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”.
[421] 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 [422] Yes Type of plug load Load[Units="kWh/year"]/Value
double kWh/yr >= 0 No See [423] Annual electricity consumption extension/FracSensible
double 0 - 1 No See [424] Fraction that is sensible heat gain to conditioned space [425] extension/FracLatent
double 0 - 1 No See [426] 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 [427] 24 comma-separated weekday fractions extension/WeekendScheduleFractions
array No See [428] 24 comma-separated weekend fractions extension/MonthlyScheduleMultipliers
array No See [429] 12 comma-separated monthly multipliers
[422] PlugLoadType choices are “other”, “TV other”, “well pump”, or “electric vehicle charging”.
[423] 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 OccupancyCalculationType is “operational”, this value will be adjusted for the NumberofResidents.
[424] If FracSensible not provided, defaults as:
- other: 0.855
- TV other: 1.0
- well pump: 0.0
- electric vehicle charging: 0.0
[425] 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.
[426] If FracLatent not provided, defaults as:
- other: 0.045
- TV other: 0.0
- well pump: 0.0
- electric vehicle charging: 0.0
[427] If WeekdayScheduleFractions not provided (and Detailed Schedule Inputs not used), defaults as:
- other: “0.035, 0.033, 0.032, 0.031, 0.032, 0.033, 0.037, 0.042, 0.043, 0.043, 0.043, 0.044, 0.045, 0.045, 0.044, 0.046, 0.048, 0.052, 0.053, 0.05, 0.047, 0.045, 0.04, 0.036” (based on Figure 23 of the 2010 BAHSP)
- TV other: “0.037, 0.018, 0.009, 0.007, 0.011, 0.018, 0.029, 0.040, 0.049, 0.058, 0.065, 0.072, 0.076, 0.086, 0.091, 0.102, 0.127, 0.156, 0.210, 0.294, 0.363, 0.344, 0.208, 0.090” (based on the American Time Use Survey)
- 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”
[428] If WeekdendScheduleFractions not provided (and Detailed Schedule Inputs not used), defaults as:
- other: “0.035, 0.033, 0.032, 0.031, 0.032, 0.033, 0.037, 0.042, 0.043, 0.043, 0.043, 0.044, 0.045, 0.045, 0.044, 0.046, 0.048, 0.052, 0.053, 0.05, 0.047, 0.045, 0.04, 0.036” (based on Figure 23 of the 2010 BAHSP)
- TV other: “0.044, 0.022, 0.012, 0.008, 0.011, 0.014, 0.024, 0.043, 0.071, 0.094, 0.112, 0.123, 0.132, 0.156, 0.178, 0.196, 0.206, 0.213, 0.251, 0.330, 0.388, 0.358, 0.226, 0.103” (based on the American Time Use Survey)
- 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”
[429] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), defaults as:
- other: “1.248, 1.257, 0.993, 0.989, 0.993, 0.827, 0.821, 0.821, 0.827, 0.99, 0.987, 1.248” (based on Figure 24 of the 2010 BAHSP)
- TV other: “1.137, 1.129, 0.961, 0.969, 0.961, 0.993, 0.996, 0.96, 0.993, 0.867, 0.86, 1.137” (based on the American Time Use Survey)
- well pump: “1.154, 1.161, 1.013, 1.010, 1.013, 0.888, 0.883, 0.883, 0.888, 0.978, 0.974, 1.154” (based on Figure 24 of the 2010 BAHSP)
- electric vehicle charging: “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 [430] Yes Type of fuel load Load[Units="therm/year"]/Value
double therm/yr >= 0 No See [431] Annual fuel consumption FuelType
string See [432] Yes Fuel type extension/FracSensible
double 0 - 1 No See [433] Fraction that is sensible heat gain to conditioned space [434] extension/FracLatent
double 0 - 1 No See [435] 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 [436] 24 comma-separated weekday fractions extension/WeekendScheduleFractions
array No 24 comma-separated weekend fractions extension/MonthlyScheduleMultipliers
array No See [437] 12 comma-separated monthly multipliers
[430] FuelLoadType choices are “grill”, “fireplace”, or “lighting”.
[431] 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 OccupancyCalculationType is “operational”, this value will be adjusted for the NumberofResidents.
[432] 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”.
[433] If FracSensible not provided, defaults to 0.5 for fireplace and 0.0 for all other types.
[434] 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.
[435] If FracLatent not provided, defaults to 0.1 for fireplace and 0.0 for all other types.
[436] 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”.
[437] If MonthlyScheduleMultipliers not provided (and Detailed Schedule Inputs not used), default values from Figure 24 of the 2010 BAHSP are used:
- grill: “1.097, 1.097, 0.991, 0.987, 0.991, 0.890, 0.896, 0.896, 0.890, 1.085, 1.085, 1.097”;
- fireplace: “1.154, 1.161, 1.013, 1.010, 1.013, 0.888, 0.883, 0.883, 0.888, 0.978, 0.974, 1.154”;
- lighting: “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 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 living 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 Single-family garage (not shared parking) EnergyPlus calculation Any other housing unit E.g., conditioned adjacent unit or conditioned corridor Same as living space SFA/MF only other heated space E.g., shared laundry/equipment space Avg of living space/outside; min of 68F SFA/MF only other multifamily buffer space E.g., enclosed unconditioned stairwell Avg of living 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 living space/outside Any under slab Ducts under slab (ground) EnergyPlus calculation Any roof deck Ducts on roof deck (outside) Weather data Any
Validating & Debugging Errors¶
When running HPXML files, errors may occur because:
- 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.