Merge branch 'changes-for-hpxml-gen-v6' into add-energy-end-use-to-response

Author: joshuamzm

docs/source/api.rst renamed to docs/source/deprecated/api.rst

@@ -149,9 +149,12 @@ Property                  Type     Units     Constraints  Required  Default
 ``storiesCount``          integer  count     >0           no        PSC, BSA
 ``windowToWallFraction``  float    fraction  >0           no        0.14
 ``yearBuilt``             integer  year      >1600        no        PSC                 If missing from PSC, model will fail           
+``propertyUse``           string             see [#]_     no        PSC                 Advanced option. See [#]_
 ========================  =======  ========  ===========  ========  ==================  ============================================== 
 
 .. [#] ``bedroomsCount``/2 + 0.5
+.. [#] ``propertyUse`` options are “single-family detached”, “single-family attached”, or “manufactured home”
+.. [#] ``propertyUse`` is an advanced field. Overriding the existing property use may produce in abnormal model results. If you set this, we recommend setting square footage as well.
 
 .. _cost:
 
@@ -217,18 +220,19 @@ Property                  Type     Units             Constraints  Required  Defa
 Attics
 ~~~~~~
 
-The attic is entered in ``...building.enclosure.attics``. Currently, this array must contain exactly 1 attic object. If there is no attic present in house, set ``area`` to 0.
-See note about `objects and arrays`_ for more information.
+The attic is entered in ``...building.enclosure.attics``. Currently, this array must contain exactly 1 attic object. See note about `objects and arrays`_ for more information.
 
 =================================  =======  ================  ==============  ========  ==================  ============================================== 
 Property                           Type     Units             Constraints     Required  Default             Notes
 =================================  =======  ================  ==============  ========  ==================  ==============================================       
-``id``                             id                         Must be unique  yes       Attic1  
-``area``                           float    ft2               >0              no        PSC
-``isVented``                       boolean                                    no        yes
-``floorAssemblyEffectiveRValue``   float    F-ft2-hr/Btu      >0              no        BSA
+``id``                             id                         Must be unique  yes       Attic1
+``type``                           string                     see [#]_        no        BSA
+``area``                           float    ft2               >0              no        PSC                 Not applicable when ``type`` is "cathedral ceiling" or "flat roof"
+``floorAssemblyEffectiveRValue``   float    F-ft2-hr/Btu      >0              no        BSA                 Not applicable when ``type`` is "cathedral ceiling" or "flat roof"
 =================================  =======  ================  ==============  ========  ==================  ============================================== 
 
+.. [#] ``type`` options are "attic vented", "attic unvented", "cathedral ceiling", or "flat roof".
+
 Roofs
 ~~~~~
 
@@ -259,7 +263,7 @@ Property                           Type     Units             Constraints     Re
 ``wallHeight``                     float    ft                >=0             no        PSC  
 =================================  =======  ================  ==============  ========  ==================  ============================================== 
 
-.. [#] ``type`` choices are "basement conditioned", "basement unconditioned", "crawl vented", "crawl unvented", "slab", and "pier and beam".
+.. [#] ``type`` choices are "basement conditioned", "basement unconditioned", "crawl vented", "crawl unvented", "slab", and "belly and wing".
 
 Walls
 ~~~~~
@@ -365,7 +369,7 @@ Property                           Type     Units                        Constra
 .. [#] If ``systemType`` is "central air conditioner"
 .. [#] ``systemType`` choices are "central air conditioner", "room air conditioner", "evaporative cooler", "packaged terminal air conditioner", and "mini-split".
 .. [#] ``compressorType`` choices are "single stage", "two stage", and "variable speed".
-.. [#] ``coolEfficiencyUnits`` choices are "percent", "EER", "CEER", and "SEER". The option to use "SEER2" is planned for a future release.
+.. [#] ``coolEfficiencyUnits`` choices are "fraction", "EER", "CEER", "SEER", and "SEER2".
 
 HVAC Heating Systems
 ~~~~~~~~~~~~~~~~~~~~
@@ -388,7 +392,7 @@ Property                           Type     Units                        Constra
 
 .. [#] Required when ``systemType`` is "furnace" or "boiler".
 .. [#] ``fuel`` choices are "electricity", "natural gas", "fuel oil", "propane", "coal", "wood", and "wood pellets".
-.. [#] ``heatEfficiencyUnits`` choices are "AFUE" and "percent".
+.. [#] ``heatEfficiencyUnits`` choices are "AFUE" and "fraction".
 
 HVAC Heat Pumps
 ~~~~~~~~~~~~~~~
@@ -406,9 +410,9 @@ Property                           Type     Units                       Constrai
 ``heatCapacityBtuPerHour``         float    Btu/hr                      >=0             no                            autosized by modeling engine if undefined
 ``coolCapacityBtuPerHour``         float    Btu/hr                      >=0             no                            autosized by modeling engine if undefined
 ``heatEfficiency``                 float    Btu/Wh                      >0              no        PSC
-``heatEfficiencyUnits``            string                               HSPF [#]_       no        HSPF
+``heatEfficiencyUnits``            string                               see [#]_        no        HSPF
 ``coolEfficiency``                 float    Btu/Wh                      >0              no        PSC
-``coolEfficiencyUnits``            string                               SEER [#]_       no        SEER
+``coolEfficiencyUnits``            string                               see [#]_        no        SEER
 ``heatLoadFraction``               float    fraction                    0-1             yes       1
 ``coolLoadFraction``               float    fraction                    0-1             yes       1
 ``backupSystem``                   object                                               yes
@@ -418,8 +422,8 @@ Property                           Type     Units                       Constrai
 .. [#] Required when ``systemType`` is "air-to-air" or "ground-to-air".
 .. [#] ``systemType`` choices are "mini-split", "air-to-air", and "ground-to-air".
 .. [#] ``compressorType`` choices are "single stage", "two stage", and "variable speed".
-.. [#] The option to use "HSPF2" is planned for a future release.
-.. [#] The option to use "SEER2" is planned for a future release.
+.. [#] ``heatEfficiencyUnits`` choices are "HSPF" and "HSPF2".
+.. [#] ``coolEfficiencyUnits`` choices are "SEER" and "SEER2".
 
 ``backupSystem`` schema for HVAC Heat Pumps:
 
@@ -430,15 +434,15 @@ Property                           Type     Units                       Constrai
 ``heatingSwitchoverTemp``          float    F                                           no                            determined by modeling engine if undefined
 ``fuel``                           string                               see [#]_        no        electricity         only applicable if backupSystem.systemType = "integrated"
 ``heatEfficiency``                 float    see ``heatEfficiencyUnit``  0-1             no        1                   only applicable if backupSystem.systemType = "integrated"
-``heatEfficiencyUnits``            string                               see [#]_        no        percent             only applicable if backupSystem.systemType = "integrated"
+``heatEfficiencyUnits``            string                               see [#]_        no        fraction             only applicable if backupSystem.systemType = "integrated"
 ``heatCapacityBtuPerHour``         float    Btu/hr                      >=0             no                            autosized by modeling engine if undefined, only applicable if backupSystem.systemType = "integrated"
 ``backupHvacId``                   idref                                see [#]_        see [#]_  PSC
 =================================  =======  ==========================  ==============  ========  ==================  ============================================== 
 
 .. [#] ``systemType`` choices are "integrated" and "separate".
 .. [#] ``fuel`` choices are "electricity", "natural gas", "fuel oil", "propane", "coal", "wood", and "wood pellets".
-.. [#] ``heatEfficiencyUnits`` choices are "AFUE" and "percent".
-.. [#] Must reference an defined ``hvacHeatingSystem.id``
+.. [#] ``heatEfficiencyUnits`` choices are "AFUE" and "fraction".
+.. [#] Must reference a defined ``hvacHeatingSystem.id``
 .. [#] Required when ``backupSystem.systemType`` is "separate".
 
 HVAC Air Distribution Systems
@@ -468,14 +472,14 @@ Property                           Type     Units                       Constrai
 ``systemType``                     string                               see [#]_        yes       "supply" and "return"   both supply and return must be defined
 ``insulationRValue``               float    F-ft2-hr/Btu                >=0             no        0   
 ``leakageValue``                   float    see ``leakageUnits``        >=0             no        BSA    
-``leakageUnits``                   string                               see [#]_        no        Percent 
+``leakageUnits``                   string                               see [#]_        no        fraction 
 ``location``                       string                               see [#]_        no        see notes [#]_
 =================================  =======  ==========================  ==============  ========  ======================  ============================================== 
 
 .. [#] ``systemType`` choices are "supply" and "return".
-.. [#] ``leakageUnits`` choices are"CFM25", "CFM50", and "percent".
-.. [#] ``location`` 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 heated space", and "other non-freezing space".
-.. [#] If ``location`` not provided, defaults to the first present space type: "basement conditioned", "basement unconditioned", "crawlspace vented", "crawlspace unvented", "attic vented", "attic unvented", "garage", or "living space".
+.. [#] ``leakageUnits`` choices are "CFM25", "CFM50", and "fraction".
+.. [#] ``location`` choices are "conditioned space", "basement conditioned", "basement unconditioned", "crawlspace unvented", "crawlspace vented", "attic unvented", "attic vented", "garage", "outside", "exterior wall", "under slab", "roof deck", "other heated space", "other non-freezing space", and "manufactured home belly".
+.. [#] If ``location`` not provided, defaults to the first present space type: "basement conditioned", "basement unconditioned", "crawlspace conditioned", "crawlspace vented", "crawlspace unvented", "attic vented", "attic unvented", "garage", or "conditioned space".
 
 HVAC Hydronic Distribution Systems
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -725,20 +729,22 @@ Property                                     Type     Units
 ``tankVolume``                               float    gal                                         no
 ``dhwLoadFraction``                          float    fraction                    0-1             yes                             sum of dhwLoadFraction must equal 1
 ``heatCapacityBtuPerHour``                   float    Btu/hr                      >0              no                              autosized by modeling engine if undefined
-``energyFactor`` or ``uniformEnergyFactor``  float    fraction                    <1              no        BSA
+``efficiency``                               float    fraction                    >0              no        BSA
+``efficiencyUnits``                          string                               see [#]_        no        BSA
 ``hotWaterTemperature``                      float    F                           >0              no        125 
 ===========================================  =======  ==========================  ==============  ========  ====================  ============================================== 
 
 .. [#] ``systemType`` choices are "storage water heater", "instantaneous water heater", "heat pump water heater", "space-heating boiler with storage tank", and "space-heating boiler with tankless coil".
 .. [#] Must reference a defined ``hvacHeatingSystem.id``. 
 .. [#] Only required when ``systemType`` is "space-heating boiler with ..."
 .. [#] ``fuel`` choices are "electricity", "natural gas", "fuel oil", "propane", "coal", "wood", and "wood pellets".
-.. [#] ``location`` choices are "living space", "basement conditioned", "basement unconditioned", "crawlspace unvented", "crawlspace vented", "attic unvented", "attic vented", "garage", “other exterior”, “other heated space”, and “other non-freezing space”.
+.. [#] ``location`` choices are "conditioned space", "basement conditioned", "basement unconditioned", "crawlspace unvented", "crawlspace vented", "attic unvented", "attic vented", "garage", “other exterior”, “other heated space”, and “other non-freezing space”.
 .. [#] If ``location`` not provided, defaults to the first present space type:
   
-  IECC zones 1-3, excluding 3A: "garage", "living space"
+  IECC zones 1-3, excluding 3A: "garage", "conditioned space"
 
-  IECC zones 3A, 4-8, unknown: "basement conditioned", "basement unconditioned", "living space"
+  IECC zones 3A, 4-8, unknown: "basement conditioned", "basement unconditioned", "conditioned space"
+.. [#] ``efficiencyUnits`` choices are "EF" and "UEF".
 
 .. _weather:
 

docs/source/automated_measures.rst renamed to docs/source/deprecated/automated_measures.rst

@@ -123,17 +123,17 @@ connected to the base building's heating and cooling systems.
 
 ``adjust`` schema for existing HVAC distribution system:
 
-  ====================  =======  ===========  ==============================================
+  ====================  =======  ===========  ========================================================
   Property              Type     Constraints  Description
-  ====================  =======  ===========  ==============================================
-  ``leakageUnits``      String   See [#]_     Duct leakage units
+  ====================  =======  ===========  ========================================================
+  ``leakageUnits``      String   See [#]_     Duct leakage units must be the same as ``baseBuilding``
   ``leakageValue``      Double   >= 0.0       Duct leakage value
   ``insulationRValue``  Double   >= 0.0
-  ====================  =======  ===========  ==============================================
+  ====================  =======  ===========  ========================================================
 
   Values can be defined and will only be applied if applicable. For example, if there isn't ``airDistribution``, then ``leakageValue`` won't be applied.
 
-  .. [#] Units choices are CFM25, CFM50, or Percent.
+  .. [#] Units choices are "CFM25", "CFM50", or "fraction".
 
 .. _existing_water_heating_system:
 
@@ -218,7 +218,7 @@ Characteristics of a new water heating system can be entered in ``automatedMeasu
   =====================  ====================  ===========  ========  =======  ===================================
   Property               Type                  Constraints  Required  Default  Description
   =====================  ====================  ===========  ========  =======  ===================================
-  ``systemType``         String                See [#]_     Yes                Type of water heating system. fuelType assumed as base heating fuel for "storage water heater" and "instantaneous water heater".
+  ``systemType``         String                See [#]_     Yes                Type of water heating system. ``fuelType`` assumed as base heating fuel for "storage water heater" and "instantaneous water heater".
   ``efficiencyClass``    String                See [#]_     Yes
   ``dhwLoadFraction``    Double                0 - 1 [#]_   No        1.0      DHW load for the new water heating system
   ``costs``              Array of :ref:`cost`               No        ``[]``   Implied costs of measure
@@ -246,6 +246,16 @@ Assumptions for ``efficiencyClass``:
   instantaneous water heater  other        N/A       N/A
   ==========================  ===========  ========  =======
 
+Assumptions for ``tankVolume`` when ``systemType`` is "heat pump water heater":
+  ===============  =============
+  Resident Count   Volume (gal)
+  ===============  =============
+  2 or less        50
+  3                65
+  4 or more        80
+  ===============  =============
+
+
 Adjust global aspects of the building
 -------------------------------------
 
@@ -280,6 +290,8 @@ Adjustments to the building air leakage rates can be entered in ``automatedMeasu
 
   .. [#] rateUnit choices are ACH or CFM.
 
+The air sealing measure is only applicable when the improved air sealing rate is less than the base rate. 
+
 .. _adjust_attic_insulation:
 
 Attic Insulation
@@ -304,6 +316,19 @@ Adjustments to existing attic insulation can be entered in ``automatedMeasures.a
   ``floorAssemblyEffectiveRValue``  Double  F-ft2-hr/Btu  > 0.0        50.6     Effective R-value of attic floor assembly
   ================================  ======  ============  ===========  =======  =======================================
 
+Attic insulation measure applicability is determined based on the difference between the base and improved assembly effective R-value using the following table.
+
+  =====================  =========================  ===========
+  Base Assembly R-Value  Improved Assembly R-Value  Applicable?
+  =====================  =========================  ===========
+  < 8.7                  < 8.7                      false
+  < 8.7                  >= 8.7                     true
+  8.7 - 20.6             < 26.6                     false
+  8.7 - 20.6             >= 26.6                    true
+  > 20.6                 < 31.6                     false
+  > 20.6                 >= 31.6                    true
+  =====================  =========================  ===========
+
 .. _adjust_thermostat:
 
 Thermostat

docs/source/extensive_inputs_and_outputs.rst renamed to docs/source/deprecated/extensive_inputs_and_outputs.rst

@@ -66,8 +66,8 @@ Download the response example with hourly datapoints here: :download:`simple_wit
    In a future release, we'll automatically compress the response payload including hourly data and inform the client
    through the `Content-Encoding` HTTP response header.
 
-Extensive
----------
+Using baseBuilding
+------------------
 
 Request
 *******
@@ -84,3 +84,22 @@ And the response will have the following structure.
 
 .. literalinclude:: examples/response/timelines/post/extensive_inputs.json
    :language: json
+
+Using automatedMeasures
+-----------------------
+
+Request
+*******
+
+Send a POST request to `/v1/timelines` with the following payload.
+
+.. literalinclude:: examples/request/timelines/post/automated_measures_new_heat_pump.json
+   :language: json
+
+Response
+********
+
+And the response will have the following structure.
+
+.. literalinclude:: examples/response/timelines/post/automated_measures_new_heat_pump.json
+   :language: json