Merge pull request #1234 from NREL/duct_shape

Updates duct effective R-values; allows duct shape inputs
NREL · Apr 25, 2024 · 40a0a4b · 40a0a4b
2 parents 8b6ec6e + 9387d16
commit 40a0a4b
Show file tree

Hide file tree

Showing 41 changed files with 56,400 additions and 54,494 deletions.
diff --git a/docs/read_the_docs/source/workflow_inputs/characteristics.rst b/docs/read_the_docs/source/workflow_inputs/characteristics.rst
@@ -1935,36 +1935,48 @@ Arguments
      - Double
      -
      - The leakage value to outside for the supply ducts.
-   * - ``ducts_return_leakage_to_outside_value``
-     - true
-     - 
-     - Double
-     -
-     - The leakage value to outside for the return ducts.
    * - ``ducts_supply_insulation_r``
      - true
      - h-ft^2-R/Btu
      - Double
      -
-     - The insulation r-value of the supply ducts excluding air films.
+     - The nominal insulation r-value of the supply ducts excluding air films. Use 0 for uninsulated ducts.
    * - ``ducts_supply_buried_insulation_level``
      - false
      - 
      - Choice
      - "auto", "not buried", "partially buried", "fully buried", "deeply buried"
      - Whether the supply ducts are buried in, e.g., attic loose-fill insulation. Partially buried ducts have insulation that does not cover the top of the ducts. Fully buried ducts have insulation that just covers the top of the ducts. Deeply buried ducts have insulation that continues above the top of the ducts.
+   * - ``ducts_supply_fraction_rectangular``
+     - false
+     - frac
+     - Double
+     - "auto"
+     - The fraction of supply ducts that are rectangular (as opposed to round); this affects the duct effective R-value used for modeling. If not provided, the OS-HPXML default (see `Air Distribution <https://openstudio-hpxml.readthedocs.io/en/v1.7.0/workflow_inputs.html#air-distribution>`_) is used.
+   * - ``ducts_return_leakage_to_outside_value``
+     - true
+     - 
+     - Double
+     -
+     - The leakage value to outside for the return ducts.
    * - ``ducts_return_insulation_r``
      - true
      - h-ft^2-R/Btu
      - Double
      -
-     - The insulation r-value of the return ducts excluding air films.
+     - The nominal insulation r-value of the return ducts excluding air films. Use 0 for uninsulated ducts.
    * - ``ducts_return_buried_insulation_level``
      - false
      - 
      - Choice
      - "auto", "not buried", "partially buried", "fully buried", "deeply buried"
      - Whether the return ducts are buried in, e.g., attic loose-fill insulation. Partially buried ducts have insulation that does not cover the top of the ducts. Fully buried ducts have insulation that just covers the top of the ducts. Deeply buried ducts have insulation that continues above the top of the ducts.
+   * - ``ducts_return_fraction_rectangular``
+     - false
+     - frac
+     - Double
+     - "auto"
+     - The fraction of return ducts that are rectangular (as opposed to round); this affects the duct effective R-value used for modeling. If not provided, the OS-HPXML default (see `Air Distribution <https://openstudio-hpxml.readthedocs.io/en/v1.7.0/workflow_inputs.html#air-distribution>`_) is used.
 
 .. _duct_location:
 

diff --git a/measures/ResStockArguments/README.md b/measures/ResStockArguments/README.md
@@ -2402,17 +2402,6 @@ The leakage value to outside for the supply ducts.
 
 <br/>
 
-**Ducts: Return Leakage to Outside Value**
-
-The leakage value to outside for the return ducts.
-
-- **Name:** ``ducts_return_leakage_to_outside_value``
-- **Type:** ``Double``
-
-- **Required:** ``true``
-
-<br/>
-
 **Ducts: Supply Location**
 
 The location of the supply ducts. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.7.0/workflow_inputs.html#air-distribution'>Air Distribution</a>) is used.
