HPXML to Home Energy Score Documentation

Introduction

HPXML is a flexible way to transfer home energy audit and retrofit data via a standardized schema. This flexibility, one if its greatest strengths, is also a weakness. Home Energy Score (HEScore) requires very specific data points to be reported as inputs to the API. Many of those data points can be represented in the HPXML syntax in multiple ways due to the flexibility of the standard. The purpose of this guide is to document the assumptions that are made in the translation of HPXML data elements into HEScore software inputs.

Usage Instructions

The HPXML to Home Energy Score (HEScore) translator can be run hosted through the HEScore API or directly on your local machine. Most users will find that the HEScore API is the preferred method since it easily fits into the API workflow and automates the process. The stand alone method is mostly for developers needing to debug and track down problems in the translation as well as for those who want to make modifications to the translation assumptions and code.

Home Energy Score API

The HEScore API provides the most generally applicable way use HPXML to generate a Home Energy Score. Generally in the API is used by doing the following steps, calling each API method in order:

  1. submit_address - Creates a new building and assessment date.
  2. submit_inputs - Submit a detailed house description in a format specific to Home Energy Score.
  3. calculate_base_building - Calculates the energy use of the as-described building.
  4. commit_results - Locks the inputs and marks them as being accurate by the Qualified Assessor.
  5. calculate_package_building - Analyzes a set of retrofit upgrades that are screened against standardized costs, and determines the most cost effective ones.
  6. generate_label - Creates a PDF and PNG Home Energy Score label.

There are other options and reports available, but that is the general gist of it. The HPXML translator is made available through a separate API method: submit_hpxml_inputs. It replaces the first two steps above, alleviating the need to translate data elements from your data structure into the HEScore data structure.

submit_hpxml_inputs accepts an HPXML file as a Base64 encoded payload, so you will need to convert it. An example of how to do this in Python is:

import base64

with open('path/to/hpxmlfile.xml','r') as f:
    hpxml_as_base64 = base64.standard_b64encode(f.read())

Similar libraries and functionality exist in many languages.

Much more information on how to use the HEScore API including the submit_hpxml_inputs method is available on the Home Energy Scoring Tool API Documentation site.

Stand Alone

The HPXML to HEScore translator that is used within the Home Energy Score API can be used independently as well. It is a Python script that accepts an HPXML file as input and returns a JSON file with HEScore inputs arranged like the HEScore API call submit_inputs expects. It it useful to run it this way for debugging a translation of your particular flavor of HPXML file or for development of the translator.

Set Up

The program runs using Python 2.7. The instructions below will help you set up Python on your platform and get the translator installed.

Windows
  1. Download Python 2.7.x (not the 3.x version) from python.org and Install.
  2. Add C:\Python27 to your path. Here’s how.
  3. Follow instructions for All Platforms.
Mac OS X
  1. Install Homebrew.
  2. Open a terminal.
  3. Install Python 2.7 using homebrew: brew install python
  4. Follow instructions for All Platforms.
Linux
  1. Install Python 2.7 using the package manager for your platform.
  2. Follow instructions for All Platforms.
All Platforms

Optionally install and activate a virtual environment. Instructions here.

Install the package using pip:

pip install hescore-hpxml

Alternatively, you can install the latest and greatest directly from GitHub, which is useful if you’re going to do some development on the translator. To do so, get a copy of the source code from GitHub, using your preferred method. If you’re not sure, just click “Download ZIP”.

Open a terminal and use pip to install it in developer mode:

cd path/to/hescore-hpxml
pip install -e .[dev]

Running the Translator

The best way to figure out how to run the translator is to call it with the -h flag.

hpxml2hescore -h

Translation Assumptions

Contents:

Address and Requesting a New Session

The first step in starting a HEScore transaction is to call the submit_address API call.

Address

The building address is found in HPXML under the Building/Site/Address element. The sub elements there easily translate into the expected address format for HEScore.

<HPXML>
   ...
   <Building>
      <Site>
         <SiteID id="id1"/>
         <Address>
            <Address1>123 Main St.</Address1>
            <Address2></Address2>
            <CityMunicipality>Anywhere</CityMunicipality>
            <StateCode>CA</StateCode>
            <ZipCode>90000</ZipCode>
         </Address>
      </Site>
   </Building>
</HPXML>

HPXML allows for two lines of address elements. If both are used, the lines will be concatenated with a space between for submission to the HEScore building_address.address field. All of the HPXML elements shown in the above code snippet are required with the exception of Address2

Assessment Type

To begin a HEScore session an assessment type must be selected. The assessment type is determined from HPXML via the XMLTransactionHeaderInformation/Transaction and Building/ProjectStatus/EventType element using the following mapping:

Assessment Type mapping
XML Transaction Type HPXML Event Type HEScore Assessment Type
create audit initial
proposed workscope alternative
approved workscope alternative
construction-period testing/daily test out test
job completion testing/final inspection final
quality assurance/monitoring qa
preconstruction preconstruction
update any corrected
Mentor Assessment Type

In v2015 HEScore introduced a new assessment type called “mentor”. It is used for new assessors in training when an assessment is supervised by a more qualified assessor. There is no equivalent way to communicate this scenario in HPXML. To work around this issue, the translator will look for a specifically named element in the extension of Building/ProjectStatus:

<ProjectStatus>
    <EventType>audit</EventType>
    <Date>2014-12-18</Date>
    <extension>
        <HEScoreMentorAssessment/>
    </extension>
</ProjectStatus>

Upon finding this HEScoreMentorAssessment element, the HEScore assessment type will be set to “mentor” regardless of the mapping above.

Home Performance with Energy Star

Inputs for the Home Energy Score submit_hpwes API call can be retrieved from an HPXML file as described below.

Identifying HPwES Projects

To trigger data collection for HPwES project, the following elements need to be included depending on HPXML version used.

HPXML v2

To translate the HPwES fields, the Project/ProgramCertificate must be present and equal to Home Performance with Energy Star.

HPXML v3

In HPXML v3.0+, ProgramCertificate no longer exists and a new element of path Building/BuildingDetails/GreenBuildingVerifications/GreenBuildingVerification is used. Similarly, GreenBuildingVerification must be present as Home Performance with ENERGY STAR.

Project

To get the Home Performance with Energy Star (HPwES) data from an HPXML file a Project node needs to be included. The following elements are required under the Project node:

<Project>
    <ProjectDetails>
        <ProjectSystemIdentifiers id="projectid"/>
        <!-- HPXML v2 only --><ProgramCertificate>Home Performance with Energy Star</ProgramCertificate>
        <StartDate>2018-08-20</StartDate>
        <CompleteDateActual>2018-12-14</CompleteDateActual>
    </projectDetails>
</Project>

If more than one Project element exists, the first one will be used. The user can override this by passing the --projectid argument to the translator command line.

The project fields are mapped as follows:

HPXML ProjectDetails submit_hpwes API value
StartDate improvement_installation_start_date
CompleteDateActual improvement_installation_completion_date

Contractor

A Contractor element is also required with at minimum the following elements:

<Contractor>
    <ContractorDetails>
        <SystemIdentifier id="contractor1"/>
        <BusinessInfo>
            <SystemIdentifier id="contractor1businessinfo"/>
            <BusinessName>My HPwES Contractor Business</BusinessName>
            <extension>
                <ZipCode>12345</ZipCode>
            </extension>
        </BusinessInfo>
    </ContractorDetails>
</Contractor>

If there are more than one Contractor elements, the contractor with the id passed in the --contractorid command line argument is used. If no contracter id is specified by the user, the contractor listed in the Building/ContractorID will be used. If that element isn’t available, the first Contractor element will be used.

The contractor fields are mapped as follows:

HPXML Contractor submit_hpwes API value
ContractorDetails/BusinessInfo/BusinessName contractor_business_name
ContractorDetails/BusinessInfo/extension/ZipCode contractor_zip_code

About

Assessment Date

HEScore requires an assessment date. If a date is stored in the element Building/ProjectStatus/Date, that date is used. If not, the current date is used.

External Building ID

The value of Building/extension/HESExternalID or Building/BuildingID/SendingSystemIdentifierValue, if present, is copied into the building.about.external_building_id field in HEScore. Preference is given to the extension element if both are present. This is optional, but may be useful for those wanting to pass an additional building identifier for their own tracking purposes.

Building Shape

HEScore requires specifying whether the building is a detached house or a town house through their building.shape input. HPXML can specify this (and a variety of other house types) through the Building/BuildingSummary/BuildingConstruction/ResidentialFacilitytype data element. Not all facility types in HPXML can be modeled in HEScore. The table below shows how the possible enumerations of the HPXML field are translated into HEScore.

