NREL · joseph-robertson · Mar 8, 2023 · Mar 8, 2023 · Mar 8, 2023 · Mar 8, 2023
diff --git a/BuildResidentialHPXML/README.md b/BuildResidentialHPXML/README.md
@@ -3780,7 +3780,7 @@ The type of the hot water distribution system.
 
 **Hot Water Distribution: Standard Piping Length**
 
-If the distribution system is Standard, the length of the piping. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#standard'>Standard</a>) is used.
+If the distribution system is Standard or Recirculation (Shared), the length of the piping. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#standard'>Standard</a> or <a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#recirculation-shared'>Recirculation (Shared)</a>) is used.
 
 - **Name:** ``hot_water_distribution_standard_piping_length``
 - **Type:** ``Double``
@@ -3832,7 +3832,7 @@ If the distribution system is Recirculation, the length of the recirculation bra
 
 **Hot Water Distribution: Recirculation Pump Power**
 
-If the distribution system is Recirculation, the recirculation pump power. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#recirculation-in-unit'>Recirculation (In-Unit)</a>) is used.
+If the distribution system is Recirculation, the recirculation pump power. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#recirculation-in-unit'>Recirculation (In-Unit)</a> or <a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#recirculation-shared'>Recirculation (Shared)</a>) is used.
 
 - **Name:** ``hot_water_distribution_recirc_pump_power``
 - **Type:** ``Double``
@@ -3843,6 +3843,19 @@ If the distribution system is Recirculation, the recirculation pump power. If no
 
 <br/>
 
+**Hot Water Distribution: Recirculation Number of Bedrooms Served**
+
+If the distribution system is Recirculation, number of bedrooms served by the recirculation system. Only needed if single-family attached or apartment unit and it is a shared recirculation system serving multiple dwelling units. Used to apportion recirculation pump power to the unit.
+
+- **Name:** ``hot_water_distribution_recirc_num_bedrooms_served``
+- **Type:** ``Integer``
+
+- **Units:** ``#``
+
+- **Required:** ``false``
+
+<br/>
+
 **Hot Water Distribution: Pipe Insulation Nominal R-Value**
 
 Nominal R-value of the pipe insulation. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#hpxml-hot-water-distribution'>HPXML Hot Water Distribution</a>) is used.

diff --git a/BuildResidentialHPXML/measure.rb b/BuildResidentialHPXML/measure.rb
@@ -2245,7 +2245,7 @@ def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
     arg = OpenStudio::Measure::OSArgument::makeDoubleArgument('hot_water_distribution_standard_piping_length', false)
     arg.setDisplayName('Hot Water Distribution: Standard Piping Length')
     arg.setUnits('ft')
-    arg.setDescription("If the distribution system is #{HPXML::DHWDistTypeStandard}, the length of the piping. If not provided, the OS-HPXML default (see <a href='#{docs_base_url}#standard'>Standard</a>) is used.")
+    arg.setDescription("If the distribution system is #{HPXML::DHWDistTypeStandard} or #{HPXML::DHWDistTypeRecirc} (Shared), the length of the piping. If not provided, the OS-HPXML default (see <a href='#{docs_base_url}#standard'>Standard</a> or <a href='#{docs_base_url}#recirculation-shared'>Recirculation (Shared)</a>) is used.")
     args << arg
 
     recirculation_control_type_choices = OpenStudio::StringVector.new
@@ -2276,7 +2276,13 @@ def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
     arg = OpenStudio::Measure::OSArgument::makeDoubleArgument('hot_water_distribution_recirc_pump_power', false)
     arg.setDisplayName('Hot Water Distribution: Recirculation Pump Power')
     arg.setUnits('W')