@@ -2428,7 +2417,7 @@ The location of the supply ducts. If not provided, the OS-HPXML default (see <a
 
 **Ducts: Supply Insulation R-Value**
 
-The insulation r-value of the supply ducts excluding air films.
+The nominal insulation r-value of the supply ducts excluding air films. Use 0 for uninsulated ducts.
 
 - **Name:** ``ducts_supply_insulation_r``
 - **Type:** ``Double``
@@ -2474,6 +2463,28 @@ The fraction of supply ducts surface area in the given location. Only used if Su
 
 <br/>
 
+**Ducts: Supply Fraction Rectangular**
+
+The fraction of supply ducts that are rectangular (as opposed to round); this affects the duct effective R-value used for modeling. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.7.0/workflow_inputs.html#air-distribution'>Air Distribution</a>) is used.
+
+- **Name:** ``ducts_supply_fraction_rectangular``
+- **Type:** ``String``
+
+- **Required:** ``false``
+
+<br/>
+
+**Ducts: Return Leakage to Outside Value**
+
+The leakage value to outside for the return ducts.
+
+- **Name:** ``ducts_return_leakage_to_outside_value``
+- **Type:** ``Double``
+
+- **Required:** ``true``
+
+<br/>
+
 **Ducts: Return Location**
 
 The location of the return ducts. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.7.0/workflow_inputs.html#air-distribution'>Air Distribution</a>) is used.
@@ -2489,7 +2500,7 @@ The location of the return ducts. If not provided, the OS-HPXML default (see <a
 
 **Ducts: Return Insulation R-Value**
 
-The insulation r-value of the return ducts excluding air films.
+The nominal insulation r-value of the return ducts excluding air films. Use 0 for uninsulated ducts.
 
 - **Name:** ``ducts_return_insulation_r``
 - **Type:** ``Double``
@@ -2546,6 +2557,17 @@ The number of return registers of the ducts. Only used to calculate default retu
 
 <br/>
 
+**Ducts: Return Fraction Rectangular**
+
+The fraction of return ducts that are rectangular (as opposed to round); this affects the duct effective R-value used for modeling. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.7.0/workflow_inputs.html#air-distribution'>Air Distribution</a>) is used.
+
+- **Name:** ``ducts_return_fraction_rectangular``
+- **Type:** ``String``
+
+- **Required:** ``false``
+
+<br/>
+
 **Mechanical Ventilation: Fan Type**
 
 The type of the mechanical ventilation. Use 'none' if there is no mechanical ventilation system.

diff --git a/measures/ResStockArguments/measure.xml b/measures/ResStockArguments/measure.xml
@@ -3,8 +3,8 @@
   <schema_version>3.1</schema_version>
   <name>res_stock_arguments</name>
   <uid>c984bb9e-4ac4-4930-a399-9d23f8f6936a</uid>
-  <version_id>0f5b801c-be1b-4a28-8ee1-7caf1b3bb704</version_id>
-  <version_modified>2024-04-08T20:52:19Z</version_modified>
+  <version_id>106a127b-4f0d-448a-87a9-538d2fa6415d</version_id>
+  <version_modified>2024-04-24T22:07:46Z</version_modified>
   <xml_checksum>2C38F48B</xml_checksum>
   <class_name>ResStockArguments</class_name>
   <display_name>ResStock Arguments</display_name>
@@ -3311,15 +3311,6 @@
       <model_dependent>false</model_dependent>
       <default_value>0.1</default_value>
     </argument>
-    <argument>
-      <name>ducts_return_leakage_to_outside_value</name>
-      <display_name>Ducts: Return Leakage to Outside Value</display_name>
-      <description>The leakage value to outside for the return ducts.</description>
-      <type>Double</type>
-      <required>true</required>
-      <model_dependent>false</model_dependent>
-      <default_value>0.1</default_value>
-    </argument>
     <argument>
       <name>ducts_supply_location</name>
       <display_name>Ducts: Supply Location</display_name>
@@ -3418,7 +3409,7 @@
     <argument>
       <name>ducts_supply_insulation_r</name>
       <display_name>Ducts: Supply Insulation R-Value</display_name>
-      <description>The insulation r-value of the supply ducts excluding air films.</description>
+      <description>The nominal insulation r-value of the supply ducts excluding air films. Use 0 for uninsulated ducts.</description>
       <type>Double</type>
       <units>h-ft^2-R/Btu</units>
       <required>true</required>
@@ -3474,6 +3465,24 @@
       <required>false</required>
       <model_dependent>false</model_dependent>
     </argument>
+    <argument>
+      <name>ducts_supply_fraction_rectangular</name>
+      <display_name>Ducts: Supply Fraction Rectangular</display_name>
+      <description>The fraction of supply ducts that are rectangular (as opposed to round); this affects the duct effective R-value used for modeling. If not provided, the OS-HPXML default (see &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.7.0/workflow_inputs.html#air-distribution'&gt;Air Distribution&lt;/a&gt;) is used.</description>
+      <type>String</type>
+      <units>frac</units>
+      <required>false</required>
+      <model_dependent>false</model_dependent>
+    </argument>
+    <argument>
+      <name>ducts_return_leakage_to_outside_value</name>
+      <display_name>Ducts: Return Leakage to Outside Value</display_name>
+      <description>The leakage value to outside for the return ducts.</description>
+      <type>Double</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>0.1</default_value>
+    </argument>
     <argument>
       <name>ducts_return_location</name>
       <display_name>Ducts: Return Location</display_name>
@@ -3572,7 +3581,7 @@
     <argument>
       <name>ducts_return_insulation_r</name>
       <display_name>Ducts: Return Insulation R-Value</display_name>
-      <description>The insulation r-value of the return ducts excluding air films.</description>
+      <description>The nominal insulation r-value of the return ducts excluding air films. Use 0 for uninsulated ducts.</description>
       <type>Double</type>
       <units>h-ft^2-R/Btu</units>
       <required>true</required>
@@ -3637,6 +3646,15 @@
       <required>false</required>
       <model_dependent>false</model_dependent>
     </argument>
+    <argument>
+      <name>ducts_return_fraction_rectangular</name>
+      <display_name>Ducts: Return Fraction Rectangular</display_name>
+      <description>The fraction of return ducts that are rectangular (as opposed to round); this affects the duct effective R-value used for modeling. If not provided, the OS-HPXML default (see &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.7.0/workflow_inputs.html#air-distribution'&gt;Air Distribution&lt;/a&gt;) is used.</description>
+      <type>String</type>
+      <units>frac</units>
+      <required>false</required>
+      <model_dependent>false</model_dependent>
+    </argument>
     <argument>
       <name>mech_vent_fan_type</name>
       <display_name>Mechanical Ventilation: Fan Type</display_name>
@@ -7372,7 +7390,7 @@
       <filename>README.md</filename>
       <filetype>md</filetype>
       <usage_type>readme</usage_type>
-      <checksum>BF15E74E</checksum>
+      <checksum>8577760F</checksum>
     </file>
     <file>
       <filename>README.md.erb</filename>

diff --git a/resources/hpxml-measures/BuildResidentialHPXML/README.md b/resources/hpxml-measures/BuildResidentialHPXML/README.md
@@ -2824,17 +2824,6 @@ The leakage value to outside for the supply ducts.
 
 <br/>
 
-**Ducts: Return Leakage to Outside Value**
-
-The leakage value to outside for the return ducts.
-
-- **Name:** ``ducts_return_leakage_to_outside_value``
-- **Type:** ``Double``
-
-- **Required:** ``true``
-
-<br/>
-
 **Ducts: Supply Location**
 
 The location of the supply ducts. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.7.0/workflow_inputs.html#air-distribution'>Air Distribution</a>) is used.
@@ -2850,7 +2839,7 @@ The location of the supply ducts. If not provided, the OS-HPXML default (see <a
 
 **Ducts: Supply Insulation R-Value**
 
-The insulation r-value of the supply ducts excluding air films.
+The nominal insulation r-value of the supply ducts excluding air films. Use 0 for uninsulated ducts.
 
 - **Name:** ``ducts_supply_insulation_r``
 - **Type:** ``Double``
@@ -2900,6 +2889,30 @@ The fraction of supply ducts surface area in the given location. Only used if Su
 
 <br/>
 
+**Ducts: Supply Fraction Rectangular**
+
+The fraction of supply ducts that are rectangular (as opposed to round); this affects the duct effective R-value used for modeling. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.7.0/workflow_inputs.html#air-distribution'>Air Distribution</a>) is used.
+
+- **Name:** ``ducts_supply_fraction_rectangular``
+- **Type:** ``Double``
+
+- **Units:** ``frac``
+
+- **Required:** ``false``
+
+<br/>
+
+**Ducts: Return Leakage to Outside Value**
+
+The leakage value to outside for the return ducts.
+
+- **Name:** ``ducts_return_leakage_to_outside_value``
+- **Type:** ``Double``
+
+- **Required:** ``true``
+
+<br/>
+
 **Ducts: Return Location**
 
 The location of the return ducts. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.7.0/workflow_inputs.html#air-distribution'>Air Distribution</a>) is used.
@@ -2915,7 +2928,7 @@ The location of the return ducts. If not provided, the OS-HPXML default (see <a
 
 **Ducts: Return Insulation R-Value**
 
-The insulation r-value of the return ducts excluding air films.
+The nominal insulation r-value of the return ducts excluding air films. Use 0 for uninsulated ducts.
 
 - **Name:** ``ducts_return_insulation_r``
 - **Type:** ``Double``
@@ -2978,6 +2991,19 @@ The number of return registers of the ducts. Only used to calculate default retu
 
 <br/>
 
+**Ducts: Return Fraction Rectangular**
+
+The fraction of return ducts that are rectangular (as opposed to round); this affects the duct effective R-value used for modeling. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.7.0/workflow_inputs.html#air-distribution'>Air Distribution</a>) is used.
+
+- **Name:** ``ducts_return_fraction_rectangular``
+- **Type:** ``Double``
+
+- **Units:** ``frac``
+
+- **Required:** ``false``
+
+<br/>
+
 **Mechanical Ventilation: Fan Type**
 
 The type of the mechanical ventilation. Use 'none' if there is no mechanical ventilation system.