HPXML Facility Types to HEScore Building Shape
HPXML HEScore
single-family detached rectangle
single-family attached town_house
manufactured home not translated
2-4 unit building not translated
5+ unit building not translated
multi-family - uncategorized not translated
multi-family - town homes town_house
multi-family - condos not translated
apartment unit not translated
studio unit not translated
other not translated
unknown not translated

Note

For enumerations that are not translated the HPXML file will fail to run in HEScore.

For town houses HEScore requires a town_house_walls input to be specified. This is available in HPXML in the Building/BuildingSummary/Site/Surroundings element. The translation of the enumerations is as follows:

Mapping for shared walls in town houses
HPXML HEScore
stand-alone not translated
attached on one side back_right_front or back_front_left
attached on two sides back_front
attached on three sides not translated

If the HPXML enumeration of attached on one side is present the translation will determine which HEScore enumeration to select based on which side of the house is missing windows.

Warning

  • If windows are found on a shared town house wall, the translation will fail.
  • HEScore cannot model townhouses that are “attached on three sides” or “stand-alone”. Using one of those inputs will result in a translation error.

Year Built, Stories, Bedrooms, Floor Height, and Floor Area

The HEScore inputs year_built, number_bedrooms, num_floor_above_grade, floor_to_ceiling_height, and conditioned_floor_area are each retrieved from their corresponding HPXML elements shown below.

<HPXML>
   ...
   <Building>
     ...
     <BuildingDetails>
         <BuildingSummary>
             <BuildingConstruction>
                 <YearBuilt>1998</YearBuilt>
                 <ConditionedFloorArea>2400</ConditionedFloorArea>
                 <NumberofConditionedFloorsAboveGrade>2</NumberofConditionedFloorsAboveGrade>
                 <AverageCeilingHeight>8</AverageCeilingHeight>
                 <NumberofBedrooms>3</NumberofBedrooms>
             </BuildingConstruction>
         </BuildingSummary>
     </BuildingDetails>
   </Building>
</HPXML>

The HEScore input floor_to_ceiling_height will be calculated by dividing ConditionedBuildingVolume by ConditionedFloorArea if AverageCeilingHeight is omitted.

House Orientation

In HPXML the orientation of a house and orientations in general can be specified as either a compass direction (‘North’,’Southwest’,etc.) or an azimuth measured in degrees clockwise from North. HEScore requires a compass direction for the orientation of the front of the house. If the azimuth is available in Building/BuildingDetails/BuildingSummary/Site/AzimuthOfFrontOfHome the nearest compass direction is chosen. If the azimuth is omitted from HPXML but the OrientationOfFronOfHome element exists, the orientation is used.

Infiltration

HPXML allows the specification of multiple Building/BuildingDetails/Enclosure/AirInfiltration/AirInfiltrationMeasurement elements, which can contain either a blower door test or a qualitative assessment of “leakiness”. HEScore can be used with either a measurement from a blower door test or by specifying whether the house has been air sealed or not (boolean). Preference is given to a blower door test measurement when it is available in HPXML.

Blower Door Test

The translator first looks for a blower door test (not an estimate) with units of CFM50. If more than one of the AirInfiltrationMeasurement elements have units in CFM50, the last one to appear in the document is used. If there are no measurements in CFM50, it will look for one in ACH50. If more than one of the AirInfiltrationMeasurement elements have units in ACH50, the last one to appear in the document is used. If the UnitofMeasure element has a value of ACH, then the value is converted to CFM using the building volume calculated by the floor area and floor height.

An example of the minimum expected elements in HPXML follows:

<AirInfiltrationMeasurement>
   <SystemIdentifier id="infilt1"/>
   <TypeOfInfiltrationMeasurement>blower door</TypeOfInfiltrationMeasurement>
   <HousePressure>50</HousePressure><!-- Must be 50 -->
   <BuildingAirLeakage>
      <UnitofMeasure>CFM<!-- or ACH --></UnitofMeasure>
      <AirLeakage>1234</AirLeakage>
   </BuildingAirLeakage>
</AirInfiltrationMeasurement>
Air Sealing Present

When a blower door test is not available the translator looks for an AirInfiltrationMeasurement that specifies an estimate of leakage. An example of the minimum expected elements in that case looks like:

<AirInfiltrationMeasurement>
   <SystemIdentifier id="infilt2"/>
   <TypeOfInfiltrationMeasurement>estimate</TypeOfInfiltrationMeasurement>
   <LeakinessDescription>tight</LeakinessDescription>
</AirInfiltrationMeasurement>

If more than one AirInfiltrationMeasurement is found that have the above elements, the last one to appear in the document is used. Whether the house is marked as having air sealing present is determined according to the following mapping from LeakinessDescription:

HPXML LeakinessDescription to HEScore Air Sealing Present
Leakiness Description Air Sealing Present
very tight True
tight True
average False
leaky False
very leaky False

If none of the AirInfiltrationMeasurement elements meet the criteria above to specify an estimate, the building is assumed to not have air sealing present.

Note

If a building has no AirInfiltrationMeasurement elements in the HPXML document, the house is assumed to not be air sealed.

Comments

The hpxml-hescore translator allows passing through comments. Since there’s no equivalent way to communicate this information in HPXML under the Building node, the translator will look for a specifically named element in extension of Building:

<Building>
    <extension>
        <Comments>Any comment</Comments>
    </extension>
</Building>

If there’s no comment found in extension element, the translator will look for the Project/ProjectDetails/Notes element for comments. Only the first Project node will be selected. For complicated cases where buildings are assigned to multiple projects, using the extension element is recommended.

Roof and Attic

HPXML allows the specification of multiple Attic elements, each of which relates to one (HPXML v2) or more (HPXML v3) Roof elements. That relation is optional in HPXML, but is required for HEScore when there is more than one Attic or Roof because it is important to know which roof relates to each attic space. An area is required for each Attic if there is more than one Attic element.

  • In HPXML v2, areas can be specified directly by Attic/AtticArea.
  • In HPXML v3, translator first searches all the Area of FrameFloor whose id is the same as what referred in Attic/AttachedToFrameFloor, and sums all areas up. Otherwise, the Area of Roof whose id is the same as what referred in Attic/AttachedToRoof will be searched and summed for each attic.

If there is only one Attic element, the footprint area of the building is assumed. If there’s only one roof in HPXML, it will be automatically attached to attic.

Attic/Roof Type

Each Attic is considered and the AtticType is mapped into a HEScore roof type according to the following mapping.

HPXML Attic Type to HEScore Roof type mapping (HPXML v2)
HPXML HEScore
cape cod cath_ceiling
cathedral ceiling cath_ceiling
flat roof cath_ceiling
unvented attic vented_attic
vented attic vented_attic
venting unknown attic vented_attic
other see note below
HPXML Attic Type to HEScore Roof type mapping (HPXML v3)
HPXML HEScore
CathedralCeiling cath_ceiling
FlatRoof cath_ceiling
Attic/CapeCod = ‘true’ cath_ceiling
Attic/Conditioned = ‘true’ cond_attic
Attic vented_attic
Other not translated

Note

Prior to HPXML v3, there’s no existing HPXML element capturing a conditioned attic. The only way to model a HEScore cond_attic is to specify HPXML Attic Type to be other with an extra element Attic/extension/Conditioned to be true.

Otherwise, HPXML Attic Type other will not be translated and will result in a translation error.

HEScore can accept up to two attic/roof constructions. If there are more than two specified in HPXML, the properties of the Attic elements with the same roof type are combined. For variables with a discrete selection the value that covers the greatest combined area is used. For R-values a calculation is performed to determine the equivalent overall R-value for the attic. This is discussed in more detail in Roof R-value.

Note

Starting from HPXML v3, HPXML allows multiple floors/roofs attached to a single attic. The properties of the floors/roofs attached to the same attic are combined into a single one.

Roof Color

Roof color in HEScore is mapped from the HPXML Roof/RoofColor element according to the following mapping.

HPXML to HEScore roof color mapping
HPXML HEScore
light light
medium medium
medium dark medium_dark
dark dark
reflective white

If the Roof/SolarAbsorptance element is present, the HEScore roof color is set to “cool_color” and the recorded absorptance will be sent to HEScore under the “roof_absorptance” element.

Note

Starting from HPXML v3, if there’re more than one roof attached to the same attic, the roof color of that covers greatest area will be selected.

Exterior Finish

HPXML stores the exterior finish information in the Roof/RoofType element. This is translated into the HEScore exterior finish variable according to the following mapping.

