OpenStudio-ERI documentation¶
Introduction¶
The OpenStudio-ERI project allows calculating an Energy Rating Index (ERI) using the Department of Energy’s open-source OpenStudio/EnergyPlus simulation platform. The building description is provided in an HPXML file format.
The project supports:
- ANSI/RESNET/ICC 301© Standard for the Calculation and Labeling of the Energy Performance of Dwelling and Sleeping Units using an Energy Rating Index
- ENERGY STAR Certification System for Homes and Apartments Using an Energy Rating Index-Based Compliance Path
License¶
This workflow is available under a BSD-3-like license, which is a free, open-source, and permissive license. For more information, check out the license file.
Disclaimer¶
Downloading and using this software from this website does not constitute accreditation of the final software product by RESNET. If you are seeking to develop RESNET Accredited Rating Software, you will need to submit your final software product to RESNET for accreditation.
Any reference herein to RESNET, its activities, products, or services, or any linkages from this website to RESNET’s website, does not constitute or imply the endorsement, recommendation, or favoring of the U.S. Government, the Alliance for Sustainable Energy, or any of their employees or contractors acting on their behalf.
Capabilities¶
ERI Capabilities¶
The following ERI Standards and Addenda are currently available:
- ANSI/RESNET/ICC 301-2014© Standard for the Calculation and Labeling of the Energy Performance of Low-Rise Residential Buildings using an Energy Rating Index
- ANSI/RESNET/ICC 301-2014 Addendum A-2015, Domestic Hot Water Systems
- ANSI/RESNET/ICC 301-2014 Addendum D-2017, Duct Leakage to Outside Test Exception
- ANSI/RESNET/ICC 301-2014 Addendum E-2018, House Size Index Adjustment Factors
- ANSI/RESNET/ICC 301-2014 Addendum G-2018, Solid State Lighting
- ANSI/RESNET/ICC 301-2014 Addendum L-2018, Duct Leakage to Outside Test Exception
- ANSI/RESNET/ICC 301-2019 Standard for the Calculation and Labeling of the Energy Performance of Dwelling and Sleeping Units using an Energy Rating Index
- ANSI/RESNET/ICC 301-2019 Addendum A-2019, Clothes Washers and Dryers and Dishwashers
- ANSI/RESNET/ICC 301-2019 Addendum B-2020, Clarifications, HVAC Quality Installation Grading, and Dehumidification
The following ENERGY STAR programs/versions are supported:
- Single Family, National, v3.1
- Single Family, National, v3
- Single Family, Pacific, v3
- Single Family, Florida, v3.1
- Single Family, Oregon and Washington, v3.2
- Multifamily, National, v1.1
- Multifamily, National, v1
- Multifamily, Oregon and Washington, v1.2
Accuracy vs Speed¶
The EnergyPlus simulation engine is like a Swiss army knife. There are often multiple models available for the same building technology with varying trade-offs between accuracy and speed. This workflow standardizes the use of EnergyPlus (e.g., the choice of models appropriate for residential buildings) to provide a fast and easy to use solution.
The workflow is continuously being evaluated for ways to reduce runtime without significant impact on accuracy. A number of such enhancements have been made to date.
There are additional ways that software developers using this workflow can reduce runtime:
- Run on Linux/Mac platform, which is significantly faster by taking advantage of the POSIX fork call.
- Do not use the
--hourlyflag unless hourly output is required. If required, limit requests to hourly variables of interest. - Run on computing environments with 1) fast CPUs, 2) sufficient memory, and 3) enough processors to allow all simulations to run in parallel.
- Avoid using the
--add-component-loadsargument if heating/cooling component loads are not of interest.
Usage Instructions¶
Setup¶
To get started:
- Either download OpenStudio 3.3.0 and install the Command Line Interface/EnergyPlus components, or use the nrel/openstudio docker image.
- Download the latest release release.
- To obtain all available weather files, run:
openstudio workflow/energy_rating_index.rb --download-weather
Note
If the openstudio command is not found, it’s because the executable is not in your PATH. Either add the executable to your PATH or point directly to the executable found in the openstudio-X.X.X/bin directory.
Running ERI¶
Run the ERI calculation on a provided sample HPXML file as follows:
openstudio workflow/energy_rating_index.rb -x workflow/sample_files/base.xml
Note that all simulations will be executed in parallel if there are sufficient cpus/cores available.
This will generate output as shown below:
You can also request generation of timeseries output CSV files as part of the calculation by providing one or more timeseries flags (--hourly, --daily, or --monthly).
For example, to request all possible hourly outputs:
openstudio workflow/energy_rating_index.rb -x workflow/sample_files/base.xml --hourly ALL
Or for example, one or more specific monthly output types can be requested, e.g.:
openstudio workflow/energy_rating_index.rb -x workflow/sample_files/base.xml --monthly fuels --monthly temperatures
Run openstudio workflow/energy_rating_index.rb -h to see all available commands/arguments.
Running ENERGY STAR¶
Run the ENERGY STAR calculation on a provided sample HPXML file as follows:
openstudio workflow/energy_star.rb -x workflow/sample_files/base.xml
Note that all simulations will be executed in parallel if there are sufficient cpus/cores available.
Output¶
Upon completion, results are provided in the console (stdout) as well as available in summary output files. See the Workflow Outputs section for a description of all available outputs.
Workflow Inputs¶
Introduction¶
OpenStudio-ERI requires a building description in an HPXML file format. HPXML is an open data standard for collecting and transferring home energy data. Using HPXML files reduces the complexity and effort for software developers to leverage the EnergyPlus simulation engine.
HPXML Inputs¶
HPXML is an flexible and extensible format, where nearly all elements in the schema are optional and custom elements can be included. Because of this, a stricter set of requirements for the HPXML file have been developed for purposes of running an Energy Rating Index calculation.
HPXML files submitted to OpenStudio-ERI should undergo a two step validation process:
- Validation against the HPXML Schema
The HPXML XSD Schema can be found at
hpxml-measures/HPXMLtoOpenStudio/resources/HPXML.xsd. It should be used by the software developer to validate their HPXML file prior to running the workflow. XSD Schemas are used to validate what elements/attributes/enumerations are available, data types for elements/attributes, the number/order of children elements, etc.OpenStudio-ERI does not validate the HPXML file against the XSD Schema and assumes the file submitted is valid. However, OpenStudio-ERI does automatically check for valid data types (e.g., integer vs string), enumeration choices, and numeric values within min/max.
- Validation using Schematron
The Schematron document for the ERI use case can be found at
rulesets/301EnergyRatingIndexRuleset/resources/301validator.xml. Schematron is a rule-based validation language, expressed in XML using XPath expressions, for validating the presence or absence of inputs in XML files. As opposed to an XSD Schema, a Schematron document validates constraints and requirements based on conditionals and other logical statements. For example, if an element is specified with a particular value, the applicable enumerations of another element may change.OpenStudio-ERI automatically validates the HPXML file against the Schematron document and reports any validation errors, but software developers may find it beneficial to also integrate Schematron validation into their software.
Important
Usage of both validation approaches (XSD and Schematron) is recommended for developers actively working on creating HPXML files for Energy Rating Index calculations:
- Validation against XSD for general correctness and usage of HPXML
- Validation against Schematron for understanding XML document requirements specific to running ERI calculations
HPXML Software Info¶
High-level simulation inputs are entered in /HPXML/SoftwareInfo.
HPXML ERI/ES Calculation¶
The version of the ERI calculation is entered in /HPXML/SoftwareInfo/extension/ERICalculation.
Element Type Units Constraints Required Default Description Versionstring See [1] No [2] Version of 301 Standard w/ addenda
[1] Version choices are “latest”, “2019AB”, “2019A”, “2019”, “2014ADEGL”, “2014ADEG”, “2014ADE”, “2014AD”, “2014A”, or “2014”. For example, a value of “2019AB” tells the workflow to use ANSI/RESNET/ICC© 301-2019 with both Addendum A and Addendum B included. A value of “latest” can be used to always point to the latest version available.
[2] Version only required to run ERI calculation.
The version of the ENERGY STAR calculation is entered in /HPXML/SoftwareInfo/extension/EnergyStarCalculation.
Element Type Units Constraints Required Default Description Versionstring See [3] No [4] Version of ENERGY STAR program
[3] Version choices are “SF_National_3.0”, “SF_National_3.1”, “SF_Pacific_3.0”, “SF_Florida_3.1”, “SF_OregonWashington_3.2”, “MF_National_1.0”, “MF_National_1.1”, or “MF_OregonWashington_1.2”.
[4] Version only required to run ENERGY STAR calculation.
HPXML Building Summary¶
High-level building summary information is entered in /HPXML/Building/BuildingDetails/BuildingSummary.
HPXML Site¶
If running ENERGY STAR calculations (i.e., if /HPXML/SoftwareInfo/extension/EnergyStarCalculation is provided), site information is entered in /HPXML/Building/Site.
Element Type Units Constraints Required Default Description SiteIDid Yes Unique identifier Address/StateCodestring See [5] Yes State/territory where the home is located
[5] StateCode choices are only used for the ENERGY STAR calculation and depend on the ENERGY STAR version:
- National: AA, AE, AK, AL, AP, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UT, VA, VI, VT, WA, WI, WV, WY
- Pacific: HI, GU, MP
- Florida: FL
- OregonWashington: OR, WA
HPXML Building Fuels¶
Each fuel type available to the building is entered in /HPXML/Building/BuildingDetails/BuildingSummary/Site/FuelTypesAvailable.
Element Type Units Constraints Required Default Description Fuelstring See [6] Yes Fuel name
[6] Fuel choices can be found at the HPXML Toolbox website.
Note
The provided fuels are used to determine whether the home has access to natural gas or fossil fuel delivery (specified by any value other than “electricity”). This information may be used for determining the heating system, as specified by the ERI 301 Standard.
HPXML Building Construction¶
Building construction is entered in /HPXML/Building/BuildingDetails/BuildingSummary/BuildingConstruction.
Element Type Units Constraints Required Default Notes ResidentialFacilityTypestring See [7] Yes Type of dwelling unit NumberofConditionedFloorsdouble > 0 Yes Number of conditioned floors (including a basement) NumberofConditionedFloorsAboveGradedouble > 0, <= NumberofConditionedFloors Yes Number of conditioned floors above grade (including a walkout basement) NumberofBedroomsinteger > 0 Yes Number of bedrooms ConditionedFloorAreadouble ft2 > 0 Yes Floor area within conditioned space boundary
[7] ResidentialFacilityType choices are “single-family detached”, “single-family attached”, or “apartment unit”. For ENERGY STAR, “single-family detached” may only be used for SF versions and “apartment unit” may only be used for MF versions; “single-family attached” may be used for all versions.
HPXML Weather Station¶
Weather information is entered in /HPXML/Building/BuildingDetails/ClimateandRiskZones/WeatherStation.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier Namestring Yes Name of weather station extension/EPWFilePathstring Yes Path to the EnergyPlus weather file (EPW) [8]
[8] A full set of U.S. TMY3 weather files can be downloaded here.
HPXML Climate Zone¶
The IECC climate zone is entered in /HPXML/Building/BuildingDetails/ClimateandRiskZones/ClimateZoneIECC.
Element Type Units Constraints Required Default Notes Yearinteger See [9] Yes IECC year ClimateZonestring See [10] Yes IECC zone
[9] Year choices are 2003, 2006, 2009, or 2012.
[10] ClimateZone choices are “1A”, “1B”, “1C”, “2A”, “2B”, “2C”, “3A”, “3B”, “3C”, “4A”, “4B”, “4C”, “5A”, “5B”, “5C”, “6A”, “6B”, “6C”, “7”, or “8”.
HPXML Enclosure¶
The dwelling unit’s enclosure is entered in /HPXML/Building/BuildingDetails/Enclosure.
All surfaces that bound different space types of the dwelling unit (i.e., not just thermal boundary surfaces) must be specified in the HPXML file. For example, an attached garage would generally be defined by walls adjacent to conditioned space, walls adjacent to outdoors, a slab, and a roof or ceiling. For software tools that do not collect sufficient inputs for every required surface, the software developers will need to make assumptions about these surfaces or collect additional input.
Interior partition surfaces (e.g., walls between rooms inside conditioned space, or the floor between two conditioned stories) can be excluded.
For single-family attached (SFA) or multifamily (MF) buildings, surfaces between unconditioned space and the neighboring unit’s same unconditioned space should set InteriorAdjacentTo and ExteriorAdjacentTo to the same value.
For example, a foundation wall between the unit’s vented crawlspace and the neighboring unit’s vented crawlspace would use InteriorAdjacentTo="crawlspace - vented" and ExteriorAdjacentTo="crawlspace - vented".
Warning
It is the software tool’s responsibility to provide the appropriate building surfaces. While some error-checking is in place, it is not possible to know whether some surfaces are incorrectly missing.
Also note that wall and roof surfaces do not require an azimuth to be specified. Rather, only the windows/skylights themselves require an azimuth. Thus, software tools can choose to use a single wall (or roof) surface to represent multiple wall (or roof) surfaces for the entire building if all their other properties (construction type, interior/exterior adjacency, etc.) are identical.
HPXML Air Infiltration¶
Building air leakage is entered in /HPXML/Building/BuildingDetails/Enclosure/AirInfiltration/AirInfiltrationMeasurement.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier BuildingAirLeakage/UnitofMeasurestring See [11] Yes Units for air leakage HousePressuredouble Pa > 0 See [12] House pressure with respect to outside [13] BuildingAirLeakage/AirLeakagedouble > 0 Yes Value for air leakage InfiltrationVolumedouble ft3 > 0 Yes Volume associated with infiltration measurement
[11] 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).
[12] HousePressure only required if BuildingAirLeakage/UnitofMeasure is not “ACHnatural”.
[13] HousePressure typical value is 50 Pa.
HPXML Attics¶
If the dwelling unit has an unvented attic, whether it is within the infiltration volume is entered in /HPXML/Building/BuildingDetails/Enclosure/Attics/Attic[AtticType/Attic[Vented="false"]].
Element Type Units Constraints Required Default Notes WithinInfiltrationVolumeboolean Yes In accordance with ANSI/RESNET/ICC Standard 380
If the dwelling unit has a vented attic, attic ventilation information can be optionally entered in /HPXML/Building/BuildingDetails/Enclosure/Attics/Attic[AtticType/Attic[Vented="true"]]/VentilationRate.
HPXML Foundations¶
If the dwelling unit has an unconditioned basement, whether it is within the infiltration volume is entered in Enclosure/Foundations/Foundation/FoundationType/Basement[Conditioned='false'].
Element Type Units Constraints Required Default Notes WithinInfiltrationVolumeboolean Yes In accordance with ANSI/RESNET/ICC Standard 380
If the dwelling unit has an unvented crawlspace, whether it is within the infiltration volume is entered in Enclosure/Foundations/Foundation/FoundationType/Crawlspace[Vented='false'].
Element Type Units Constraints Required Default Notes WithinInfiltrationVolumeboolean Yes In accordance with ANSI/RESNET/ICC Standard 380
If the dwelling unit has a vented crawlspace, crawlspace ventilation information can be optionally entered in /HPXML/Building/BuildingDetails/Enclosure/Foundations/Foundation[FoundationType/Crawlspace[Vented="true"]]/VentilationRate.
HPXML Roofs¶
Each pitched or flat roof surface that is exposed to ambient conditions is entered as an /HPXML/Building/BuildingDetails/Enclosure/Roofs/Roof.
For a multifamily building where the dwelling unit has another dwelling unit above it, the surface between the two dwelling units should be considered a FrameFloor and not a Roof.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier InteriorAdjacentTostring See [16] Yes Interior adjacent space type Areadouble ft2 > 0 Yes Gross area (including skylights) Azimuthinteger deg 0 - 359 No See [17] Azimuth (clockwise from North) SolarAbsorptancedouble 0 - 1 Yes Solar absorptance Emittancedouble 0 - 1 Yes Emittance Pitchinteger ?:12 >= 0 Yes Pitch RadiantBarrierboolean Yes Presence of radiant barrier RadiantBarrierGradeinteger 1 - 3 See [18] Radiant barrier installation grade Insulation/SystemIdentifierid Yes Unique identifier Insulation/AssemblyEffectiveRValuedouble F-ft2-hr/Btu > 0 Yes Assembly R-value [19]
[16] InteriorAdjacentTo choices are “attic - vented”, “attic - unvented”, “living space”, or “garage”. See HPXML Locations for descriptions.
[17] If Azimuth not provided, modeled as four surfaces of equal area facing every direction.
[18] RadiantBarrierGrade only required if RadiantBarrier is provided.
[19] 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 SystemIdentifierid Yes Unique identifier ExteriorAdjacentTostring See [20] Yes Exterior adjacent space type InteriorAdjacentTostring See [21] Yes Interior adjacent space type Areadouble ft2 > 0 Yes Gross area Azimuthinteger deg 0 - 359 No See [22] Azimuth (clockwise from North) SolarAbsorptancedouble 0 - 1 Yes Solar absorptance Emittancedouble 0 - 1 Yes Emittance Insulation/SystemIdentifierid Yes Unique identifier Insulation/AssemblyEffectiveRValuedouble F-ft2-hr/Btu > 0 Yes Assembly R-value [23]
[20] ExteriorAdjacentTo choices are “outside”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.
[21] InteriorAdjacentTo choices are “living space”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, or “garage”. See HPXML Locations for descriptions.
[22] If Azimuth not provided, modeled as four surfaces of equal area facing every direction.
[23] 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 SystemIdentifierid Yes Unique identifier ExteriorAdjacentTostring See [24] Yes Exterior adjacent space type InteriorAdjacentTostring See [25] Yes Interior adjacent space type WallTypeelement 1 [26] Yes Wall type (for thermal mass) Areadouble ft2 > 0 Yes Gross area (including doors/windows) Azimuthinteger deg 0 - 359 No See [27] Azimuth (clockwise from North) SolarAbsorptancedouble 0 - 1 Yes Solar absorptance Emittancedouble 0 - 1 Yes Emittance Insulation/SystemIdentifierid Yes Unique identifier Insulation/AssemblyEffectiveRValuedouble F-ft2-hr/Btu > 0 Yes Assembly R-value [28]
[24] ExteriorAdjacentTo choices are “outside”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.
[25] InteriorAdjacentTo choices are “living space”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, or “garage”. See HPXML Locations for descriptions.
[26] WallType child element choices are WoodStud,DoubleWoodStud,ConcreteMasonryUnit,StructurallyInsulatedPanel,InsulatedConcreteForms,SteelFrame,SolidConcrete,StructuralBrick,StrawBale,Stone,LogWall, orAdobe.
[27] If Azimuth not provided, modeled as four surfaces of equal area facing every direction.
[28] 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 SystemIdentifierid Yes Unique identifier ExteriorAdjacentTostring See [29] Yes Exterior adjacent space type [30] InteriorAdjacentTostring See [31] Yes Interior adjacent space type Typestring See [32] No solid concrete Type of material Heightdouble ft > 0 Yes Total height Areadouble ft2 > 0 Yes Gross area (including doors/windows) Azimuthinteger deg 0 - 359 No See [33] Azimuth (clockwise from North) Thicknessdouble inches > 0 Yes Thickness excluding interior framing DepthBelowGradedouble ft 0 - Height Yes Depth below grade [34] Insulation/SystemIdentifierid Yes Unique identifier Insulation/Layer[InstallationType="continuous - interior"]element 0 - 1 See [35] Interior insulation layer Insulation/Layer[InstallationType="continuous - exterior"]element 0 - 1 See [36] Exterior insulation layer Insulation/AssemblyEffectiveRValuedouble F-ft2-hr/Btu > 0 See [37] Assembly R-value [38]
[29] ExteriorAdjacentTo choices are “ground”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.
[30] InteriorAdjacentTo choices are “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, or “garage”. See HPXML Locations for descriptions.
[31] 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.
[32] 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”.
[33] If Azimuth not provided, modeled as four surfaces of equal area facing every direction.
[34] 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.
[35] Layer[InstallationType=”continuous - interior”] only required if AssemblyEffectiveRValue is not provided.
[36] Layer[InstallationType=”continuous - exterior”] only required if AssemblyEffectiveRValue is not provided.
[37] AssemblyEffectiveRValue only required if Layer elements are not provided.
[38] 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 NominalRValuedouble F-ft2-hr/Btu >= 0 Yes R-value of the foundation wall insulation; use zero if no insulation DistanceToTopOfInsulationdouble ft >= 0 Yes Vertical distance from top of foundation wall to top of insulation DistanceToBottomOfInsulationdouble ft See [39] Yes Vertical distance from top of foundation wall to bottom of insulation
[39] When NominalRValue is non-zero, DistanceToBottomOfInsulation must be greater than DistanceToTopOfInsulation and less than or equal to FoundationWall/Height.
HPXML Frame Floors¶
Each floor/ceiling surface that is not in contact with the ground (Slab) nor adjacent to ambient conditions above (Roof) is entered as an /HPXML/Building/BuildingDetails/Enclosure/FrameFloors/FrameFloor.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier ExteriorAdjacentTostring See [40] Yes Exterior adjacent space type InteriorAdjacentTostring See [41] Yes Interior adjacent space type Areadouble ft2 > 0 Yes Gross area Insulation/SystemIdentifierid Yes Unique identifier Insulation/AssemblyEffectiveRValuedouble F-ft2-hr/Btu > 0 Yes Assembly R-value [42]
[40] ExteriorAdjacentTo choices are “outside”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, “garage”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.
[41] InteriorAdjacentTo choices are “living space”, “attic - vented”, “attic - unvented”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, or “garage”. See HPXML Locations for descriptions.
[42] AssemblyEffectiveRValue includes all material layers, interior/exterior air films, and insulation installation grade.
For frame floors adjacent to “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”, additional information is entered in FrameFloor.
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 SystemIdentifierid Yes Unique identifier InteriorAdjacentTostring See [44] Yes Interior adjacent space type Areadouble ft2 > 0 Yes Gross area Thicknessdouble inches >= 0 Yes Thickness [45] ExposedPerimeterdouble ft >= 0 Yes Perimeter exposed to ambient conditions [46] DepthBelowGradedouble ft >= 0 See [47] Depth from the top of the slab surface to grade PerimeterInsulation/SystemIdentifierid Yes Unique identifier PerimeterInsulation/Layer/NominalRValuedouble F-ft2-hr/Btu >= 0 Yes R-value of vertical insulation PerimeterInsulation/Layer/InsulationDepthdouble ft >= 0 Yes Depth from grade to bottom of vertical insulation UnderSlabInsulation/SystemIdentifierid Yes Unique identifier UnderSlabInsulation/Layer/NominalRValuedouble F-ft2-hr/Btu >= 0 Yes R-value of horizontal insulation UnderSlabInsulation/Layer/InsulationWidthdouble ft >= 0 See [48] Width from slab edge inward of horizontal insulation UnderSlabInsulation/Layer/InsulationSpansEntireSlabboolean See [49] Whether horizontal insulation spans entire slab extension/CarpetFractiondouble frac 0 - 1 Yes Fraction of slab covered by carpet extension/CarpetRValuedouble F-ft2-hr/Btu >= 0 Yes Carpet R-value
[44] InteriorAdjacentTo choices are “living space”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - vented”, “crawlspace - unvented”, or “garage”. See HPXML Locations for descriptions.
[45] For a crawlspace with a dirt floor, enter a thickness of zero.
[46] 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.
[47] 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/DepthBelowGradevalue.
[48] InsulationWidth only required if InsulationSpansEntireSlab=true is not provided.
[49] InsulationSpansEntireSlab=true only required if InsulationWidth is not provided.
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 SystemIdentifierid Yes Unique identifier Areadouble ft2 > 0 Yes Total area Azimuthinteger deg 0 - 359 Yes Azimuth (clockwise from North) UFactordouble Btu/F-ft2-hr > 0 Yes Full-assembly NFRC U-factor SHGCdouble 0 - 1 Yes Full-assembly NFRC solar heat gain coefficient Overhangselement 0 - 1 No <none> Presence of overhangs (including roof eaves) FractionOperabledouble frac 0 - 1 Yes Operable fraction [50] PerformanceClassstring See [51] Yes Performance class AttachedToWallidref See [52] Yes ID of attached wall
[50] FractionOperable reflects whether the windows are operable (can be opened), not how they are used by the occupants. If a Windowrepresents a single window, the value should be 0 or 1. If aWindowrepresents multiple windows (e.g., 4), the value should be between 0 and 1 (e.g., 0, 0.25, 0.5, 0.75, or 1).
[51] PerformanceClass choices are “residential” (e.g., Class R) or “architectural” (e.g., Class AW).
[52] AttachedToWall must reference a WallorFoundationWall.
If overhangs are specified, additional information is entered in Overhangs.
Element Type Units Constraints Required Default Notes Depthdouble inches >= 0 Yes Depth of overhang DistanceToTopOfWindowdouble ft >= 0 Yes Vertical distance from overhang to top of window DistanceToBottomOfWindowdouble ft See [53] Yes Vertical distance from overhang to bottom of window [54]
[53] The difference between DistanceToBottomOfWindow and DistanceToTopOfWindow defines the height of the window.
[54] 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 SystemIdentifierid Yes Unique identifier Areadouble ft2 > 0 Yes Total area Azimuthinteger deg 0 - 359 Yes Azimuth (clockwise from North) UFactordouble Btu/F-ft2-hr > 0 Yes Full-assembly NFRC U-factor SHGCdouble 0 - 1 Yes Full-assembly NFRC solar heat gain coefficient AttachedToRoofidref See [55] Yes ID of attached roof
[55] AttachedToRoof must reference a Roof.
HPXML Doors¶
Each opaque door is entered as an /HPXML/Building/BuildingDetails/Enclosure/Doors/Door.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier AttachedToWallidref See [56] Yes ID of attached wall Areadouble ft2 > 0 Yes Total area Azimuthinteger deg 0 - 359 Yes Azimuth (clockwise from North) RValuedouble F-ft2-hr/Btu > 0 Yes R-value
[56] AttachedToWall must reference a WallorFoundationWall.
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 SystemIdentifierid Yes Unique identifier HeatingSystemTypeelement 1 [57] Yes Type of heating system HeatingSystemFuelstring See [58] Yes Fuel type HeatingCapacitydouble Btu/hr >= 0 Yes Heating output capacity FractionHeatLoadServeddouble frac 0 - 1 [59] Yes Fraction of heating load served
[57] HeatingSystemType child element choices are ElectricResistance,Furnace,WallFurnace,FloorFurnace,Boiler,Stove,PortableHeater,FixedHeater,Fireplace, orPackagedTerminalAirConditionerHeating.
[58] HeatingSystemFuel choices are “natural gas”, “fuel oil”, “propane”, “electricity”, “wood”, or “wood pellets”. For ElectricResistance, “electricity” is required. ForPackagedTerminalAirConditionerHeating, “electricity” is currently the only choice.
[59] The sum of all FractionHeatLoadServed(across both HeatingSystems and HeatPumps) must be less than or equal to 1.
Electric Resistance¶
If electric resistance heating is specified, additional information is entered in HeatingSystem.
Element Type Units Constraints Required Default Notes AnnualHeatingEfficiency[Units="Percent"]/Valuedouble frac 0 - 1 Yes Efficiency
Furnace¶
If a furnace is specified, additional information is entered in HeatingSystem.
Element Type Units Constraints Required Default Notes DistributionSystemidref See [60] Yes ID of attached distribution system AnnualHeatingEfficiency[Units="AFUE"]/Valuedouble frac 0 - 1 Yes Rated efficiency extension/FanPowerWattsPerCFMdouble W/cfm >= 0 [61] Yes Fan power [62] extension/AirflowDefectRatiodouble frac > -1 Yes Deviation between design/installed airflows [63]
[60] HVACDistribution type must be AirDistribution (type: “regular velocity” or “gravity”) or DSE.
[61] If there is a cooling system attached to the DistributionSystem, the heating and cooling systems cannot have different values for FanPowerWattsPerCFM.
[62] If the fan power is not measured, a value of 0.58 W/cfm should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
[63] 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. If the airflow rate is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
Warning
HVAC installation quality should be provided per the conditions specified in ANSI/RESNET/ACCA 310. OS-ERI does not check that, for example, the total duct leakage requirement has been met or that a Grade I/II input is appropriate per the ANSI 310 process flow; that is currently the responsibility of the software developer.
Wall/Floor Furnace¶
If a wall furnace or floor furnace is specified, additional information is entered in HeatingSystem.
Element Type Units Constraints Required Default Notes AnnualHeatingEfficiency[Units="AFUE"]/Valuedouble frac 0 - 1 Yes Rated efficiency extension/FanPowerWattsdouble 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 IsSharedSystemboolean Yes Whether it serves multiple dwelling units DistributionSystemidref See [64] Yes ID of attached distribution system AnnualHeatingEfficiency[Units="AFUE"]/Valuedouble frac 0 - 1 Yes Rated efficiency
[64] 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 NumberofUnitsServedinteger > 1 Yes Number of dwelling units served extension/SharedLoopWattsdouble W >= 0 Yes Shared loop power extension/SharedLoopMotorEfficiencydouble frac 0 - 1 No 0.85 Shared loop motor efficiency extension/FanCoilWattsdouble W >= 0 See [66] Fan coil power
[66] FanCoilWatts only required if boiler connected to fan coil.
Stove¶
If a stove is specified, additional information is entered in HeatingSystem.
Element Type Units Constraints Required Default Notes AnnualHeatingEfficiency[Units="Percent"]/Valuedouble frac 0 - 1 Yes Efficiency extension/FanPowerWattsdouble 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"]/Valuedouble frac 0 - 1 Yes Efficiency extension/FanPowerWattsdouble 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"]/Valuedouble frac 0 - 1 Yes Efficiency extension/FanPowerWattsdouble W >= 0 No 0 Fan power
PTAC Heating¶
If a PTAC with non-heat pump (e.g., electric resistance) heating is specified, additional information is entered in HeatingSystem.
Element Type Units Constraints Required Default Notes AnnualHeatingEfficiency[Units="Percent"]/Valuedouble frac 0 - 1 No 1.0 Efficiency
Note
A cooling system of type “packaged terminal air conditioner” must be specified in /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/CoolingSystem.
HPXML Cooling Systems¶
Each cooling system (other than a heat pump) is entered as an /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/CoolingSystem.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier CoolingSystemTypestring See [67] Yes Type of cooling system CoolingSystemFuelstring See [68] Yes Fuel type FractionCoolLoadServeddouble frac 0 - 1 [69] Yes Fraction of cooling load served
[67] CoolingSystemType choices are “central air conditioner”, “room air conditioner”, “evaporative cooler”, “mini-split”, “chiller”, “cooling tower”, or “packaged terminal air conditioner”.
[68] CoolingSystemFuel only choice is “electricity”.
[69] The sum of all FractionCoolLoadServed(across both CoolingSystems and HeatPumps) 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 DistributionSystemidref See [70] Yes ID of attached distribution system AnnualCoolingEfficiency[Units="SEER"]/Valuedouble Btu/Wh > 0 Yes Rated efficiency CoolingCapacitydouble Btu/hr >= 0 Yes Cooling output capacity SensibleHeatFractiondouble frac 0 - 1 No Sensible heat fraction CompressorTypestring See [71] No See [72] Type of compressor extension/FanPowerWattsPerCFMdouble W/cfm >= 0 [73] Yes Fan power [74] extension/AirflowDefectRatiodouble frac > -1 Yes Deviation between design/installed airflows [75] extension/ChargeDefectRatiodouble frac -0.25, 0, 0.25 Yes Deviation between design/installed charges [76]
[70] HVACDistribution type must be AirDistribution (type: “regular velocity”) or DSE.
[71] CompressorType choices are “single stage”, “two stage”, or “variable speed”.
[72] If CompressorType not provided, defaults to “single stage” if SEER <= 15, else “two stage” if SEER <= 21, else “variable speed”.
[73] If there is a heating system attached to the DistributionSystem, the heating and cooling systems cannot have different values for FanPowerWattsPerCFM.
[74] If the fan power is not measured, a value of 0.58 W/cfm should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
[75] 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. If the airflow rate is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
[76] 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. If the charge is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
Warning
HVAC installation quality should be provided per the conditions specified in ANSI/RESNET/ACCA 310. OS-ERI does not check that, for example, the total duct leakage requirement has been met or that a Grade I/II input is appropriate per the ANSI 310 process flow; that is currently the responsibility of the software developer.
Room Air Conditioner¶
If a room air conditioner is specified, additional information is entered in CoolingSystem.
Element Type Units Constraints Required Default Notes AnnualCoolingEfficiency[Units="EER" or Units="CEER"]/Valuedouble Btu/Wh > 0 Yes Rated efficiency CoolingCapacitydouble Btu/hr >= 0 Yes Cooling output capacity SensibleHeatFractiondouble frac 0 - 1 No Sensible heat fraction
Packaged Terminal Air Conditioner¶
If a PTAC is specified, additional information is entered in CoolingSystem.
Element Type Units Constraints Required Default Notes AnnualCoolingEfficiency[Units="EER" or Units="CEER"]/Valueinteger or double # or Btu/Wh > 1600 or > 0 Yes Rated cooling efficiency CoolingCapacitydouble Btu/hr >= 0 Yes Cooling output capacity SensibleHeatFractiondouble frac 0 - 1 No Sensible heat fraction
Evaporative Cooler¶
If an evaporative cooler is specified, additional information is entered in CoolingSystem.
Mini-Split¶
If a mini-split is specified, additional information is entered in CoolingSystem.
Element Type Units Constraints Required Default Notes DistributionSystemidref See [78] No ID of attached distribution system AnnualCoolingEfficiency[Units="SEER"]/Valuedouble Btu/Wh > 0 Yes Rated cooling efficiency CoolingCapacitydouble Btu/hr >= 0 Yes Cooling output capacity SensibleHeatFractiondouble frac 0 - 1 No Sensible heat fraction extension/FanPowerWattsPerCFMdouble W/cfm >= 0 Yes Fan power [79] extension/AirflowDefectRatiodouble frac > -1 Yes Deviation between design/installed airflows [80] extension/ChargeDefectRatiodouble frac -0.25, 0, 0.25 Yes Deviation between design/installed charges [81]
[78] If provided, HVACDistribution type must be AirDistribution (type: “regular velocity”) or DSE.
[79] If the fan power is not measured, a value of 0.58 W/cfm should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
[80] 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. If the airflow rate is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
[81] 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. If the charge is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
Warning
HVAC installation quality should be provided per the conditions specified in ANSI/RESNET/ACCA 310. OS-ERI does not check that, for example, the total duct leakage requirement has been met or that a Grade I/II input is appropriate per the ANSI 310 process flow; that is currently the responsibility of the software developer.
Chiller¶
If a chiller is specified, additional information is entered in CoolingSystem.
Element Type Units Constraints Required Default Notes IsSharedSystemboolean true Yes Whether it serves multiple dwelling units DistributionSystemidref See [82] Yes ID of attached distribution system NumberofUnitsServedinteger > 1 Yes Number of dwelling units served CoolingCapacitydouble Btu/hr >= 0 Yes Total cooling output capacity AnnualCoolingEfficiency[Units="kW/ton"]/Valuedouble kW/ton > 0 Yes Rated efficiency extension/SharedLoopWattsdouble W >= 0 Yes Pumping and fan power serving the system extension/SharedLoopMotorEfficiencydouble frac 0 - 1 No 0.85 Shared loop motor efficiency extension/FanCoilWattsdouble W >= 0 See [83] Fan coil power
[82] 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.
[83] FanCoilWatts only required if chiller connected to fan coil.
Cooling Tower¶
If a cooling tower is specified, additional information is entered in CoolingSystem.
Element Type Units Constraints Required Default Notes IsSharedSystemboolean true Yes Whether it serves multiple dwelling units DistributionSystemidref See [84] Yes ID of attached distribution system NumberofUnitsServedinteger > 1 Yes Number of dwelling units served extension/SharedLoopWattsdouble W >= 0 Yes Pumping and fan power serving the system extension/SharedLoopMotorEfficiencydouble frac 0 - 1 No 0.85 Shared loop motor efficiency
[84] HVACDistribution type must be HydronicDistribution (type: “water loop”). A Water-Loop-to-Air Heat Pump must also be specified.
HPXML Heat Pumps¶
Each heat pump is entered as an /HPXML/Building/BuildingDetails/Systems/HVAC/HVACPlant/HeatPump.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier HeatPumpTypestring See [85] Yes Type of heat pump HeatPumpFuelstring See [86] Yes Fuel type BackupTypestring See [87] No <none> Type of backup heating
[85] HeatPumpType choices are “air-to-air”, “mini-split”, “ground-to-air”, “water-loop-to-air”, or “packaged terminal heat pump”.
[86] HeatPumpFuel only choice is “electricity”.
[87] BackupType only choice is “integrated”. 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).
If a backup type of “integrated” is provided, additional information is entered in HeatPump.
Element Type Units Constraints Required Default Notes BackupSystemFuelstring See [88] Yes Integrated backup heating fuel type BackupAnnualHeatingEfficiency[Units="Percent" or Units="AFUE"]/Valuedouble frac 0 - 1 Yes Integrated backup heating efficiency BackupHeatingCapacitydouble Btu/hr >= 0 Yes Integrated backup heating output capacity BackupHeatingSwitchoverTemperaturedouble F No <none> Integrated backup heating switchover temperature [89]
[88] BackupSystemFuel choices are “electricity”, “natural gas”, “fuel oil”, “propane”, “wood”, or “wood pellets”.
[89] Provide BackupHeatingSwitchoverTemperature for a situation in which 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.
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 DistributionSystemidref See [90] Yes ID of attached distribution system CompressorTypestring See [91] No See [92] Type of compressor HeatingCapacitydouble Btu/hr >= 0 Yes Heating output capacity (excluding any backup heating) HeatingCapacity17Fdouble Btu/hr >= 0, <= HeatingCapacity No Heating output capacity at 17F, if available CoolingCapacitydouble Btu/hr >= 0 Yes Cooling output capacity CoolingSensibleHeatFractiondouble frac 0 - 1 No Sensible heat fraction FractionHeatLoadServeddouble frac 0 - 1 [93] Yes Fraction of heating load served FractionCoolLoadServeddouble frac 0 - 1 [94] Yes Fraction of cooling load served AnnualCoolingEfficiency[Units="SEER"]/Valuedouble Btu/Wh > 0 Yes Rated cooling efficiency AnnualHeatingEfficiency[Units="HSPF"]/Valuedouble Btu/Wh > 0 Yes Rated heating efficiency extension/FanPowerWattsPerCFMdouble W/cfm >= 0 Yes Fan power [95] extension/AirflowDefectRatiodouble frac > -1 Yes Deviation between design/installed airflows [96] extension/ChargeDefectRatiodouble frac -0.25, 0, 0.25 Yes Deviation between design/installed charges [97]
[90] HVACDistribution type must be AirDistribution (type: “regular velocity”) or DSE.
[91] CompressorType choices are “single stage”, “two stage”, or “variable speed”.
[92] If CompressorType not provided, defaults to “single stage” if SEER <= 15, else “two stage” if SEER <= 21, else “variable speed”.
[93] The sum of all FractionHeatLoadServed(across both HeatingSystems and HeatPumps) must be less than or equal to 1.
[94] The sum of all FractionCoolLoadServed(across both CoolingSystems and HeatPumps) must be less than or equal to 1.
[95] If the fan power is not measured, a value of 0.58 W/cfm should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
[96] 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. If the airflow rate is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
[97] 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. If the charge is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
Warning
HVAC installation quality should be provided per the conditions specified in ANSI/RESNET/ACCA 310. OS-ERI does not check that, for example, the total duct leakage requirement has been met or that a Grade I/II input is appropriate per the ANSI 310 process flow; that is currently the responsibility of the software developer.
Mini-Split Heat Pump¶
If a mini-split heat pump is specified, additional information is entered in HeatPump.
Element Type Units Constraints Required Default Notes DistributionSystemidref See [98] No ID of attached distribution system, if present HeatingCapacitydouble Btu/hr >= 0 Yes Heating output capacity (excluding any backup heating) HeatingCapacity17Fdouble Btu/hr >= 0, <= HeatingCapacity No Heating output capacity at 17F, if available CoolingCapacitydouble Btu/hr >= 0 Yes Cooling output capacity CoolingSensibleHeatFractiondouble frac 0 - 1 No Sensible heat fraction FractionHeatLoadServeddouble frac 0 - 1 [99] Yes Fraction of heating load served FractionCoolLoadServeddouble frac 0 - 1 [100] Yes Fraction of cooling load served AnnualCoolingEfficiency[Units="SEER"]/Valuedouble Btu/Wh > 0 Yes Rated cooling efficiency AnnualHeatingEfficiency[Units="HSPF"]/Valuedouble Btu/Wh > 0 Yes Rated heating efficiency extension/FanPowerWattsPerCFMdouble W/cfm >= 0 Yes Fan power [101] extension/AirflowDefectRatiodouble frac > -1 Yes Deviation between design/installed airflows [102] extension/ChargeDefectRatiodouble frac -0.25, 0, 0.25 Yes Deviation between design/installed charges [103]
[98] If provided, HVACDistribution type must be AirDistribution (type: “regular velocity”) or DSE.
[99] The sum of all FractionHeatLoadServed(across both HeatingSystems and HeatPumps) must be less than or equal to 1.
[100] The sum of all FractionCoolLoadServed(across both CoolingSystems and HeatPumps) must be less than or equal to 1.
[101] If the fan power is not measured, a value of 0.58 W/cfm should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
[102] 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. If the airflow rate is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
[103] 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. If the charge is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
Warning
HVAC installation quality should be provided per the conditions specified in ANSI/RESNET/ACCA 310. OS-ERI does not check that, for example, the total duct leakage requirement has been met or that a Grade I/II input is appropriate per the ANSI 310 process flow; that is currently the responsibility of the software developer.
Packaged Terminal Heat Pump¶
If a packaged terminal heat pump is specified, additional information is entered in HeatPump.
Element Type Units Constraints Required Default Notes HeatingCapacitydouble Btu/hr >= 0 Yes Heating output capacity (excluding any backup heating) CoolingCapacitydouble Btu/hr >= 0 Yes Cooling output capacity CoolingSensibleHeatFractiondouble frac 0 - 1 No Sensible heat fraction FractionHeatLoadServeddouble frac 0 - 1 [104] Yes Fraction of heating load served FractionCoolLoadServeddouble frac 0 - 1 [105] Yes Fraction of cooling load served AnnualCoolingEfficiency[Units="EER" or Units="CEER"]/Valuedouble Btu/Wh > 0 Yes Rated cooling efficiency AnnualHeatingEfficiency[Units="COP"]/Valuedouble Btu/Wh > 0 Yes Rated heating efficiency
[104] The sum of all FractionHeatLoadServed(across both HeatingSystems and HeatPumps) must be less than or equal to 1.
[105] The sum of all FractionCoolLoadServed(across both CoolingSystems and HeatPumps) 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 IsSharedSystemboolean Yes Whether it has a shared hydronic circulation loop [106] DistributionSystemidref See [107] Yes ID of attached distribution system HeatingCapacitydouble Btu/hr >= 0 Yes Heating output capacity (excluding any backup heating) CoolingCapacitydouble Btu/hr >= 0 Yes Cooling output capacity CoolingSensibleHeatFractiondouble frac 0 - 1 No Sensible heat fraction FractionHeatLoadServeddouble frac 0 - 1 [108] Yes Fraction of heating load served FractionCoolLoadServeddouble frac 0 - 1 [109] Yes Fraction of cooling load served AnnualCoolingEfficiency[Units="EER"]/Valuedouble Btu/Wh > 0 Yes Rated cooling efficiency AnnualHeatingEfficiency[Units="COP"]/Valuedouble W/W > 0 Yes Rated heating efficiency NumberofUnitsServedinteger > 0 See [110] Number of dwelling units served extension/PumpPowerWattsPerTondouble W/ton >= 0 Yes Pump power [111] extension/SharedLoopWattsdouble W >= 0 See [112] Shared pump power [113] extension/SharedLoopMotorEfficiencydouble frac 0 - 1 No 0.85 [114] Shared loop motor efficiency extension/FanPowerWattsPerCFMdouble W/cfm >= 0 Yes Fan power [115] extension/AirflowDefectRatiodouble frac > -1 Yes Deviation between design/installed airflows [116] extension/ChargeDefectRatiodouble frac -0.25, 0, 0.25 Yes Deviation between design/installed charges [117]
[106] IsSharedSystem should be true if the SFA/MF building has multiple ground source heat pumps connected to a shared hydronic circulation loop.
[107] HVACDistribution type must be AirDistribution (type: “regular velocity”) or DSE.
[108] The sum of all FractionHeatLoadServed(across both HeatingSystems and HeatPumps) must be less than or equal to 1.
[109] The sum of all FractionCoolLoadServed(across both CoolingSystems and HeatPumps) must be less than or equal to 1.
[110] NumberofUnitsServed only required if IsSharedSystem is true, in which case it must be > 1.
[111] 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.
[112] SharedLoopWatts only required if IsSharedSystem is true.
[113] Shared loop pump power attributed to the dwelling unit is calculated as SharedLoopWatts / NumberofUnitsServed.
[114] SharedLoopMotorEfficiency only used if IsSharedSystem is true.
[115] If the fan power is not measured, a value of 0.58 W/cfm should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
[116] 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. If the airflow rate is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
[117] 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. If the charge is not measured and the measurement is not exempted, a value of -0.25 should be used according to ANSI/RESNET/ICC© 301-2019 Addendum B.
Warning
HVAC installation quality should be provided per the conditions specified in ANSI/RESNET/ACCA 310. OS-ERI does not check that, for example, the total duct leakage requirement has been met or that a Grade I/II input is appropriate per the ANSI 310 process flow; that is currently the responsibility of the software developer.
Water-Loop-to-Air Heat Pump¶
If a water-loop-to-air heat pump is specified, additional information is entered in HeatPump.
Element Type Units Constraints Required Default Notes DistributionSystemidref See [118] Yes ID of attached distribution system HeatingCapacitydouble Btu/hr > 0 See [119] Heating output capacity CoolingCapacitydouble Btu/hr > 0 See [120] Cooling output capacity AnnualCoolingEfficiency[Units="EER"]/Valuedouble Btu/Wh > 0 See [121] Rated cooling efficiency AnnualHeatingEfficiency[Units="COP"]/Valuedouble W/W > 0 See [122] Rated heating efficiency
[118] HVACDistribution type must be AirDistribution (type: “regular velocity”) or DSE.
[119] HeatingCapacity required if there is a shared boiler with water loop distribution.
[120] CoolingCapacity required if there is a shared chiller or cooling tower with water loop distribution.
[121] AnnualCoolingEfficiency required if there is a shared chiller or cooling tower with water loop distribution.
[122] 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.
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 SystemIdentifierid Yes Unique identifier DistributionSystemTypeelement 1 [124] Yes Type of distribution system ConditionedFloorAreaServeddouble ft2 > 0 See [125] Conditioned floor area served
[124] DistributionSystemType child element choices are AirDistribution,HydronicDistribution, orOther=DSE.
[125] ConditionedFloorAreaServed required only when DistributionSystemType is AirDistribution and AirDistribution/Ductsare present.
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 AirDistributionTypestring See [126] Yes Type of air distribution NumberofReturnRegistersinteger >= 0 See [127] Number of return registers
[126] 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.).
[127] NumberofReturnRegisters required only if AirDistribution/Ductsare present.
For the air distribution system, duct leakage inputs are required if AirDistributionType is “regular velocity” or “gravity” and optional if AirDistributionType is “fan coil”.
When provided, duct leakage must be entered in one of three ways:
- Leakage to the Outside
Supply and return leakage to the outside are each entered as a
HVACDistribution/DistributionSystemType/AirDistribution/DuctLeakageMeasurement:
Element Type Units Constraints Required Default Notes DuctTypestring See [128] Yes Supply or return ducts DuctLeakage/Unitsstring CFM25 Yes Duct leakage units DuctLeakage/Valuedouble >= 0 Yes Duct leakage value [129] DuctLeakage/TotalOrToOutsidestring to outside Yes Type of duct leakage (outside conditioned space vs total)
[128] DuctType choices are “supply” or “return”.
[129] If the HVAC system has no return ducts (e.g., a ducted evaporative cooler), use zero for the Value.
- Total Leakage (Version 2014ADEGL or newer)
Total leakage is entered as a
HVACDistribution/DistributionSystemType/AirDistribution/DuctLeakageMeasurement:
Element Type Units Constraints Required Default Notes DuctLeakage/Unitsstring CFM25 Yes Duct leakage units DuctLeakage/Valuedouble >= 0 Yes Duct leakage value DuctLeakage/TotalOrToOutsidestring total Yes Type of duct leakage (outside conditioned space vs total) If the ResidentialFacilityType is “apartment unit”, OS-ERI will calculate leakage to outside for the given distribution system as half the total leakage.
If the ResidentialFacilityType is anything else, OS-ERI will calculate leakage to outside for the given distribution system based on total leakage, the fraction of duct surface area outside conditioned space, and HVAC capacities. OS-ERI currently assumes the air handler is located outside conditioned space; future inputs will be available to describe when the air handler is within conditioned space.
Warning
Total leakage should only be used if the conditions specified in ANSI/RESNET/ICC 301 have been appropriately met. OS-ERI does not check that, for example, the total duct leakage or infiltration requirements for dwellings and townhouses have been met per ANSI 301; that is currently the responsibility of the software developer.
Leakage to Outside Testing Exemption (Version 2014AD or newer)
A duct leakage to outside testing exemption is entered in
HVACDistribution/DistributionSystemType/AirDistribution:
Element Type Units Constraints Required Default Notes extension/DuctLeakageToOutsideTestingExemption=trueboolean true Yes Leakage to outside exemption? OS-ERI will use a DSE of 0.88 for the given distribution system.
Warning
The duct leakage to outside testing exemption should only be used if the conditions specified in ANSI/RESNET/ICC 301 have been appropriately met.
Additionally, each supply/return duct present is entered in a HVACDistribution/DistributionSystemType/AirDistribution/Ducts.
Element Type Units Constraints Required Default Notes DuctTypestring See [130] Yes Supply or return ducts DuctInsulationRValuedouble F-ft2-hr/Btu >= 0 Yes R-value of duct insulation [131] DuctSurfaceAreadouble ft2 >= 0 Yes Duct surface area DuctLocationstring See [132] Yes Duct location
[130] DuctType choices are “supply” or “return”.
[131] DuctInsulationRValue should not include air films (i.e., use 0 for an uninsulated duct).
[132] DuctLocation choices are “living space”, “basement - conditioned”, “basement - unconditioned”, “crawlspace - unvented”, “crawlspace - vented”, “attic - unvented”, “attic - vented”, “garage”, “outside”, “exterior wall”, “under slab”, “roof deck”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.
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.
To define a DSE system, additional information is entered in HVACDistribution.
Element Type Units Constraints Required Default Notes AnnualHeatingDistributionSystemEfficiencydouble frac 0 - 1 Yes Seasonal distribution system efficiency for heating AnnualCoolingDistributionSystemEfficiencydouble frac 0 - 1 Yes Seasonal distribution system efficiency for cooling DSE values can be calculated from ASHRAE Standard 152.
HPXML Ventilation Fan¶
Each mechanical ventilation system that provides ventilation to the whole dwelling unit is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier UsedForWholeBuildingVentilationboolean true Yes Must be set to true IsSharedSystemboolean See [134] Yes Whether it serves multiple dwelling units FanTypestring See [135] Yes Type of ventilation system HoursInOperationdouble hrs/day 0 - 24 Yes Hours per day of operation FanPowerorextension/FanPowerDefaulted=truedouble or boolean W >= 0 or true Yes Fan power or whether fan power is unknown
[134] For central fan integrated supply systems, IsSharedSystem must be false.
[135] FanType choices are “energy recovery ventilator”, “heat recovery ventilator”, “exhaust only”, “supply only”, “balanced”, or “central fan integrated supply”.
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 SensibleRecoveryEfficiencyorAdjustedSensibleRecoveryEfficiencydouble 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 TotalRecoveryEfficiencyorAdjustedTotalRecoveryEfficiencydouble frac 0 - 1 Yes (Adjusted) Total recovery efficiency SensibleRecoveryEfficiencyorAdjustedSensibleRecoveryEfficiencydouble frac 0 - 1 Yes (Adjusted) Sensible recovery efficiency
Central Fan Integrated Supply¶
If a central fan integrated supply system is specified, additional information is entered in VentilationFan.
In-Unit System¶
If the specified system is not a shared system (i.e., not serving multiple dwelling units), additional information is entered in VentilationFan.
Element Type Units Constraints Required Default Notes TestedFlowRateorextension/FlowRateNotTested=truedouble or boolean cfm >= 0 or true Yes Flow rate [137] or whether flow rate unmeasured
[137] For a central fan integrated supply system, TestedFlowRate should equal the amount of outdoor air provided to the distribution system.
HPXML Whole House Fan¶
Each whole house fan that provides cooling load reduction is entered as a /HPXML/Building/BuildingDetails/Systems/MechanicalVentilation/VentilationFans/VentilationFan.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier UsedForSeasonalCoolingLoadReductionboolean true Yes Must be set to true RatedFlowRatedouble cfm >= 0 Yes Flow rate FanPowerdouble W >= 0 Yes Fan power
Note
The whole house fan is assumed to operate during hours of favorable outdoor conditions and will take priority over operable windows (natural ventilation).
HPXML Water Heating Systems¶
Each water heater is entered as a /HPXML/Building/BuildingDetails/Systems/WaterHeating/WaterHeatingSystem.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier IsSharedSystemboolean Yes Whether it serves multiple dwelling units or shared laundry room WaterHeaterTypestring See [144] Yes Type of water heater Locationstring See [145] Yes Water heater location FractionDHWLoadServeddouble frac 0 - 1 [146] Yes Fraction of hot water load served [147] UsesDesuperheaterboolean No false Presence of desuperheater? NumberofUnitsServedinteger > 0 See [148] Number of dwelling units served directly or indirectly
[144] 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”.
[145] Location choices are “living space”, “basement - unconditioned”, “basement - conditioned”, “attic - unvented”, “attic - vented”, “garage”, “crawlspace - unvented”, “crawlspace - vented”, “other exterior”, “other housing unit”, “other heated space”, “other multifamily buffer space”, or “other non-freezing space”. See HPXML Locations for descriptions.
[146] The sum of all FractionDHWLoadServed(across all WaterHeatingSystems) must equal to 1.
[147] 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).
[148] 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 FuelTypestring See [149] Yes Fuel type TankVolumedouble gal > 0 Yes Tank volume HeatingCapacitydouble Btuh > 0 No See [150] Heating output capacity UniformEnergyFactororEnergyFactordouble frac < 1 Yes EnergyGuide label rated efficiency FirstHourRatingdouble gal/hr > 0 See [151] EnergyGuide label first hour rating RecoveryEfficiencydouble frac 0 - 1 See [152] Recovery efficiency WaterHeaterInsulation/Jacket/JacketRValuedouble F-ft2-hr/Btu >= 0 No 0 R-value of additional tank insulation wrap
[149] FuelType choices are “natural gas”, “fuel oil”, “propane”, “electricity”, “wood”, or “wood pellets”.
[150] If HeatingCapacity not provided, defaults based on Table 8 in the 2014 BAHSP.
[151] FirstHourRating only required if UniformEnergyFactor provided.
[152] RecoveryEfficiency only required if FuelType is not electricity.
Tankless¶
If an instantaneous tankless water heater is specified, additional information is entered in WaterHeatingSystem.
Heat Pump¶
If a heat pump water heater is specified, additional information is entered in WaterHeatingSystem.
Element Type Units Constraints Required Default Notes FuelTypestring See [154] Yes Fuel type TankVolumedouble gal > 0 Yes Tank volume UniformEnergyFactororEnergyFactordouble frac > 1 Yes EnergyGuide label rated efficiency FirstHourRatingdouble gal/hr > 0 See [155] EnergyGuide label first hour rating WaterHeaterInsulation/Jacket/JacketRValuedouble F-ft2-hr/Btu >= 0 No 0 R-value of additional tank insulation wrap
[154] FuelType only choice is “electricity”.
[155] FirstHourRating only required if UniformEnergyFactor provided.
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 RelatedHVACSystemidref See [156] Yes ID of boiler TankVolumedouble gal > 0 Yes Volume of the storage tank WaterHeaterInsulation/Jacket/JacketRValuedouble F-ft2-hr/Btu >= 0 No 0 R-value of additional storage tank insulation wrap StandbyLossdouble F/hr > 0 No See [157] Storage tank standby losses
[156] RelatedHVACSystem must reference a HeatingSystemof type Boiler.
[157] 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.
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 SystemIdentifierid Yes Unique identifier SystemTypeelement 1 [160] Yes Type of in-unit distribution system serving the dwelling unit PipeInsulation/PipeRValuedouble F-ft2-hr/Btu >= 0 Yes Pipe insulation R-value DrainWaterHeatRecoveryelement 0 - 1 No <none> Presence of drain water heat recovery device extension/SharedRecirculationelement 0 - 1 [161] No <none> Presence of shared recirculation system serving multiple dwelling units
[160] SystemType child element choices are StandardandRecirculation.
[161] 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 PipingLengthdouble ft > 0 Yes Length of piping [162]
[162] 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 ControlTypestring See [163] Yes Recirculation control type RecirculationPipingLoopLengthdouble ft > 0 Yes Recirculation piping loop length [164] BranchPipingLoopLengthdouble ft > 0 Yes Branch piping loop length [165] PumpPowerdouble W >= 0 Yes Recirculation pump power
[163] ControlType choices are “manual demand control”, “presence sensor demand control”, “temperature”, “timer”, or “no control”.
[164] 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.
[165] BranchPipingLoopLength 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.
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 FacilitiesConnectedstring See [167] Yes Specifies which facilities are connected EqualFlowboolean Yes Specifies how the DHWR is configured [168] Efficiencydouble frac 0 - 1 Yes Efficiency according to CSA 55.1
[167] 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.
[168] 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 SystemIdentifierid Yes Unique identifier WaterFixtureTypestring See [169] Yes Type of water fixture LowFlowboolean Yes Whether the fixture is considered low-flow [170]
[169] WaterFixtureType choices are “shower head” or “faucet”.
[170] LowFlow should be true if the fixture’s flow rate (gpm) is <= 2.0.
HPXML Solar Thermal¶
A single solar hot water system can be entered as a /HPXML/Building/BuildingDetails/Systems/SolarThermal/SolarThermalSystem.
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 SolarFractiondouble frac 0 - 1 Yes Solar fraction [172] ConnectedToidref See [173] No [174] <none> Connected water heater
[172] 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.
[173] ConnectedTo must reference a WaterHeatingSystem. The referenced water heater cannot be a space-heating boiler nor attached to a desuperheater.
[174] 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 CollectorAreadouble ft2 > 0 Yes Area CollectorLoopTypestring See [175] Yes Loop type CollectorTypestring See [176] Yes System type CollectorAzimuthinteger deg 0 - 359 Yes Azimuth (clockwise from North) CollectorTiltdouble deg 0 - 90 Yes Tilt relative to horizontal CollectorRatedOpticalEfficiencydouble frac 0 - 1 Yes Rated optical efficiency [177] CollectorRatedThermalLossesdouble Btu/hr-ft2-R > 0 Yes Rated thermal losses [178] StorageVolumedouble gal > 0 Yes Hot water storage volume ConnectedToidref See [179] Yes Connected water heater
[175] CollectorLoopType choices are “liquid indirect”, “liquid direct”, or “passive thermosyphon”.
[176] CollectorType choices are “single glazing black”, “double glazing black”, “evacuated tube”, or “integrated collector storage”.
[177] CollectorRatedOpticalEfficiency is FRTA (y-intercept) from the Directory of SRCC OG-100 Certified Solar Collector Ratings.
[178] CollectorRatedThermalLosses is FRUL (slope) from the Directory of SRCC OG-100 Certified Solar Collector Ratings.
[179] ConnectedTo must reference a WaterHeatingSystemthat is not of type space-heating boiler nor connected to a desuperheater.
HPXML Photovoltaics¶
Each solar electric photovoltaic (PV) system is entered as a /HPXML/Building/BuildingDetails/Systems/Photovoltaics/PVSystem.
Many of the inputs are adopted from the PVWatts model.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier IsSharedSystemboolean Yes Whether it serves multiple dwelling units Locationstring See [180] Yes Mounting location ModuleTypestring See [181] Yes Type of module Trackingstring See [182] Yes Type of tracking ArrayAzimuthinteger deg 0 - 359 Yes Direction panels face (clockwise from North) ArrayTiltdouble deg 0 - 90 Yes Tilt relative to horizontal MaxPowerOutputdouble W >= 0 Yes Peak power InverterEfficiencydouble frac 0 - 1 Yes Inverter efficiency [183] SystemLossesFractiondouble frac 0 - 1 Yes System losses [184] extension/NumberofBedroomsServedinteger > 1 See [185] Number of bedrooms served
[180] Location choices are “ground” or “roof” mounted.
[181] ModuleType choices are “standard”, “premium”, or “thin film”.
[182] Tracking choices are “fixed”, “1-axis”, “1-axis backtracked”, or “2-axis”.
[183] Default from PVWatts is 0.96.
[184] System losses due to soiling, shading, snow, mismatch, wiring, degradation, etc. Default from PVWatts is 0.14.
[185] 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 Generators¶
Each generator that provides on-site power is entered as a /HPXML/Building/BuildingDetails/Systems/extension/Generators/Generator.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier IsSharedSystemboolean Yes Whether it serves multiple dwelling units FuelTypestring See [186] Yes Fuel type AnnualConsumptionkBtudouble kBtu/yr > 0 Yes Annual fuel consumed AnnualOutputkWhdouble kWh/yr > 0 [187] Yes Annual electricity produced NumberofBedroomsServedinteger > 1 See [188] Number of bedrooms served
[186] FuelType choices are “natural gas”, “fuel oil”, “propane”, “wood”, or “wood pellets”.
[187] AnnualOutputkWh must also be < AnnualConsumptionkBtu*3.412 (i.e., the generator must consume more energy than it produces).
[188] 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.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier IsSharedApplianceboolean Yes Whether it serves multiple dwelling units [189] Locationstring See [190] Yes Location IntegratedModifiedEnergyFactororModifiedEnergyFactordouble ft3/kWh/cyc > 0 Yes EnergyGuide label efficiency [191] RatedAnnualkWhdouble kWh/yr > 0 Yes EnergyGuide label annual consumption LabelElectricRatedouble $/kWh > 0 Yes EnergyGuide label electricity rate LabelGasRatedouble $/therm > 0 Yes EnergyGuide label natural gas rate LabelAnnualGasCostdouble $ > 0 Yes EnergyGuide label annual gas cost LabelUsagedouble cyc/wk > 0 Yes EnergyGuide label number of cycles (not used if 301 version < 2019A) Capacitydouble ft3 > 0 Yes Clothes dryer volume
[189] For example, a clothes washer in a shared laundry room of a MF building.
[190] 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.
[191] 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.
If the clothes washer is shared, additional information is entered in /HPXML/Building/BuildingDetails/Appliances/ClothesWasher.
Element Type Units Constraints Required Default Notes AttachedToWaterHeatingSystemidref See [192] Yes ID of attached water heater NumberofUnitsinteger Yes Number of clothes washers in the shared laundry room NumberofUnitsServedinteger Yes Number of dwelling units served by the shared laundry room
[192] AttachedToWaterHeatingSystem must reference a WaterHeatingSystem.
Note
If no clothes washer is located within the Rated Home, a clothes washer in the nearest shared laundry room on the project site shall be used if available for daily use by the occupants of the Rated Home. If there are multiple clothes washers, the clothes washer with the highest Label Energy Rating (kWh/yr) shall be used.
HPXML Clothes Dryer¶
A single clothes dryer can be entered as a /HPXML/Building/BuildingDetails/Appliances/ClothesDryer.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier IsSharedApplianceboolean Yes Whether it serves multiple dwelling units [193] Locationstring See [194] Yes Location FuelTypestring See [195] Yes Fuel type CombinedEnergyFactororEnergyFactordouble lb/kWh > 0 Yes EnergyGuide label efficiency [196] ControlTypestring See [197] See [198] Type of controls
[193] For example, a clothes dryer in a shared laundry room of a MF building.
[194] 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.
[195] FuelType choices are “natural gas”, “fuel oil”, “propane”, “electricity”, “wood”, or “wood pellets”.
[196] 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.
[197] ControlType choices are “timer” or “moisture”.
[198] ControlType only required if ERI Version < 2019A.
If the clothes dryer is shared, additional information is entered in /HPXML/Building/BuildingDetails/Appliances/ClothesDryer.
Element Type Units Constraints Required Default Notes NumberofUnitsinteger Yes Number of clothes dryers in the shared laundry room NumberofUnitsServedintegerYes Number of dwelling units served by the shared laundry room
Note
If no clothes dryer is located within the Rated Home, a clothes dryer in the nearest shared laundry room on the project site shall be used if available for daily use by the occupants of the Rated Home. If there are multiple clothes dryers, the clothes dryer with the lowest Energy Factor or Combined Energy Factor shall be used.
HPXML Dishwasher¶
A single dishwasher can be entered as a /HPXML/Building/BuildingDetails/Appliances/Dishwasher.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier IsSharedApplianceboolean Yes Whether it serves multiple dwelling units [199] Locationstring See [200] Yes Location RatedAnnualkWhorEnergyFactordouble kWh/yr or # > 0 Yes EnergyGuide label consumption/efficiency [201] LabelElectricRatedouble $/kWh > 0 Yes EnergyGuide label electricity rate (not used if 301 version < 2019A) LabelGasRatedouble $/therm > 0 Yes EnergyGuide label natural gas rate (not used if 301 version < 2019A) LabelAnnualGasCostdouble $ > 0 Yes EnergyGuide label annual gas cost (not used if 301 version < 2019A) LabelUsagedouble cyc/wk > 0 Yes EnergyGuide label number of cycles (not used if 301 version < 2019A) PlaceSettingCapacityinteger # > 0 Yes Number of place settings
[199] For example, a dishwasher in a shared mechanical room of a MF building.
[200] 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.
[201] If EnergyFactor (EF) provided instead of RatedAnnualkWh, it will be converted using the following equation based on ANSI/RESNET/ICC 301-2014: RatedAnnualkWh = 215.0 / EF.
If the dishwasher is shared, additional information is entered in /HPXML/Building/BuildingDetails/Appliances/Dishwasher.
Note
If no dishwasher is located within the Rated Home, a dishwasher in the nearest shared kitchen in the building shall be used only if available for daily use by the occupants of the Rated Home. If there are multiple dishwashers, the dishwasher with the lowest Energy Factor (highest kWh/yr) shall be used.
HPXML Refrigerators¶
A single refrigerator can be entered as a /HPXML/Building/BuildingDetails/Appliances/Refrigerator.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier Locationstring See [203] Yes Location RatedAnnualkWhdouble kWh/yr > 0 Yes Annual consumption
[203] 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.
Note
If there are multiple refrigerators, the total energy consumption of all refrigerators/freezers shall be used along with the location that represents the majority of power consumption.
HPXML Dehumidifier¶
Each dehumidifier can be entered as a /HPXML/Building/BuildingDetails/Appliances/Dehumidifier.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier Typestring See [204] Yes Type of dehumidifier Locationstring See [205] Yes Location of dehumidifier Capacitydouble pints/day > 0 Yes Dehumidification capacity IntegratedEnergyFactororEnergyFactordouble liters/kWh > 0 Yes Rated efficiency FractionDehumidificationLoadServeddouble frac 0 - 1 [206] Yes Fraction of dehumidification load served
[204] Type choices are “portable” or “whole-home”.
[205] Location only choice is “living space”.
[206] The sum of all FractionDehumidificationLoadServed(across all Dehumidifiers) must be less than or equal to 1.
Note
Dehumidifiers only affect ERI scores if Version 2019AB or newer is used, as dehumidifiers were incorporated into the ERI calculation as of 301-2019 Addendum B.
Note
Dehumidifiers are currently modeled as located within conditioned space; the model is not suited for a dehumidifier in, e.g., a wet unconditioned basement or crawlspace. Therefore the dehumidifier Location is currently restricted to “living space”.
HPXML Cooking Range/Oven¶
A single cooking range can be entered as a /HPXML/Building/BuildingDetails/Appliances/CookingRange.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier Locationstring See [207] Yes Location FuelTypestring See [208] Yes Fuel type IsInductionboolean Yes Induction range?
[207] 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.
[208] FuelType choices are “natural gas”, “fuel oil”, “propane”, “electricity”, “wood”, or “wood pellets”.
If a cooking range is specified, a single oven is also entered as a /HPXML/Building/BuildingDetails/Appliances/Oven.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier IsConvectionboolean Yes Convection oven?
HPXML Lighting & Ceiling Fans¶
Lighting and ceiling fans are entered in /HPXML/Building/BuildingDetails/Lighting.
HPXML Lighting¶
Nine /HPXML/Building/BuildingDetails/Lighting/LightingGroup elements must be provided, each of which is the combination of:
LightingType: ‘LightEmittingDiode’, ‘CompactFluorescent’, and ‘FluorescentTube’Location: ‘interior’, ‘garage’, and ‘exterior’
Use LightEmittingDiode for Tier II qualifying light fixtures; use CompactFluorescent and/or FluorescentTube for Tier I qualifying light fixtures.
Information is entered in each LightingGroup.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier LightingTypeelement 1 [209] Yes Lighting type Locationstring See [210] Yes See [211] FractionofUnitsInLocationdouble frac 0 - 1 [212] Yes Fraction of light fixtures in the location with the specified lighting type
[209] LightingType child element choices are LightEmittingDiode,CompactFluorescent, orFluorescentTube.
[210] Location choices are “interior”, “garage”, or “exterior”.
[211] Garage lighting is ignored if the building has no garage specified elsewhere.
[212] The sum of FractionofUnitsInLocation for a given Location (e.g., interior) must be less than or equal to 1. If the fractions sum to less than 1, the remainder is assumed to be incandescent lighting.
HPXML Ceiling Fans¶
Each ceiling fan is entered as a /HPXML/Building/BuildingDetails/Lighting/CeilingFan.
Element Type Units Constraints Required Default Notes SystemIdentifierid Yes Unique identifier Airflow[FanSpeed="medium"]/Efficiencydouble cfm/W > 0 Yes Efficiency at medium speed Quantityinteger > 0 Yes Number of similar ceiling fans
HPXML Locations¶
The various locations used in an HPXML file are defined as follows:
Value Description Temperature Building Type outside Ambient environment Weather data Any ground EnergyPlus calculation Any living space Above-grade conditioned floor area EnergyPlus calculation Any attic - vented EnergyPlus calculation Any attic - unvented EnergyPlus calculation Any basement - conditioned Below-grade conditioned floor area EnergyPlus calculation Any basement - unconditioned EnergyPlus calculation Any crawlspace - vented EnergyPlus calculation Any crawlspace - unvented EnergyPlus calculation Any garage Single-family (not shared parking) EnergyPlus calculation Any other housing unit Unrated Conditioned Space Same as conditioned space SFA/MF only other heated space Unrated Heated Space Avg of conditioned space/outside; min of 68F SFA/MF only other multifamily buffer space Multifamily Buffer Boundary Avg of conditioned space/outside; min of 50F SFA/MF only other non-freezing space Non-Freezing Space Floats with outside; minimum of 40F SFA/MF only other exterior Water heater outside Weather data Any exterior wall Ducts in exterior wall Avg of living space/outside Any under slab Ducts under slab (ground) EnergyPlus calculation Any roof deck Ducts on roof deck (outside) Weather data Any
Validating & Debugging Errors¶
When running HPXML files, errors may occur because:
- An HPXML file provided is invalid (either relative to the HPXML schema or the ERI Use Case).
- An unexpected error occurred in the workflow (e.g., applying the ERI 301 ruleset).
- An unexpected EnergyPlus simulation error occurred.
If, for example, the Rated Home is unsuccessful, first look in the ERIRatedHome/run.log for details. If there are no errors in that log file, then the error may be in the EnergyPlus simulation – see ERIRatedHome/eplusout.err.
Contact us if you can’t figure out the cause of an error.
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.
Workflow Outputs¶
Upon completing an ERI or ENERGY STAR calculation, a variety of summary output files and simulation files are available.
ERI Files¶
ERI output files described below are found in the results directory.
See the sample_results_eri directory for examples of these outputs.
ERI_Results.csv¶
The ERI_Results.csv file includes the ERI result as well as the high-level components (e.g., REUL, EC_r, EC_x, IAD_Save) that comprise the ERI calculation.
The file reflects the format of the Results tab of the HERS Method Test spreadsheet.
Note that multiple comma-separated values will be reported for many of these outputs if there are multiple heating, cooling, or hot water systems.
See the example ERI_Results.csv.
ERI_Worksheet.csv¶
The ERI_Worksheet.csv file includes more detailed components that feed into the ERI_Results.csv values.
The file reflects the format of the Worksheet tab of the HERS Method Test spreadsheet.
Note that multiple comma-separated values will be reported for many of these outputs if there are multiple heating, cooling, or hot water systems.
See the example ERI_Worksheet.csv.
ERI______Home.csv¶
A CSV file is written for each of the homes simulated (e.g., ERIReferenceHome.csv for the Reference home).
The CSV file includes the following sections of output.
See the example ERIRatedHome.csv.
Annual Energy Consumption by Fuel Type¶
Fuel uses are listed below.
Type Notes Electricity: Total (MBtu) Electricity: Net (MBtu) Subtracts any power produced by PV or generators. Natural Gas: Total (MBtu) Fuel Oil: Total (MBtu) Propane: Total (MBtu) Wood Cord: Total (MBtu) Wood Pellets: Total (MBtu)
Annual Energy Consumption By End Use¶
End uses are listed below.
Note that all end uses are mutually exclusive – the “Electricity: Heating” end use, for example, excludes energy reported in the “Electricity: Heating Fans/Pumps” end use. So the sum of all end uses for a given fuel (e.g., sum of all “End Use: Natural Gas: *”) equal the above reported fuel use (e.g., “Fuel Use: Natural Gas: Total”).
Type Notes Electricity: Heating (MBtu) Excludes fans/pumps Electricity: Heating Fans/Pumps (MBtu) Electricity: Cooling (MBtu) Excludes fans/pumps Electricity: Cooling Fans/Pumps (MBtu) Electricity: Hot Water (MBtu) Excludes recirc pump and solar thermal pump Electricity: Hot Water Recirc Pump (MBtu) Electricity: Hot Water Solar Thermal Pump (MBtu) Non-zero only when using detailed (not simple) solar thermal inputs Electricity: Lighting Interior (MBtu) Electricity: Lighting Garage (MBtu) Electricity: Lighting Exterior (MBtu) Electricity: Mech Vent (MBtu) Excludes preheating/precooling Electricity: Mech Vent Preheating (MBtu) Shared ventilation preconditioning system Electricity: Mech Vent Precooling (MBtu) Shared ventilation preconditioning system Electricity: Whole House Fan (MBtu) Electricity: Refrigerator (MBtu) Electricity: Dehumidifier (MBtu) Electricity: Dishwasher (MBtu) Electricity: Clothes Washer (MBtu) Electricity: Clothes Dryer (MBtu) Electricity: Range/Oven (MBtu) Electricity: Ceiling Fan (MBtu) Electricity: Television (MBtu) Electricity: Plug Loads (MBtu) Excludes independently reported plug loads (e.g., well pump) Electricity: PV (MBtu) Negative value for any power produced Electricity: Generator (MBtu) Negative value for any power produced Natural Gas: Heating (MBtu) Natural Gas: Hot Water (MBtu) Natural Gas: Clothes Dryer (MBtu) Natural Gas: Range/Oven (MBtu) Natural Gas: Mech Vent Preheating (MBtu) Shared ventilation preconditioning system Natural Gas: Generator (MBtu) Positive value for any fuel consumed Fuel Oil: Heating (MBtu) Fuel Oil: Hot Water (MBtu) Fuel Oil: Clothes Dryer (MBtu) Fuel Oil: Range/Oven (MBtu) Fuel Oil: Mech Vent Preheating (MBtu) Shared ventilation preconditioning system Propane: Heating (MBtu) Propane: Hot Water (MBtu) Propane: Clothes Dryer (MBtu) Propane: Range/Oven (MBtu) Propane: Mech Vent Preheating (MBtu) Shared ventilation preconditioning system Propane: Generator (MBtu) Positive value for any fuel consumed Wood Cord: Heating (MBtu) Wood Cord: Hot Water (MBtu) Wood Cord: Clothes Dryer (MBtu) Wood Cord: Range/Oven (MBtu) Wood Cord: Mech Vent Preheating (MBtu) Shared ventilation preconditioning system Wood Pellets: Heating (MBtu) Wood Pellets: Hot Water (MBtu) Wood Pellets: Clothes Dryer (MBtu) Wood Pellets: Range/Oven (MBtu) Wood Pellets: Mech Vent Preheating (MBtu) Shared ventilation preconditioning system
Annual Building Loads¶
Annual building loads are listed below.
Type Notes Load: Heating: Delivered (MBtu) Includes HVAC distribution losses. Load: Cooling: Delivered (MBtu) Includes HVAC distribution losses. Load: Hot Water: Delivered (MBtu) Includes contributions by desuperheaters or solar thermal systems. Load: Hot Water: Tank Losses (MBtu) Load: Hot Water: Desuperheater (MBtu) Load served by the desuperheater. Load: Hot Water: Solar Thermal (MBtu) Load served by the solar thermal system.
Note that the “Delivered” loads represent the energy delivered by the HVAC/DHW system; if a system is significantly undersized, there will be unmet load not reflected by these values.
Annual Unmet Hours¶
Annual unmet hours are listed below.
Type Notes Unmet Hours: Heating (hr) Number of hours where the heating setpoint is not maintained. Unmet Hours: Cooling (hr) Number of hours where the cooling setpoint is not maintained.
These numbers reflect the number of hours of the year when the conditioned space temperature is more than 0.2 deg-C (0.36 deg-F) from the setpoint during heating/cooling.
Peak Building Electricity¶
Peak building electricity outputs are listed below.
Type Notes Peak Electricity: Winter Total (W) Winter season defined by operation of the heating system. Peak Electricity: Summer Total (W) Summer season defined by operation of the cooling system.
Peak Building Loads¶
Peak building loads are listed below.
Type Notes Peak Load: Heating: Delivered (kBtu) Includes HVAC distribution losses. Peak Load: Cooling: Delivered (kBtu) Includes HVAC distribution losses.
Note that the “Delivered” peak loads represent the energy delivered by the HVAC system; if a system is significantly undersized, there will be unmet peak load not reflected by these values.
Annual Component Building Loads¶
Note: This section is only available if the --add-component-loads argument is used.
The argument is not used by default for faster performance.
Component loads represent the estimated contribution of different building components to the annual heating/cooling building loads. The sum of component loads for heating (or cooling) will roughly equal the annual heating (or cooling) building load reported above.
Component loads disaggregated by Heating/Cooling are listed below.
Type Notes Component Load: *: Roofs (MBtu) Heat gain/loss through HPXML Roofelements adjacent to conditioned spaceComponent Load: *: Ceilings (MBtu) Heat gain/loss through HPXML FrameFloorelements (inferred to be ceilings) adjacent to conditioned spaceComponent Load: *: Walls (MBtu) Heat gain/loss through HPXML Wallelements adjacent to conditioned spaceComponent Load: *: Rim Joists (MBtu) Heat gain/loss through HPXML RimJoistelements adjacent to conditioned spaceComponent Load: *: Foundation Walls (MBtu) Heat gain/loss through HPXML FoundationWallelements adjacent to conditioned spaceComponent Load: *: Doors (MBtu) Heat gain/loss through HPXML Doorelements adjacent to conditioned spaceComponent Load: *: Windows (MBtu) Heat gain/loss through HPXML Windowelements adjacent to conditioned space, including solarComponent Load: *: Skylights (MBtu) Heat gain/loss through HPXML Skylightelements adjacent to conditioned space, including solarComponent Load: *: Floors (MBtu) Heat gain/loss through HPXML FrameFloorelements (inferred to be floors) adjacent to conditioned spaceComponent Load: *: Slabs (MBtu) Heat gain/loss through HPXML Slabelements adjacent to conditioned spaceComponent Load: *: Internal Mass (MBtu) Heat gain/loss from internal mass (e.g., furniture, interior walls/floors) in conditioned space Component Load: *: Infiltration (MBtu) Heat gain/loss from airflow induced by stack and wind effects Component Load: *: Natural Ventilation (MBtu) Heat gain/loss from airflow through operable windows Component Load: *: Mechanical Ventilation (MBtu) Heat gain/loss from airflow/fan energy from a whole house mechanical ventilation system Component Load: *: Whole House Fan (MBtu) Heat gain/loss from airflow due to a whole house fan Component Load: *: Ducts (MBtu) Heat gain/loss from conduction and leakage losses through supply/return ducts outside conditioned space Component Load: *: Internal Gains (MBtu) Heat gain/loss from appliances, lighting, plug loads, water heater tank losses, etc. in the conditioned space
Annual Hot Water Uses¶
Annual hot water uses are listed below.
Type Notes Hot Water: Clothes Washer (gal) Hot Water: Dishwasher (gal) Hot Water: Fixtures (gal) Showers and faucets. Hot Water: Distribution Waste (gal)
Timeseries Outputs¶
See the Running ERI section for requesting timeseries outputs.
When requested, a CSV file of timeseries outputs is written for the Reference/Rated Homes (e.g., ERIReferenceHome_Hourly.csv, ERIReferenceHome_Daily.csv, or ERIReferenceHome_Monthly.csv for the Reference home).
Depending on the outputs requested, CSV files may include:
Type Notes Fuel Consumptions Energy use for each fuel type (in kBtu for fossil fuels and kWh for electricity). End Use Consumptions Energy use for each end use type (in kBtu for fossil fuels and kWh for electricity). Hot Water Uses Water use for each end use type (in gallons). Total Loads Heating, cooling, and hot water loads (in kBtu) for the building. Component Loads Heating and cooling loads (in kBtu) disaggregated by component (e.g., Walls, Windows, Infiltration, Ducts, etc.). Zone Temperatures Average temperatures (in deg-F) for each space modeled (e.g., living space, attic, garage, basement, crawlspace, etc.). Airflows Airflow rates (in cfm) for infiltration, mechanical ventilation, natural ventilation, and whole house fans. Weather Weather file data including outdoor temperatures, relative humidity, wind speed, and solar.
Timeseries outputs can be one of the following frequencies: hourly, daily, or monthly.
Timestamps in the output use the end-of-hour (or end-of-day for daily frequency, etc.) convention. Most outputs will be summed over the hour (e.g., energy) but some will be averaged over the hour (e.g., temperatures, airflows).
See the example ERIRatedHome_Hourly.csv.
ERI______Home.xml¶
An HPXML file is written for each of the homes simulated (e.g., ERIReferenceHome.xml for the Reference home).
The file reflects the configuration of the home after applying the ERI 301 ruleset.
The file will also show HPXML default values that are applied as part of modeling this home. Defaults will be applied for a few different reasons:
- Optional ERI inputs aren’t provided (e.g., ventilation rate for a vented attic, SHR for an air conditioner, etc.)
- Modeling assumptions (e.g., 1 hour timestep, Jan 1 - Dec 31 run period, appliance schedules, etc.)
- HVAC sizing calculations (e.g., autosized HVAC capacities and airflow rates, heating/cooling design loads)
Any HPXML-defaulted values will include the dataSource='software' attribute.
See the example ERIRatedHome.xml.
Simulation Files¶
In addition, raw EnergyPlus simulation input/output files are available for each simulation (e.g., ERIRatedHome, ERIReferenceHome, etc. directories).
Warning
It is highly discouraged for software tools to read the raw EnergyPlus output files. The EnergyPlus input/output files are made available for inspection, but the outputs for certain situations can be misleading if one does not know how the model was created. If there are additional outputs of interest that are not available in our summary output files, please send us a request.
See the example ERIRatedHome directory.
ENERGY STAR Files¶
ENERGY STAR output files described below are found in the results directory.
See the sample_results_energystar directory for examples of these outputs.
ES_Results.csv¶
The ES_Results.csv file includes the following:
Output Notes Reference Home ERI ERI of the ES Reference Home SAF (Size Adjustment Factor) Can only be less than 1 for some ES programs/versions SAF Adjusted ERI Target Reference Home ERI multiplied by SAF Rated Home ERI ERI of the Rated Home including OPP as allowed by the ES program/version Rated Home ERI w/o OPP ERI of the Rated Home excluding any on-site power production (OPP) ENERGY STAR Certification PASS or FAIL
See the example ES_Results.csv.
ES______.xml¶
An HPXML file is written for the ENERGY STAR Reference Home (ESReference.xml) and the Rated Home (ESRated.xml).
The file reflects the configuration of the home after applying the ENERGY STAR ruleset.
See the example ESReference.xml.
ERI Directories¶
Two directories are created under results, one called ESRerence and one called ESRated.
Each directory has the full set of ERI Files corresponding to the ERI calculation of the ES Reference Home and Rated Home.
See the example ESReference directory.
Testing Framework¶
A large number of tests are automatically run for every code change in the GitHub repository.
The current set of tests include:
- Successful ERI calculations for all sample files
- RESNET® ANSI/ASHRAE Standard 140-2011, Class II, Tier 1 Tests
- RESNET HERS® Reference Home auto-generation tests
- RESNET HERS Index Adjustment Design auto-generation tests
- RESNET HERS method tests
- RESNET HVAC tests
- RESNET Duct distribution system efficiency tests
- RESNET Hot water system performance tests
- EPA Tests for ENERGY STAR
If you are seeking to develop RESNET Accredited Rating Software, you will need to submit your final software product to RESNET for accreditation.
Running Tests Locally¶
All tests can be run locally using:
openstudio energy_rating_index_test.rb
Individual tests (any method in workflow/tests/energy_rating_index_test.rb that begins with “test_”) can also be run.
For example:
openstudio energy_rating_index_test.rb --name=test_resnet_hers_method
All current HERS tests can be run using as follows:
openstudio energy_rating_index_test.rb --name=test_resnet_ashrae_140openstudio energy_rating_index_test.rb --name=test_resnet_hers_reference_home_auto_generationopenstudio energy_rating_index_test.rb --name=test_resnet_hers_methodopenstudio energy_rating_index_test.rb --name=test_resnet_hvacopenstudio energy_rating_index_test.rb --name=test_resnet_dseopenstudio energy_rating_index_test.rb --name=test_resnet_hot_waterEPA tests for ENERGY STAR can be run using:
openstudio energy_rating_index_test.rb --name=test_epaTest results in CSV format are created at workflow/tests/test_results. For many RESNET tests, the Excel spreadsheet test criteria are also implemented in code to automate the process of checking for test failures. All simulation/HPXML/etc. files generated from running the tests can be found inside the workflow/tests/test_files directory.
At the completion of the test, there will also be output that denotes the number of failures/errors like so:
Finished in 36.067116s, 0.0277 runs/s, 0.9704 assertions/s.
1 runs, 35 assertions, 0 failures, 0 errors, 0 skips
Software developers may find it convenient to export HPXML files with the same name as the test files included in the repository. This allows issuing the same commands above to generate test results.
Official Test Results¶
The official OpenStudio-ERI test results can be found in any release or any checkout of the code at workflow/tests/base_results.
The results are based on using the HPXML files found under workflow/tests.
Packaging¶
The OpenStudio-ERI workflow is cross-platform and can be used in web or desktop applications.
Web Applications¶
Using the OpenStudio-ERI workflow in a web application is very straightforward.
First, OpenStudio must be available. Web applications may wish to use the nrel/openstudio docker image. Alternatively, the OpenStudio installer can be executed on the web server – only the EnergyPlus and Command Line Interface (CLI) components are required.
Then grab the latest OpenStudio-ERI release.
Desktop Applications¶
The OpenStudio-ERI workflow can also be packaged into a third-party software installer for distribution to desktop users.
First, OpenStudio must be bundled – only the EnergyPlus and Command Line Interface (CLI) components are required.
Either the OpenStudio setup file can be automatically run as part of your install, or the OpenStudio application can be installed to a local computer and its contents can be re-bundled in your installer (there are no external dependencies required).
The only required OpenStudio contents are the openstudio/bin and openstudio/EnergyPlus directories.
Then grab the latest OpenStudio-ERI release.