Merge pull request #121 from NREL/hpxml_v3

Hpxml v3
NREL · Jun 9, 2020 · 1b9fce8 · 1b9fce8
2 parents 5f37c35 + 8f2e73d
commit 1b9fce8
Show file tree

Hide file tree

Showing 46 changed files with 13,477 additions and 18,845 deletions.
diff --git a/docs/source/translation/cooling_system.rst b/docs/source/translation/cooling_system.rst
@@ -54,15 +54,16 @@ is done according to the following mapping.
 
 .. table:: Cooling System Type mapping
 
-   =========================  ====================
-   HPXML Cooling System Type  HEScore Cooling Type
-   =========================  ====================
-   central air conditioning   split_dx
-   room air conditioner       packaged_dx
-   mini-split                 mini_split
-   evaporative cooler         dec
-   other                      *not translated*
-   =========================  ====================
+   ===================================  ====================
+   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::
 
@@ -73,6 +74,11 @@ is done according to the following mapping.
    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
 ******************
 
@@ -102,8 +108,8 @@ cooling system type.
    ===============  ================
 
 The translator searches the ``CoolingSystem/AnnualCoolingEfficiency`` or
-``HeatPump/AnnualCoolEfficiency`` elements of the primary cooling system and
-uses the first one that has the correct units.
+``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.
 
 .. _clg-shipment-weighted-efficiency:
 

diff --git a/docs/source/translation/heating_system.rst b/docs/source/translation/heating_system.rst
@@ -134,8 +134,8 @@ heating system type.
    ===============  ================
 
 The translator searches the ``HeatingSystem/AnnualHeatingEfficiency`` or
-``HeatPump/AnnualHeatEfficiency`` elements of the primary heating system and
-uses the first one that has the correct units.
+``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
 ============================

diff --git a/docs/source/translation/hpwes.rst b/docs/source/translation/hpwes.rst
@@ -1,33 +1,53 @@
 Home Performance with Energy Star
 #################################
 
-Inputs for the Home Energy Score `submit_hpwes`_ API call can now be retrieved
-from an HPXML file.
+Inputs for the Home Energy Score `submit_hpwes`_ API call can be retrieved from
+an HPXML file as described below.
+
+.. _submit_hpwes: https://hes-documentation.labworks.org/home/api-definitions/api-methods/submit_hpwes
+
+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 with at least the
-following elements:
+from an HPXML file a ``Project`` node needs to be included. 
+The following elements are required under the ``Project`` node:
 
-.. _submit_hpwes: https://hes-documentation.labworks.org/home/api-definitions/api-methods/submit_hpwes
-
-.. code:: xml
+.. code-block:: xml
 
     <Project>
         <ProjectDetails>
             <ProjectSystemIdentifiers id="projectid"/>
-            <ProgramCertificate>Home Performance with Energy Star</ProgramCertificate>
+            <!-- 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. To translate the HPwES fields, the ``ProgramCertificate`` must be
-present and equal to ``Home Performance with Energy Star``.
+command line.
 
 The project fields are mapped as follows:
 

diff --git a/docs/source/translation/hvac_distribution.rst b/docs/source/translation/hvac_distribution.rst
@@ -18,7 +18,7 @@ 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.
 
-.. table:: Duct Location mapping
+.. table:: Duct Location mapping (HPXML v2)
 
    ======================  ================
    HPXML                   HEScore
@@ -35,6 +35,36 @@ following mapping.
    outside                 *not translated*
    ======================  ================
 
+.. table:: 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