HPXML Roof Type to HEScore Exterior Finish mapping
HPXML HEScore
shingles composition shingles
slate or tile shingles concrete tile
wood shingles or shakes wood shakes
asphalt or fiberglass shingles composition shingles
metal surfacing composition shingles
expanded polystyrene sheathing not translated
plastic/rubber/synthetic sheeting tar and gravel
concrete concrete tile
cool roof not translated
green roof not translated
no one major type not translated
other not translated

Note

Items where the HEScore translation indicates not translated above will result in a translation error.

Rigid Foam Sheathing

If the AtticRoofInsulation element has a Layer with the “continuous” InstallationType, InsulationMaterial/Rigid, and a NominalRValue greater than zero, the roof is determined to have rigid foam sheathing and one of the construction codes is selected accordingly. Otherwise one of the standard wood frame construction codes is selected.

HPXML v2
<Attic>
    <SystemIdentifier id="attic5"/>
    <AttachedToRoof idref="roof3"/>
    <AtticType>cathedral ceiling</AtticType>
    <AtticRoofInsulation>
        <SystemIdentifier id="attic5roofins"/>
        <Layer>
            <InstallationType>continuous</InstallationType>
            <InsulationMaterial>
                <Rigid>eps</Rigid>
            </InsulationMaterial>
            <NominalRValue>10</NominalRValue>
        </Layer>
    </AtticRoofInsulation>
    <Area>2500</Area>
</Attic>
HPXML v3
<Atics>
   <Attic>
      <SystemIdentifier id="attic5"/>
      <AtticType>
         <CathedralCeiling/>
      </AtticType>
      <AttachedToRoof idref="roof3"/>
   </Attic>
</Attics>
<Roofs>
   <Roof>
      <SystemIdentifier id="roof3"/>
      <Area>2500</Area>
      <Insulation>
           <SystemIdentifier id="attic5roofins"/>
           <Layer>
               <InstallationType>continuous</InstallationType>
               <InsulationMaterial>
                   <Rigid>eps</Rigid>
               </InsulationMaterial>
               <NominalRValue>10</NominalRValue>
           </Layer>
       </Insulation>
   </Roof>
<Roofs>

Radiant Barrier

If the Roof/RadiantBarrier element exists and has a “true” value, the attic is assumed to have a radiant barrier and no roof deck insulation is assumed according to the construction codes available in HEScore.

Roof R-value

R-values for the roof deck are added up by summing the values of the Layer/NominalRValue. If the roof construction was determined to have Rigid Foam Sheathing, an R-value of 5 is subtracted from the roof R-value sum to account for the R-value of the sheathing in the HEScore construction.

Starting from HPXML v3, multiple roofs are allowed to be attached to the same attic, if the attic has more than one Roof element with roof insulation, the insulation values are combined by first selecting the nearest roof center-of-cavity R-value for each roof area from the table below.

Roof Center-of-Cavity Effective R-values
Exterior Composition or Metal Wood Shakes Clay Tile Concrete Tile Tar and Gravel
R-value Effective R-value
Standard
R-0 2.7 3.2 2.2 2.3 2.3
R-11 13.6 14.1 13.2 13.2 13.2
R-13 15.6 16.1 15.2 15.2 15.2
R-15 17.6 18.1 17.2 17.2 17.2
R-19 21.6 22.1 21.2 21.2 21.2
R-21 23.6 24.1 23.2 23.2 23.2
R-27 29.6 30.1 29.2 29.2 29.2
R-30 32.6 33.1 32.2 32.2 32.2
w/ Radiant Barrier
R-0 5 5.5 4.5 4.6 4.6
w/ foam sheeting
R-0 6.8 7.3 6.4 6.4 6.4
R-11 17.8 18.3 17.4 17.4 17.4
R-13 19.8 20.3 19.4 19.4 19.4
R-15 21.8 22.3 21.4 21.4 21.4
R-19 25.8 26.3 25.4 25.4 25.4
R-21 27.8 28.3 27.4 27.4 27.4

Then a weighted average is calculated by weighting the U-values by area. This averaged Center-of-Cavity Effective R value is combined from all roofs attached to the same attic. The highest weighted roof construction type is selected to represent properties of the attic.

\begin{align*} U_i &= \frac{1}{R_i} \\ U_{eff,avg} &= \frac{\sum_i{U_i A_i}}{\sum_i A_i} \\ R_{eff,avg} &= \frac{1}{U_{eff,avg}} \\ \end{align*}

If the house has more than two attics specified, the attics of the same roof types are combined. Therefore, the same weighted average calculation is performed (taking roof-level averaged R as \(R_{i}\) and attic area determined in attic area as \(A_{i}\)) to combine multiple attics.

Then the R-0 effective center-of-cavity R-value (\(R_{offset}\)) is selected for highest weighted roof construction type for the attic represented in the calculation and is subtracted from \(R_{eff,avg}\).

\[R = R_{eff,avg} - R_{offset}\]

Finally the R-value is rounded to the nearest insulation level in the enumeration choices for the highest weighted roof construction type for the attic is included in the calculation.

Attic R-value

Determining the attic floor insulation levels uses the same procedure as Roof R-value except the lookup table is different. The attic floor center-of-cavity R-values are each R-0.5 greater than the nominal R-values in the enumeration list.

If the primary roof type is determined to be a cathedral ceiling, then an attic R-value is not calculated.

Knee Walls

In HPXML v2, knee walls are specified via the Attic/AtticKneeWall element.

Starting from HPXML v3, knee walls are specified via wall attachment in Attic/AttachedToWall. The attached wall must have AtticWallType of “knee wall”. See below an example:

<Attics>
   <Attic>
      <SystemIdentifier id="attic5"/>
      <AtticType>
         <Attic>
            <Vented>true</Vented>
         </Attic>
      </AtticType>
      <AttachedToRoof idref="roof3"/>
      <AttachedToWall idref="kneewall"/>
      <AttachedToFrameFloor idref="framefloor"/>
   </Attic>
</Attics>
<Walls>
   <Wall>
      <SystemIdentifier id="kneewall"/>
      <ExteriorAdjacentTo>attic</ExteriorAdjacentTo>
      <AtticWallType>knee wall</AtticWallType>
      <WallType>
         <WoodStud/>
      </WallType>
      <Area>200</Area>
      <Insulation>
           <SystemIdentifier id="kneewallins"/>
           <Layer>
               <InstallationType>cavity</InstallationType>
               <NominalRValue>10</NominalRValue>
           </Layer>
       </Insulation>
   </Wall>
<Walls>

If an attic has knee walls specified, the area of the knee walls will be added to the attic floor area. The knee walls center-of-cavity R-value is R-1.8 greater than the nominal R-value. The knee walls center-of-cavity R-value will be reflected in the area weighted center-of-cavity effective R-value of the attic floor. This averaged center-of-cavity effective R value is combined from all knee walls and attic floors attached to the same attic. The highest weighted attic floor construction type is selected.

Foundation Insulation

Determining the primary foundation

HEScore permits the specification of two foundations. The two foundations that cover the largest area are selected. This is determined by summing up the area of the FrameFloor or Slab elements (depending on what kind of foundation it is). Area elements are required for all foundations unless there is only one foundation, then it is assumed to be the footprint area of the building. If there are more than two foundations, the areas of the largest two are scaled up to encompass the area of the remaining foundations while maintaining their respective area fractions relative to each other.

Foundation Type

Once a foundation is selected, the HEScore foundation type is selected from HPXML according to the following table.

HPXML to HEScore foundation type mapping
HPXML Foundation Type HEScore Foundation Type
Basement Conditioned=”true” cond_basement
Conditioned=”false” or omitted uncond_basement
Crawlspace Vented=”true” vented_crawl
Vented=”false” or omitted unvented_crawl
SlabOnGrade slab_on_grade
Garage unvented_crawl
AboveApartment not translated
Combination not translated
Ambient vented_crawl
RubbleStone not translated
Other not translated

Warning

For foundation types that are not translated the translation will return an error.

Foundation wall insulation R-value

If the foundation type is a basement or crawlspace, an area weighted average R-value is calculated for the foundation walls. The area is obtained from the Area element, if present, or calculated from the Length and Height elements. The R-value is the sum of the FoundationWall/Insulation/Layer/NominalRValue element values for each foundation wall. For each foundation wall, an effective R-value is looked up based on the nearest R-value in the following table.

Basement and crawlspace wall effective R-values
Insulation Level Effective R-value
R-0 4
R-11 11.6
R-19 16.9