-    arg.setDescription("If the distribution system is #{HPXML::DHWDistTypeRecirc}, the recirculation pump power. If not provided, the OS-HPXML default (see <a href='#{docs_base_url}#recirculation-in-unit'>Recirculation (In-Unit)</a>) is used.")
+    arg.setDescription("If the distribution system is #{HPXML::DHWDistTypeRecirc}, the recirculation pump power. If not provided, the OS-HPXML default (see <a href='#{docs_base_url}#recirculation-in-unit'>Recirculation (In-Unit)</a> or <a href='#{docs_base_url}#recirculation-shared'>Recirculation (Shared)</a>) is used.")
+    args << arg
+
+    arg = OpenStudio::Measure::OSArgument::makeIntegerArgument('hot_water_distribution_recirc_num_bedrooms_served', false)
+    arg.setDisplayName('Hot Water Distribution: Recirculation Number of Bedrooms Served')
+    arg.setDescription("If the distribution system is #{HPXML::DHWDistTypeRecirc}, number of bedrooms served by the recirculation system. Only needed if #{HPXML::ResidentialTypeSFA} or #{HPXML::ResidentialTypeApartment} and it is a shared recirculation system serving multiple dwelling units. Used to apportion recirculation pump power to the unit.")
+    arg.setUnits('#')
     args << arg
 
     arg = OpenStudio::Measure::OSArgument::makeDoubleArgument('hot_water_distribution_pipe_r', false)
@@ -6438,17 +6444,29 @@ def self.set_hot_water_distribution(hpxml_bldg, args)
       dwhr_efficiency = args[:dwhr_efficiency]
     end
 
-    if args[:hot_water_distribution_system_type] == HPXML::DHWDistTypeStandard
+    system_type = args[:hot_water_distribution_system_type]
+    if system_type == HPXML::DHWDistTypeStandard
       standard_piping_length = args[:hot_water_distribution_standard_piping_length]
+    elsif system_type == HPXML::DHWDistTypeRecirc
+      if ([HPXML::ResidentialTypeSFA, HPXML::ResidentialTypeApartment].include? args[:geometry_unit_type]) && (args[:hot_water_distribution_recirc_num_bedrooms_served].to_f > args[:geometry_unit_num_bedrooms])
+        system_type = HPXML::DHWDistTypeStandard
+        standard_piping_length = args[:hot_water_distribution_standard_piping_length]
+        has_shared_recirculation = true
+        shared_recirculation_number_of_bedrooms_served = args[:hot_water_distribution_recirc_num_bedrooms_served]
+        shared_recirculation_control_type = args[:hot_water_distribution_recirc_control_type]
+        shared_recirculation_pump_power = args[:hot_water_distribution_recirc_pump_power]
+      else
+        recirculation_control_type = args[:hot_water_distribution_recirc_control_type]
+        recirculation_piping_length = args[:hot_water_distribution_recirc_piping_length]
+        recirculation_branch_piping_length = args[:hot_water_distribution_recirc_branch_piping_length]
+        recirculation_pump_power = args[:hot_water_distribution_recirc_pump_power]
+      end
     else
-      recirculation_control_type = args[:hot_water_distribution_recirc_control_type]
-      recirculation_piping_length = args[:hot_water_distribution_recirc_piping_length]
-      recirculation_branch_piping_length = args[:hot_water_distribution_recirc_branch_piping_length]
-      recirculation_pump_power = args[:hot_water_distribution_recirc_pump_power]
+      fail 'Unexpected hot water distribution system type.'
     end
 
     hpxml_bldg.hot_water_distributions.add(id: "HotWaterDistribution#{hpxml_bldg.hot_water_distributions.size + 1}",
-                                           system_type: args[:hot_water_distribution_system_type],
+                                           system_type: system_type,
                                            standard_piping_length: standard_piping_length,
                                            recirculation_control_type: recirculation_control_type,
                                            recirculation_piping_length: recirculation_piping_length,
@@ -6457,7 +6475,11 @@ def self.set_hot_water_distribution(hpxml_bldg, args)
                                            pipe_r_value: args[:hot_water_distribution_pipe_r],
                                            dwhr_facilities_connected: dwhr_facilities_connected,
                                            dwhr_equal_flow: dwhr_equal_flow,
-                                           dwhr_efficiency: dwhr_efficiency)
+                                           dwhr_efficiency: dwhr_efficiency,
+                                           has_shared_recirculation: has_shared_recirculation,
+                                           shared_recirculation_number_of_bedrooms_served: shared_recirculation_number_of_bedrooms_served,
+                                           shared_recirculation_pump_power: shared_recirculation_pump_power,
+                                           shared_recirculation_control_type: shared_recirculation_control_type)
   end
 
   # Set the water fixtures properties, including:

diff --git a/BuildResidentialHPXML/measure.xml b/BuildResidentialHPXML/measure.xml
@@ -3,8 +3,8 @@
   <schema_version>3.1</schema_version>
   <name>build_residential_hpxml</name>
   <uid>a13a8983-2b01-4930-8af2-42030b6e4233</uid>