Then a weighted average R-value is calculated by weighting the U-values by area.

\begin{align*} U_i &= \frac{1}{R_i} \\ U_{eff,avg} &= \frac{\sum_i{U_i A_i}}{\sum_i A_i} \\ R_{eff,avg} &= \frac{1}{U_{eff,avg}} \\ \end{align*}

The effective R-value of the R-0 insulation level is then subtracted.

\[R = R_{eff,avg} - 4.0\]

Finally, the nearest insulation level is selected from the enumeration list.

Slab insulation R-value

If the foundation type is a slab on grade, an area weighted average R-value is calculated using the value of ExposedPerimeter as the area. (The units work out, the depth in the area drops out of the equation.) The R-value is the sum of the Slab/PerimeterInsulation/Layer/NominalRValue element values for each foundation wall. For each slab, an effective R-value is looked up based on the nearest R-value in the following table.

Slab insulation effective R-values
Insulation Level Effective R-value
R-0 4
R-5 7.9

Then a weighted average R-value is calculated by weighting the U-values by area.

\begin{align*} U_i &= \frac{1}{R_i} \\ U_{eff,avg} &= \frac{\sum_i{U_i A_i}}{\sum_i A_i} \\ R_{eff,avg} &= \frac{1}{U_{eff,avg}} \\ \end{align*}

The effective R-value of the R-0 insulation level is then subtracted.

\[R = R_{eff,avg} - 4.0\]

Finally, the nearest insulation level is selected from the enumeration list.

Floor insulation above basement or crawlspace

If the foundation type is a basement or crawlspace, for each frame floor above the foundation, a weighted average using the floor area and R-value are calculated. The area is obtained from the Area element. The R-value is the sum of the FrameFloor/Insulation/Layer/NominalRValue element values for each frame floor. The effective R-value is looked up in the following table.

Floor center-of-cavity effective R-value
Insulation Level Effective R-value
R-0 4
R-11 15.8
R-13 17.8
R-15 19.8
R-19 23.8
R-21 25.8
R-25 31.8
R-30 37.8
R-38 42.8

Then a weighted average R-value is calculated by weighting the U-values by area.

\begin{align*} U_i &= \frac{1}{R_i} \\ U_{eff,avg} &= \frac{\sum_i{U_i A_i}}{\sum_i A_i} \\ R_{eff,avg} &= \frac{1}{U_{eff,avg}} \\ \end{align*}

The effective R-value of the R-0 insulation level is then subtracted.

\[R = R_{eff,avg} - 4.0\]

Finally, the nearest insulation level is selected from the enumeration list.

Walls

Wall Orientation

The flexibility of HPXML allows specification of any number of walls and windows facing any direction. HEScore expects only one wall/window specification for each side of the building (front, back, left, right).

Each wall in the HPXML document that has an ExteriorAdjacentTo='ambient' (HPXML v2) or ExteriorAdjacentTo='outside' (HPXML v3) or is missing the ExteriorAdjacentTo subelement (assumed to be ambient/outside) is considered for translation to HEScore. This excludes attic knee walls (see Knee Walls), interior walls, walls between living space and a garage, etc. since HEScore does not model those walls. The translator then attempts to assign each wall to the nearest side of the building, which is relative to the orientation of the front of the building. The wall construction and exterior finish of the largest wall by area on each side of the building are used to define the properties sent to HEScore. An area weighted R-value of all the walls on each side of the building is calculated as well as described in Area Weighted Wall R-value. If there is only one wall on any side of the house, the area is not required for that side. If a wall falls exactly between two sides of the house the area of the wall is divided by two and half of the wall is assigned to either side.

HEScore also allows the specification of one wall for all sides of the building. If none of the walls in HPXML have orientation (or azimuth) data, the wall construction and exterior finish of the largest wall by area on each side of the building are used to define the properties sent to HEScore. An area weighted R-value of all the walls on each side of the building is calculated as well as described in Area Weighted Wall R-value. If there is only one wall and no area specified, that wall is used to determine the wall construction.

Note

The following conditions must be met for the wall translation to succeed:

  • If there is more than one wall on each side of the building each wall on that side of the building must have an Area specified.
  • Either all walls must have an Azimuth and/or Orientation or none of them must.

Wall Construction

HEScore uses a selection of construction codes to describe wall construction type, insulation levels, and siding. HPXML, as usual, uses a more flexible approach defining wall types: layers of insulation materials that each include an R-value, thickness, wall cavity information, etc. To translate the inputs from HPXML to HEScore approximations need to be made to condense the continuous inputs in HPXML to discrete inputs required for HEScore.

Wood Frame Walls

If WallType/WoodStud is selected in HPXML, each layer of the wall insulation is parsed and if a rigid and continuous layer is found, or if the subelement WallType/WoodStud/ExpandedPolyStyreneSheathing is found, the wall is specified in HEScore as “Wood Frame with Rigid Foam Sheathing.”

<Wall>
   <SystemIdentifier id="wall1"/>
   <WallType>
       <WoodStud>
           <!-- Either this element needs to be here or continuous insulation below -->
           <ExpandedPolystyreneSheathing>true</ExpandedPolystyreneSheathing>
       </WoodStud>
   </WallType>
   <Insulation>
       <SystemIdentifier id="wall1ins"/>
       <Layer>
           <InstallationType>continuous</InstallationType>
           <InsulationMaterial>
               <Rigid>eps</Rigid>
               <!-- This can have any of the valid enumerations for this element,
                    it only cares if the Rigid element is present. -->
           </InsulationMaterial>
           <NominalRValue>5</NominalRValue>
       </Layer>
       ...
   </Insulation>
</Wall>

Otherwise, if the OptimumValueEngineering boolean element is set to true, the “Wood Frame with Optimal Value Engineering” wall type in HEScore is selected.

<Wall>
   <SystemIdentifier id="wall2"/>
   <WallType>
       <WoodStud>
           <OptimumValueEngineering>true</OptimumValueEngineering>
       </WoodStud>
       <Insulation>
           ...
       </Insulation>
   </WallType>
</Wall>

Note

The OptimumValueEngineering flag needs to be set in HPXML to translate to this wall type. The translator will not infer this from stud spacing.

Finally, if neither of the above conditions are met, the wall is specified as simply “Wood Frame” in HEScore.

In all cases the R-value is summed for all insulation layers and the nearest discrete R-value from the list of possible R-values for that wall type is used. For walls with rigid foam sheathing, R-5 is subtracted from the nominal R-value sum to account for the R-value of the sheathing in the HEScore construction assembly.

Siding is selected according to the siding map.

Structural Brick

If WallType/StructuralBrick is found in HPXML, one of the structural brick codes in HEScore is specified. The nearest R-value to the sum of all the insulation layer nominal R-values is selected.

<Wall>
   <SystemIdentifier id="wall3"/>
   <WallType>
       <StructuralBrick/>
   </WallType>
   <Insulation>
       <SystemIdentifier id="wall3ins"/>
       <Layer>
           <NominalRValue>5</NominalRValue>
       </Layer>
       <Layer>
           <NominalRValue>5</NominalRValue>
       </Layer>
       <!-- This would have a summed R-value of 10 -->
   </Insulation>
</Wall>
Concrete Block or Stone

If WallType/ConcreteMasonryUnit or WallType/Stone is found, one of the concrete block construction codes is used in HEScore. The nearest R-value to the sum of all the insulation layer nominal R-values is selected. The siding is translated using the same assumptions as wood stud walls with the exception that vinyl, wood, or aluminum siding is not available and if those are specified in the HPXML an error will result.

Straw Bale

If WallType/StrawBale is found in the HPXML wall, the straw bale wall assembly code in HEScore is selected.

Exterior Finish

Siding mapping is done from the Wall/Siding element in HPXML. Siding is specified as the last two characters of the construction code in HEScore.

Siding type mapping
HPXML HEScore
wood siding wo
stucco st
synthetic stucco st
vinyl siding vi
aluminum siding al
brick veneer br
asbestos siding wo
fiber cement siding wo
composite shingle siding wo
masonite siding wo
other not translated

Note

not translated means the translation will fail for that house.

Area Weighted Wall R-value

When more than one HPXML Wall element must be combined into one wall construction for HEScore, the wall construction code is determined for each HPXMl Wall as described in Wall Construction. The wall construction and exterior finish that represent the largest combined area are used to represent the side of the house.

A weighted R-value is calculated by looking up the center-of-cavity R-value for the wall construction, exterior finish, and nominal R-value for each Wall from the following table.

Wall center-of-cavity R-values
Exterior Wood Siding Stucco Vinyl Aluminum Brick Veneer None
R-value Effective R-value
Wood Frame
R-0 3.6 2.3 2.2 2.1 2.9  
R-3 5.7 4.4 4.3 4.2 5.0  
R-7 9.7 8.4 8.3 8.2 9.0  
R-11 13.7 12.4 12.3 12.2 13.0  
R-13 15.7 14.4 14.3 14.2 15.0  
R-15 17.7 16.4 16.3 16.2 17.0  
R-19 21.7 20.4 20.3 20.2 21.0  
R-21 23.7 22.4 22.3 22.2 23.0  
Wood Frame w/insulated sheathing
R-0 6.1 5.4 5.3 5.2 6.0  
R-3 9.1 8.4 8.3 8.2 9.0  
R-7 13.1 12.4 12.3 12.2 13.0  
R-11 17.1 16.4 16.3 16.2 17.0  
R-13 19.1 18.4 18.3 18.2 19.0  
R-15 21.1 20.4 20.3 20.2 21.0  
R-19 25.1 24.4 24.3 24.2 25.0  
R-21 27.1 26.4 26.3 26.2 27.0  
Optimum Value Engineering
R-19 21.0 20.3 20.1 20.1 20.9  
R-21 23.0 22.3 22.1 22.1 22.9  
R-27 29.0 28.3 28.1 28.1 28.9  
R-33 35.0 34.3 34.1 34.1 34.9  
R-38 40.0 39.3 39.1 39.1 39.9  
Structural Brick
R-0           2.9
R-5           7.9
R-10           12.8
Concrete Block
R-0   4.1     5.6 4.0
R-3   5.7     7.2 5.6
R-6   8.5     10.0 8.3
Straw Bale
R-0   58.8        

Then a weighted average is calculated by weighting the U-values values by area.

\begin{align*} U_i &= \frac{1}{R_i} \\ U_{eff,avg} &= \frac{\sum_i{U_i A_i}}{\sum_i A_i} \\ R_{eff,avg} &= \frac{1}{U_{eff,avg}} \\ \end{align*}

The R-0 center-of-cavity R-value (\(R_{offset}\)) is selected for the highest weighted wall construction type represented in the calculation and is subtracted from \(R_{eff,avg}\). For construction types where there is no R-0 nominal value, the lowest nominal R-value is subtracted from the corresponding effective R-value.

\[R = R_{eff,avg} - R_{offset}\]

Finally the R-value is rounded to the nearest insulation level in the enumeration choices for the highest weighted roof construction type included in the calculation.

Windows and Skylights

Window Orientation

HEScore requires that a window area be specified for each side of the building. To determine the window area on each side of the building, each Window element in HPXML must have an Area subelement. The Area subelement is assumed to mean the sum of the areas of the windows that the Window element represents. Each Window is then assigned to a side of the building in one of two ways:

  1. By inspecting the azimuth or orientation of the window.
  2. By association with a particular wall.

If there is an Orientation or Azimuth element, the side is determined via the one of those elements with preference given to the Azimuth if present. If the window falls between two sides of the house, the window area is divided between the sides of the house evenly.

If Orientation or Azimuth are missing and the HPXML window has the AttachedToWall element, the id reference in that element is used to find the associated wall and the side of the building that the window faces is inferred from the wall orientation. If the window is attached to a foundation wall, the orientation/azimuth must be provided on the Window element because foundation walls do not have orientation or azimuth elements available.

The areas on each side of the house are summed and the Window Properties are determined independently for each side of the house. Since HPXML requires that window properties be assigned to each direction, the window_construction_same option in HEScore will always be false and all windows will be specified separately.

Skylights in HEScore do not have an orientation that can be set, therefore orientation/azimuth information about skylights is ignored. Use AttachedToRoof to specify which HPXML roof each skylight is attached to. If not specified, skylights will be assigned to the first hescore roof.

Window Properties

Windows can be specified in one of two different ways in HEScore:

  1. NFRC rated window specifications U-Factor and Solar Heat Gain Coefficient (SHGC)
  2. Generic window types defined by the number of panes of glass, frame material, and glazing type.

Preference is given to the first choice above if those values are available in the HPXML document. If U-Factor and SHGC are not available, then one of the window codes is chosen based on the other properties of the windows. Since HPXML stores the window properties for each window, the properties for the windows on each side of the house must be aggregated across all of the windows on that side. The processes described below are done independently for the windows on each side of the house.

Defining windows using NFRC specifications

When there is at least one window on a side of the house that has U-Factor and SHGC values available, those are used. The values are aggregated across all the windows on a particular side of the house by taking an area weighted average omitting any windows that do not have U-Factor and SHGC values.

Defining windows by selecting a window type

When none of the windows on a side of the house have U-Factor and SHGC data elements, a window code is selected based on other properties of each window. Then the most predominant window code by area on each side of the house is selected.

Unfortunately there is not a 1-to-1 correlation of the HPXML data elements to HEScore for these selections and it is possible to define windows in HPXML that are impossible to input into HEScore. In these cases the translation will fail.

Windows are first sorted by frame type. The mapping of HPXML FrameType to HEScore frame type is performed thusly.

Window frame type mapping
HPXML HEScore
Aluminum Aluminum
Composite Wood or Vinyl
Fiberglass Wood or Vinyl
Metal Aluminum
Vinyl Wood or Vinyl
Wood Wood or Vinyl
Other not translated

Warning

If a FrameType of Other is selected in HPXML, the translation will fail.

Both the Aluminum and Metal frame types in HPXML have optional ThermalBreak subelements that specify whether there is a thermal break in the frame. If ThermalBreak is true then the “Aluminum with Thermal Break” frame type is selected.

Depending on the frame type selected in HEScore, different options become available for number of panes and glass type. The following sections explain the logic for each frame type.

Aluminum

The aluminum frame type allows for single- and double-paned windows, but not more than that. According to the HEScore documentation, single-pane windows with storm windows should be considered double-pane.

Window pane mapping for Aluminum frame types (HPXML v2)
HPXML Glass Layers HEScore
single-pane single-pane
double-pane double-pane
triple-pane not translated
multi-layered not translated
single-paned with storms double-pane
single-paned with low-e storms double-pane
other not translated
Window pane mapping for Aluminum frame types (HPXML v3)
HPXML Glass Layers HEScore
single-pane single-pane
double-pane double-pane
triple-pane not translated
multi-layered not translated
other not translated

Note

Starting from HPXML v3, “single-paned with storms” and “single-paned with low-e storms” enumerations are removed. Instead, translator searches Window/StormWindow element for storm existence. If the storm window is a low-e window, specify Window/StormWindow/GlassType to be equal to “low-e”. StormWindow is only used when single-pane window is specified.

HPXML v2 “single-paned with storms” equivalence(mapped to double-pane) in HPXML v3:
  • Window/GlassLayers “single-pane” + Window/StormWindow.
HPXML v2 “single-paned with low-e storms” equivalence(mapped to double-pane) in HPXML v3:
  • Window/GlassLayers “single-pane” + Window/StormWindow/GlassType to be “low-e”.

Warning

If a window has the “Aluminum” frame type, the GlassLayers must be single-pane, double-pane, or a single-pane with storm windows (or specify Window/StormWindow with “single-pane” in HPXML v3+) or the translation will fail.

Single-pane

Single-paned windows can be either tinted or clear. If the GlassType element is either “tinted” or “tinted/reflective”, “Single-pane, tinted” is selected. Otherwise, “Single-pane, clear” is selected.

Single-pane window mapping for Aluminum frame types
HPXML Glass Type HEScore Glazing Type
low-e Single-pane, tinted
tinted Single-pane, tinted
reflective Single-pane, clear
tinted/reflective Single-pane, tinted
other Single-pane, clear
element missing Single-pane, clear
Double-pane

Double-paned windows have a solar control low-e option in addition to the tinted and clear options.

Double-pane window mapping for Aluminum frame types
HPXML Glass Type HEScore Glazing Type
low-e Double-pane, solar-control low-E
tinted Double-pane, tinted
reflective Double-pane, solar-control low-E
tinted/reflective Double-pane, solar-control low-E
other Double-pane, clear
element missing Double-pane, clear
Aluminum with Thermal Break

Only double paned window options are available for the aluminum with thermal break frame type. According to the HEScore documentation, single-pane windows with storm windows should be considered double-pane.