-  <version_id>e32945f6-3cb8-4f34-95fe-cf1733b6f48e</version_id>
-  <version_modified>2024-06-05T21:34:41Z</version_modified>
+  <version_id>56e46ec8-7083-4309-a638-751918f2bf19</version_id>
+  <version_modified>2024-06-07T22:37:43Z</version_modified>
   <xml_checksum>2C38F48B</xml_checksum>
   <class_name>BuildResidentialHPXML</class_name>
   <display_name>HPXML Builder</display_name>
@@ -4639,7 +4639,7 @@
     <argument>
       <name>hot_water_distribution_standard_piping_length</name>
       <display_name>Hot Water Distribution: Standard Piping Length</display_name>
-      <description>If the distribution system is Standard, the length of the piping. If not provided, the OS-HPXML default (see &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#standard'&gt;Standard&lt;/a&gt;) is used.</description>
+      <description>If the distribution system is Standard or Recirculation (Shared), the length of the piping. If not provided, the OS-HPXML default (see &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#standard'&gt;Standard&lt;/a&gt; or &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#recirculation-shared'&gt;Recirculation (Shared)&lt;/a&gt;) is used.</description>
       <type>Double</type>
       <units>ft</units>
       <required>false</required>
@@ -4697,12 +4697,21 @@
     <argument>
       <name>hot_water_distribution_recirc_pump_power</name>
       <display_name>Hot Water Distribution: Recirculation Pump Power</display_name>
-      <description>If the distribution system is Recirculation, the recirculation pump power. If not provided, the OS-HPXML default (see &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#recirculation-in-unit'&gt;Recirculation (In-Unit)&lt;/a&gt;) is used.</description>
+      <description>If the distribution system is Recirculation, the recirculation pump power. If not provided, the OS-HPXML default (see &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#recirculation-in-unit'&gt;Recirculation (In-Unit)&lt;/a&gt; or &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#recirculation-shared'&gt;Recirculation (Shared)&lt;/a&gt;) is used.</description>
       <type>Double</type>
       <units>W</units>
       <required>false</required>
       <model_dependent>false</model_dependent>
     </argument>
+    <argument>
+      <name>hot_water_distribution_recirc_num_bedrooms_served</name>
+      <display_name>Hot Water Distribution: Recirculation Number of Bedrooms Served</display_name>
+      <description>If the distribution system is Recirculation, number of bedrooms served by the recirculation system. Only needed if single-family attached or apartment unit and it is a shared recirculation system serving multiple dwelling units. Used to apportion recirculation pump power to the unit.</description>
+      <type>Integer</type>
+      <units>#</units>
+      <required>false</required>
+      <model_dependent>false</model_dependent>
+    </argument>
     <argument>
       <name>hot_water_distribution_pipe_r</name>
       <display_name>Hot Water Distribution: Pipe Insulation Nominal R-Value</display_name>
@@ -7343,7 +7352,7 @@
       <filename>README.md</filename>
       <filetype>md</filetype>
       <usage_type>readme</usage_type>
-      <checksum>7BEAF038</checksum>
+      <checksum>F0083F35</checksum>
     </file>
     <file>
       <filename>README.md.erb</filename>
@@ -7360,7 +7369,7 @@
       <filename>measure.rb</filename>
       <filetype>rb</filetype>
       <usage_type>script</usage_type>
-      <checksum>D0586A5E</checksum>
+      <checksum>DC0A5A15</checksum>
     </file>
     <file>
       <filename>geometry.rb</filename>

diff --git a/Changelog.md b/Changelog.md
@@ -78,6 +78,7 @@ __New Features__
   - Add soil and moisture type arguments (for determining ground conductivity and diffusivity) and optional geothermal loop arguments for ground source heat pumps.
   - The "Geometry: Building Number of Units" input is now written to the HPXML `NumberofUnitsInBuilding` element.
   - Adds a blower fan efficiency input for specifying fan power W/cfm at maximum speed.
+  - Allows specifying number of bedrooms served by the recirculation system which is used for apportioning recirculation pump power.
 - BuildResidentialScheduleFile measure:
   - Allows appending columns to an existing CSV file rather than overwriting.
   - Other plug load schedules now use Other schedule fractions per ANSI/RESNET/ICC 301-2022 Addendum C.

diff --git a/tasks.rb b/tasks.rb
@@ -1944,16 +1944,6 @@ def apply_hpxml_modification_sample_files(hpxml_path, hpxml)
       hpxml_bldg.water_heating.water_fixtures_weekday_fractions = '0.012, 0.006, 0.004, 0.005, 0.010, 0.034, 0.078, 0.087, 0.080, 0.067, 0.056, 0.047, 0.040, 0.035, 0.033, 0.031, 0.039, 0.051, 0.060, 0.060, 0.055, 0.048, 0.038, 0.026'
       hpxml_bldg.water_heating.water_fixtures_weekend_fractions = '0.012, 0.006, 0.004, 0.005, 0.010, 0.034, 0.078, 0.087, 0.080, 0.067, 0.056, 0.047, 0.040, 0.035, 0.033, 0.031, 0.039, 0.051, 0.060, 0.060, 0.055, 0.048, 0.038, 0.026'
       hpxml_bldg.water_heating.water_fixtures_monthly_multipliers = '1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0'
-    elsif ['base-bldgtype-mf-unit-shared-water-heater-recirc.xml',
-           'base-bldgtype-mf-unit-shared-water-heater-recirc-beds-0.xml',
-           'base-bldgtype-mf-unit-shared-water-heater-recirc-scheduled.xml'].include? hpxml_file
-      hpxml_bldg.hot_water_distributions[0].has_shared_recirculation = true
-      hpxml_bldg.hot_water_distributions[0].shared_recirculation_number_of_bedrooms_served = 18
-      hpxml_bldg.hot_water_distributions[0].shared_recirculation_pump_power = 220
-      hpxml_bldg.hot_water_distributions[0].shared_recirculation_control_type = HPXML::DHWRecircControlTypeTimer
-      if hpxml_file == 'base-bldgtype-mf-unit-shared-water-heater-recirc-beds-0.xml'
-        hpxml_bldg.hot_water_distributions[0].shared_recirculation_number_of_bedrooms_served = 6
-      end
     elsif ['base-bldgtype-mf-unit-shared-laundry-room.xml',
            'base-bldgtype-mf-unit-shared-laundry-room-multiple-water-heaters.xml'].include? hpxml_file
       hpxml_bldg.water_heating_systems.reverse_each do |water_heating_system|

diff --git a/workflow/hpxml_inputs.json b/workflow/hpxml_inputs.json
@@ -1266,15 +1266,27 @@
     "water_heater_num_bedrooms_served": 18
   },
   "sample_files/base-bldgtype-mf-unit-shared-water-heater-recirc.xml": {
-    "parent_hpxml": "sample_files/base-bldgtype-mf-unit-shared-water-heater.xml"
+    "parent_hpxml": "sample_files/base-bldgtype-mf-unit-shared-water-heater.xml",
+    "hot_water_distribution_system_type": "Recirculation",
+    "hot_water_distribution_recirc_control_type": "timer",
+    "hot_water_distribution_recirc_pump_power": 220.0,
+    "hot_water_distribution_recirc_num_bedrooms_served": 18
   },
   "sample_files/base-bldgtype-mf-unit-shared-water-heater-recirc-beds-0.xml": {
     "parent_hpxml": "sample_files/base-bldgtype-mf-unit-shared-water-heater.xml",
     "geometry_unit_num_bedrooms": 0,
-    "water_heater_num_bedrooms_served": 6
+    "water_heater_num_bedrooms_served": 6,
+    "hot_water_distribution_system_type": "Recirculation",
+    "hot_water_distribution_recirc_control_type": "timer",
+    "hot_water_distribution_recirc_pump_power": 220.0,
+    "hot_water_distribution_recirc_num_bedrooms_served": 6
   },
   "sample_files/base-bldgtype-mf-unit-shared-water-heater-recirc-scheduled.xml": {
-    "parent_hpxml": "sample_files/base-bldgtype-mf-unit-shared-water-heater-recirc.xml"
+    "parent_hpxml": "sample_files/base-bldgtype-mf-unit-shared-water-heater-recirc.xml",
+    "hot_water_distribution_system_type": "Recirculation",
+    "hot_water_distribution_recirc_control_type": "timer",
+    "hot_water_distribution_recirc_pump_power": 220.0,
+    "hot_water_distribution_recirc_num_bedrooms_served": 18
   },
   "sample_files/base-dhw-combi-tankless.xml": {
     "parent_hpxml": "sample_files/base-dhw-indirect.xml",