Window pane mapping for Aluminum with Thermal Break frame types (HPXML v2)
HPXML Glass Layers HEScore
single-pane not translated
double-pane double-pane
triple-pane not translated
multi-layered not translated
single-paned with storms double-pane
single-paned with low-e storms double-pane
other not translated
Window pane mapping for Aluminum with Thermal Break frame types (HPXML v3)
HPXML Glass Layers HEScore
single-pane not translated
double-pane double-pane
triple-pane not translated
multi-layered not translated
other not translated

Note

Starting from HPXML v3, “single-paned with storms” and “single-paned with low-e storms” enumerations are removed. Instead, translator searches Window/StormWindow element for storm existence. If the storm window is a low-e window, specify Window/StormWindow/GlassType to be equal to “low-e”. StormWindow is only used when single-pane window is specified.

HPXML v2 “single-paned with storms” equivalence(mapped to double-pane) in HPXML v3:
  • Window/GlassLayers “single-pane” + Window/StormWindow.
HPXML v2 “single-paned with low-e storms” equivalence(mapped to double-pane) in HPXML v3:
  • Window/GlassLayers “single-pane” + Window/StormWindow/GlassType to be “low-e”.

Warning

If a window has the “Aluminum with Thermal Break” frame type, the GlassLayers must be double-pane or single-pane with storms (or specify Window/StormWindow with “single-pane” in HPXML v3+) or the translation will fail.

Double-pane

To get the “Double-pane, insulating low-E, argon gas fill” option, you need to specify the window elements as highlighted below. Storm windows will not work because it is impossible to have an argon gas fill between the window and the storm window.

<Window>
   <SystemIdentifier id="id1"/>
   <Area>30</Area>
   <Orientation>east</Orientation>
   <FrameType>
       <Aluminum><!-- or Metal -->
           <ThermalBreak>true</ThermalBreak>
       </Aluminum>
   </FrameType>
   <GlassLayers>double-pane</GlassLayers>
   <GlassType>low-e</GlassType>
   <GasFill>argon</GasFill>
</Window>

“Double-pane, solar-control low-E” can be specified as highlighted in the following code block. Using “reflective” in GlassType is assumed to be the same as solar control low-e.

<Window>
   <SystemIdentifier id="id2"/>
   <Area>30</Area>
   <Orientation>east</Orientation>
   <FrameType>
       <Aluminum><!-- or Metal -->
           <ThermalBreak>true</ThermalBreak>
       </Aluminum>
   </FrameType>
   <GlassLayers>double-pane</GlassLayers><!-- or other double-pane mapped options mentioned above -->
   <GlassType>reflective</GlassType>
</Window>

Warning

Is “reflective” the same as solar control low-e or close enough? I’m running on the assumption that low-e means insulating low-e.

To specify the “Double-pane, tinted” option in HEScore, the GlassType needs to be either “tinted” or “tinted/reflective.”

<Window>
   <SystemIdentifier id="window1"/>
   <Area>30</Area>
   <Orientation>east</Orientation>
   <FrameType>
       <Aluminum>
           <ThermalBreak>true</ThermalBreak>
       </Aluminum>
   </FrameType>
   <GlassLayers>double-pane</GlassLayers><!-- or 'single-paned with storms', 'single-paned with low-e storms' -->
   <GlassType>tinted</GlassType><!-- or tinted/reflective -->
</Window>

All other double-pane windows will be translated as “Double-pane, clear.”

Wood or Vinyl

In HEScore wood or vinyl framed windows can have 1, 2, or 3 panes. According to the HEScore documentation, single-pane windows with storm windows should be considered double-pane. The HPXML GlassLayers maps into HEScore number of panes as follows:

Window pane mapping for Wood or Vinyl frame types (HPXML v2)
HPXML Glass Layers HEScore
single-pane single-pane
double-pane double-pane
triple-pane triple-pane
multi-layered not translated
single-paned with storms double-pane
single-paned with low-e storms double-pane
other not translated
Window pane mapping for Wood or Vinyl frame types (HPXML v3)
HPXML Glass Layers HEScore
single-pane single-pane
double-pane double-pane
triple-pane triple-pane
multi-layered not translated
other not translated

Note

Starting from HPXML v3, “single-paned with storms” and “single-paned with low-e storms” enumerations are removed. Instead, translator searches Window/StormWindow element for storm existence. If the storm window is a low-e window, specify Window/StormWindow/GlassType to be equal to “low-e”. StormWindow is only used when single-pane window is specified.

HPXML v2 “single-paned with storms” equivalence(mapped to double-pane) in HPXML v3:
  • Window/GlassLayers “single-pane” + Window/StormWindow.
HPXML v2 “single-paned with low-e storms” equivalence(mapped to double-pane) in HPXML v3:
  • Window/GlassLayers “single-pane” + Window/StormWindow/GlassType to be “low-e”.
Single-pane

Single-pane windows can be either tinted or not. If the GlassType element is either “tinted” or “tinted/reflective”, “Single-pane, tinted” is selected. Otherwise, “Single-pane, clear” is selected.

Single-pane window mapping for Wood or Vinyl frame types
HPXML Glass Type HEScore Glazing Type
low-e Single-pane, tinted
tinted Single-pane, tinted
reflective Single-pane, clear
tinted/reflective Single-pane, tinted
other Single-pane, clear
element missing Single-pane, clear
Double-pane

Double-pane windows can be either clear, tinted, insulating low-E with or without argon gas fill, and solar control low-E with or without argon gas fill. According to the HEScore documentation, single-pane windows with storm windows should be considered double-pane. The double-pane mapping is a bit more complicated as it needs to use multiple elements to determine the glazing type for HEScore. We will address each possible HEScore combination and how it is expected to be represented in HPXML.

To get a insulating low-E double-pane wood or vinyl framed window, GlassLayers needs to be “double-pane” and the GlassType needs to be “low-e” or GlassLayers needs to be “single-paned with low-e storms” (or GlassLayers “single-pane” + Window/StormWindow/GlassType equal to “low-e” in HPXML v3+). If GasFill is argon, it will be argon filled. For instance, to get a double-pane low-E with argon fill, the HPXML window element would look like:

<Window>
   <SystemIdentifier id="window1"/>
   <Area>30</Area>
   <Orientation>east</Orientation>
   <FrameType>
       <Vinyl/>
   </FrameType>
   <GlassLayers>double-pane</GlassLayers>
   <GlassType>low-e</GlassType>
   <GasFill>argon</GasFill>
</Window>

Translating a Single-pane window with a low-E storm window into the HEScore type of double-pane with insulating low-E the HPXML window element would look like:

  • HPXML v2:
<Window>
   <SystemIdentifier id="window53"/>
   <Area>30</Area>
   <Orientation>east</Orientation>
   <FrameType>
       <Vinyl/>
   </FrameType>
   <GlassLayers>single-paned with low-e storms</GlassLayers>
</Window>
  • HPXML v3:
<Window>
   <SystemIdentifier id="window53"/>
   <Area>30</Area>
   <Orientation>east</Orientation>
   <FrameType>
       <Vinyl/>
   </FrameType>
   <GlassLayers>single-pane</GlassLayers>
   <StormWindow>
      <SystemIdentifier id="windowstorm"/>
      <GlassType>low-e</GlassType>
   </StormWindow>
</Window>

Note the missing GlassType element. It is ignored when it’s a single-paned window with low-e storms. The translation will also ignore GasFill for single-paned window because it’s impossible to have argon between a single pane window and storm window.

To specify a solar-control low-E double-pane wood or vinyl framed window a GlassType of “reflective” must be specified. Setting GasFill as “argon” or not indicates whether the argon gas fill type is chosen in HEScore.

Warning

The HPXML GlassType of reflective is assumed to mean solar control low-E when translated into HEScore parlance.

For instance, to get a “Double-pane, solar-control low-E” glazing type, the HPXML window element would look like:

<Window>
   <SystemIdentifier id="window53"/>
   <Area>30</Area>
   <Orientation>east</Orientation>
   <FrameType>
       <Wood/>
   </FrameType>
   <GlassLayers>double-pane</GlassLayers>
   <GlassType>reflective</GlassType>
</Window>

For argon filled, you would add <GasFill>argon</GasFill> before the </Window>.

If the GlassType is “tinted” or “tinted/reflective” the “Double-pane, tinted” HEScore glazing type is selected.

Finally, if the window is double-pane (or single-pane with storm window) and doesn’t meet the above criteria, then the “Double-pane, clear” glazing type is chosen for HEScore.

Triple-pane

If the GlassLayers in HPXML specifies a “triple-paned” window, the HEScore “Triple-pane, insulating low-E, argon gas fill” glazing type is selected. The GlassType and GasFill elements are not considered since this is the only triple-pane glazing option in HEScore.

Solar Screens

For each side of the house in HEScore, solar screens may be present. To determine if solar screens should be specified, the translator looks for either of the following subelements of Window or Skylight:

HPXML v2:

  • <ExteriorShading>solar screens</ExteriorShading>
  • <Treatments>solar screen</Treatments>

HPXML v3:

  • <ExteriorShading><Type>solar screens</Type></ExteriorShading>

If the majority of the window area on a side of the house (or skylights facing upwards) meet that criteria, that side of the house will have solar screens in the HEScore model. This determination is made independent of whether the other window properties were set using NFRC specifications or inferred based on window type.

HVAC Systems

HEScore allows the definition of up to two HVAC systems which can each include a heating system, cooling system, and duct system. To determine which HPXML elements are associated, the DistributionSystem subelement of HeatingSystem, CoolingSystem, HeatPump is used to find the link to HVACDistributionSystem. Systems that share the same HVACDistributionSystem are determined to be the same HVAC system for HEScore.

Sometimes an HVAC system will not share ducts, for instance a central air conditioner and boiler. In that case, if each of those systems serve a fraction of the home’s load within 5% of each other they will be combined into the same HVAC system for HEScore. If a HeatingSystem and CoolingSystem that are associated with the same HVACDistributionSystem serve differing portions of the house’s heating and cooling load, that weight is averaged to find the combined system weight.

If either a heating or cooling system meets all of the load and two systems of the opposite (cooling or heating, respectively) are required to meet the same fraction of the load, the larger system is split into two for input into HEScore.

To determine the fraction of the home’s heating and cooling load each system serves, each HPXML heating and cooling system is required to have FloorAreaServed or, alternatively FracLoadServed. The two combined HVAC systems that serve the greatest portion of the house’s load are sent to HEScore.

For details about how each kind of HeatingSystem, CoolingSystem, HeatPump, and HVACDistributionSystem are translated into HEScore inputs, see the appropriate subsection:

Heating

Heating system type

HPXML provides two difference HVAC system elements that can provide heating: HeatingSystem that only provides heating and HeatPump which can provide heating and cooling.

Heat Pump

The HeatPump element in HPXML can represent either an air-source heat pump or ground source heat pump in HEScore. Which is specified in HEScore is determined by the HeatPumpType element in HPXML according to the following mapping.

Heat Pump Type mapping
HPXML Heat Pump Type HEScore Heating Type
water-to-air gchp
water-to-water gchp
air-to-air heat_pump
mini-split mini_split
ground-to-air gchp

The primary heating fuel is assumed to be electric.

Note

Prior to HEScore v2016 mini-split heat pumps were translated as ducted air-source heat pumps with ducts in conditioned space. With the addition of mini split heat pumps in HEScore v2016, they are now categorized appropriately.

If a heat pump has a FractionCoolLoadServed set to zero, the heat pump is assumed to provide only space heating. If the heat pump is connected to the same distribution system as a separate cooling system and serves the same portion of the house, the house will translate but fail in Home Energy Score because that configuration is not supported.

Heating System

The HeatingSystem element in HPXML is used to describe any system that provides heating that is not a heat pump. The HeatingSystemType subelement is used to determine what kind of heating system to specify for HEScore. This is done according to the following mapping.

Heating System Type mapping
HPXML Heating System Type HEScore Heating Type
Furnace central_furnace
WallFurnace wall_furnace
FloorFurnace wall_furnace
Boiler boiler
ElectricResistance baseboard
Stove wood_stove

Note

HPXML supports other values for the HeatingSystemType element not in the list above, but HEScore does not. Other heating system types will result in a translation error.

A primary heating fuel is selected from the HeatingSystemFuel subelement of the primary heating system. The fuel types are mapped as follows.

Primary Heating System Fuel mapping
HPXML HEScore
electricity electric
renewable electricity electric
natural gas natural_gas
renewable natural gas natural_gas
fuel oil fuel_oil
fuel oil 1 fuel_oil
fuel oil 2 fuel_oil
fuel oil 4 fuel_oil
fuel oil 5/6 fuel_oil
propane lpg
wood cord_wood
wood pellets pellet_wood

Warning

HPXML supports other fuel types that could not be mapped into existing HEScore fuel types (i.e. coal, wood). Encountering an unsupported fuel type will result in a translation error.

Heating Efficiency

Heating efficiency can be described in HEScore by either the rated efficiency (AFUE, HSPF, COP), or if that is unavailable, the year installed/manufactured from which HEScore estimates the efficiency based on shipment weighted efficiencies by year. The translator follows this methodology and looks for the rated efficiency first and if it cannot be found sends the year installed.

Wood stoves and electric furnaces and baseboard heating do not use the efficiency input in HEScore. Therefore, for these heating types an efficiency is not determined.

Rated Efficiency

HEScore expects efficiency to be described in different units depending on the heating system type.

HEScore heating type efficiency units
Heating Type Efficiency Units
heat_pump HSPF
mini_split HSPF
central_furnace AFUE
wall_furnace AFUE
boiler AFUE
gchp COP

The translator searches the HeatingSystem/AnnualHeatingEfficiency or HeatPump/AnnualHeatEfficiency (HPXML v2) or HeatPump/AnnualHeatingEfficiency (HPXML v3) elements of the primary heating system and uses the first one that has the correct units.

Shipment Weighted Efficiency

When an appropriate rated efficiency cannot be found, HEScore can accept the year the equipment was installed and estimate the efficiency based on that. The year is retrieved from the YearInstalled element, and if that is not present the ModelYear element.

Cooling

Cooling system type

HPXML provides two difference HVAC system elements that can provide cooling: CoolingSystem that only provides cooling and HeatPump which can provide heating and cooling.

Heat Pump

The HeatPump element in HPXML can represent either an air-source heat pump or ground source heat pump in HEScore. Which is specified in HEScore is determined by the HeatPumpType element in HPXML according to the following mapping.

Heat Pump Type mapping
HPXML Heat Pump Type HEScore Cooling Type
water-to-air gchp
water-to-water gchp
air-to-air heat_pump
mini-split mini_split
ground-to-air gchp

Note

Prior to HEScore v2016 mini-split heat pumps were translated as ducted air-source heat pumps with ducts in conditioned space. With the addition of mini split heat pumps in HEScore v2016, they are now categorized appropriately.

If a heat pump has a FractionHeatlLoadServed set to zero, the heat pump is assumed to provide only space cooling. If the heat pump is connected to the same distribution system as a separate heating system and serves the same portion of the house, the house will translate but fail in Home Energy Score because that configuration is not supported.

Cooling System

The CoolingSystem element in HPXML is used to describe any system that provides cooling that is not a heat pump. The CoolingSystemType subelement is used to determine what kind of cooling system to specify for HEScore. This is done according to the following mapping.

Cooling System Type mapping
HPXML Cooling System Type HEScore Cooling Type
central air conditioner (HPXML V3) split_dx
central air conditioning (HPXML V2) split_dx
room air conditioner packaged_dx
mini-split mini_split
evaporative cooler dec
other not translated

Warning

If an HPXML cooling system type maps to not translated the translation will fail.

Note

Prior to v2016, HEScore did not have an evaporative cooler type and these were translated as high efficiency split_dx systems. Now that evaporative cooling has been added in HEScore v2016, they are categorized accordingly.

Note

Starting from HPXML version 3.0, the enumeration “central air conditioning” is renamed as “central air conditioner”. They’re equivalent in translation.

Cooling Efficiency

Cooling efficiency can be described in HEScore by either the rated efficiency (SEER, EER), or if that is unavailable, the year installed/manufactured from which HEScore estimates the efficiency based on shipment weighted efficiencies by year. The translator follows this methodology and looks for the rated efficiency first and if it cannot be found sends the year installed. Evaporative coolers do not require an efficiency input in HEScore, and it is therefore omitted.

Rated Efficiency

HEScore expects efficiency to be described in different units depending on the cooling system type.

HEScore cooling type efficiency units
Cooling Type Efficiency Units
split_dx SEER
packaged_dx EER
heat_pump SEER
mini_split SEER
gchp EER

The translator searches the CoolingSystem/AnnualCoolingEfficiency or HeatPump/AnnualCoolEfficiency (HPXML v2) or HeatPump/AnnualCoolingEfficiency (HPXML v3) elements of the primary cooling system and uses the first one that has the correct units.

Shipment Weighted Efficiency

When an appropriate rated efficiency cannot be found, HEScore can accept the year the equipment was installed and estimate the efficiency based on that. The year is retrieved from the YearInstalled element, and if that is not present the ModelYear element.

HVAC Distribution

In HPXML multiple HVACDistribution elements can be associated with a heating or cooling system. For the purposes of this translator, it is required that only one HVACDistribution element be linked. That element can then describe a ducted system, a hydronic system, or an open ended other system. For the translation to HEScore, only HVACDistribution elements that are ducted are considered.

Duct Location Mapping

For each Ducts element in each air distribution system, the location of the duct mapped from HPXML enumerations to HEScore enumerations according to the following mapping.

Duct Location mapping (HPXML v2)
HPXML HEScore
conditioned space cond_space
unconditioned space not translated
unconditioned basement uncond_basement
unvented crawlspace unvented_crawl
vented crawlspace vented_crawl
crawlspace not translated
unconditioned attic uncond_attic
interstitial space not translated
garage vented_crawl
outside not translated
Duct Location mapping (HPXML v3)
HPXML HEScore Hierarchy
living space cond_space
unconditioned space uncond_basement, vented_crawl, unvented_crawl, uncond_attic
under slab vented_crawl
basement uncond_basement, cond_space
basement - unconditioned uncond_basement
basement - conditioned cond_space
crawlspace - unvented unvented_crawl
crawlspace - vented vented_crawl
crawlspace - unconditioned vented_crawl, unvented_crawl
crawlspace - conditioned cond_space
crawlspace vented_crawl, unvented_crawl, cond_space
exterior wall not translated
attic uncond_attic, cond_space
attic - unconditioned uncond_attic
attic - conditioned cond_space
attic - unvented uncond_attic
attic - vented uncond_attic
interstitial space not translated
garage vented_crawl
garage - conditioned cond_space
garage - unconditioned vented_crawl
roof deck vented_crawl
outside vented_crawl

Warning

If an HPXML duct location maps to not translated above, the translation for the house will fail.

Duct Fractions

For each Ducts element in an air distribution system the FracDuctArea is summed by HEScore duct location.

Duct Insulation

If the any of the Ducts elements in a particular location have a DuctInsulationRValue or DuctInsulationThickness that is greater than zero, all of the ducts in that location are considered insulated.

Duct Sealing

Duct leakage measurements are not stored on the individual Ducts elements in HEScore, which means they are not directly associated with a duct location. They are instead associated with an AirDistribution element, which can have many ducts in many locations. Duct sealing information is therefore associated with all ducts in an AirDistribution element.

To specify that the ducts in an AirDistribution system are sealed, the translator expects to find either of the following elements:

  • DuctLeakageMeasurement/LeakinessObservedVisualInspection element with the value of “connections sealed w mastic”.
  • HVACDistribution/HVACDistributionImprovement/DuctSystemSealed element with the value of “true”.

The DuctLeakageMeasurement can hold values for actual measurements of leakage, but since HEScore cannot do anything with them, they will be ignored. Therefore the following will result in an “unsealed” designation:

<DuctLeakageMeasurement>
   <DuctType>supply</DuctType>
   <!-- All of this is ignored -->
   <DuctLeakageTestMethod>duct leakage tester</DuctLeakageTestMethod>
   <DuctLeakage>
       <Units>CFM25</Units>
       <Value>0.000000001</Value><!-- exceptionally low leakage -->
   </DuctLeakage>
</DuctLeakageMeasurement>

and the following will result in a “sealed” designation:

<DuctLeakageMeasurement>
   <DuctType>supply</DuctType>
   <LeakinessObservedVisualInspection>connections sealed w mastic</LeakinessObservedVisualInspection>
</DuctLeakageMeasurement>

Domestic Hot Water

Determining the primary water heating system

HPXML allows for the specification of several WaterHeatingSystem elements. HEScore only allows one to be specified. If there are more than one water heaters present in the HPXML file, the one that serves the largest fraction of the the load is selected based on the value of FractionDHWLoadServed. If not all of the WaterHeatingSystem elements have FractionDHWServed subelements (or if none of them do), the first WaterHeatingSystem is selected.

Water heater type

The water heater type is mapped from HPXML to HEScore accordingly:

HPXML to HEScore water heater type mapping
HPXML HEScore
WaterHeaterType DHW Category DHW Type
storage water heater unit storage
dedicated boiler with storage tank
instantaneous water heater unit tankless
heat pump water heater unit heat_pump
space-heating boiler with storage tank combined indirect
space-heating boiler with tankless coil combined tankless_coil

The fuel type is mapped according to the same mapping used in Primary Heating System Fuel mapping.

Water heating efficiency

If the WaterHeating/UniformEnergyFactor element exists, that is passed to HEScore with an efficiency method of “uef”. Otherwise if the WaterHeatingSystem/EnergyFactor element exists, that energy factor is sent to HEScore along with an efficiency method of “user”, which tells it that to interpret it as a traditional energy factor. When an energy factor cannot be found, HEScore can accept the year the equipment was installed and estimate the efficiency based on that. The year is retrieved from the YearInstalled element, and if that is not present the ModelYear element.

If the DHW type is tankless, only energy factor or unified energy factor could be used to describe efficiency, the estimation based on installed year is no longer available.

Generation

Solar Electric

HEScore allows for a single photovoltaic system to be included as of v2016. In HPXML, multiple PVSystem elements can be specified to represent the PV systems on the house. The translator combines multiple systems and generates the appropriate HEScore inputs as follows:

Capacity Known

If each PVSystem has a MaxPowerOutput, this is true. If each PVSystem has a CollectorArea, this is false. Preference is given to known capacity if both are available. Either a MaxPowerOutput must be specified for every PVSystem or CollectorArea must be specified for every PVSystem.

DC Capacity

If each PVSystem has a MaxPowerOutput, the system capacity is known. The system_capacity in HEScore is calculated by summing all the MaxPowerOutput elements in HPXML.

Number of Panels

If MaxPowerOutput is missing from any PVSystem, CollectorArea is required on every PVSystem and the system capacity is not known. The number of panels is calculated by summing all the collector area, dividing by 17.6 sq.ft., and rounding to the nearest whole number.

Year Installed

For each PVSystem the YearInverterManufactured and YearModulesManufactured element values are retrieved, and the greater of the two is assumed to be the year that system was installed. When there are multiple PVSystem elements, a capacity or area-weighted average of the assumed year installed is calculated and used.

Panel Orientation (Azimuth)

For each PVSystem the ArrayAzimuth (degrees clockwise from north) is retrieved. If ArrayAzimuth is not available, ArrayOrientation (north, northwest, etc) is converted into an azimuth. A capacity or area-weighted average azimuth is calculated and converted into the nearest cardinal direction (north, northwest, etc) for submission into the array_azimuth HEScore input (which expects a direction, not a numeric azimuth).

Glossary of Terms

ACH50
Air changes per hour at 50 Pascals pressure.
API
Application Programming Interface. An API is a documented way for different software to interact with each other. In the context of this document, the API referred to specifically is the HEScore API. Specific documentation is available on the LBNL website.
CFM50
Cubic feet per minute at 50 Pascals pressure.
HEScore
Home Energy Scoring Tool. The Home Energy Score is similar to a vehicle’s mile-per-gallon rating. The Home Energy Score allows homeowners to compare the energy performance of their homes to other homes nationwide. It also provides homeowners with suggestions for improving their homes’ efficiency. The process starts with a Home Energy Score Qualified Assessor collecting energy information during a brief home walk-through. Using the Home Energy Scoring Tool, developed by the Lawrence Berkeley National Laboratory, the Qualified Assessor then scores the home on a scale of 1 to 10. A score of 10 indicates that the home has excellent energy performance. A score of 1 indicates the home needs extensive energy improvements. In addition to providing the Score, the Qualified Assessor provides the homeowner with a list of recommended energy improvements and the associated cost savings estimates. [1]
HPXML
Home Performance XML. BPI-2100 is designed to facilitate communication and the exchange of information and data among all actors in the home performance industry by providing an extensible mark-up language (XML) standard for transferring information related to whole-house energy efficiency upgrades. The standard is informally known as Home Performance XML, or HPXML. BPI-2100 is a companion standard to BPI-2200 (Standard for Home Performance-Related Data Collection). Each of the data elements defined in BPI-2200 can be transferred via HPXML. [2]
XML
eXtensible Markup Language. XML is a markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. It is defined in the XML 1.0 Specification produced by the W3C, and several other related specifications, all free open standards. [3]

Footnotes

[1]http://energy.gov/eere/buildings/home-energy-score
[2]http://hpxmlonline.com/
[3]http://en.wikipedia.org/wiki/XML

Indices and tables