Whole building MF inter-unit heat transfer (+ common space workaround)

Changelog.md

@@ -21,6 +21,10 @@ __New Features__
   - Allow `PVSystem/AttachedToInverter` to be omitted (unless there are multiple `Inverter` elements).
   - Allow multiple inverters with different efficiencies and use a weighted-average efficiency in the model (previously threw an error)
 - For storm windows, removes minimum base window U-factor limit and throws a warning instead if the base window U-factor is below 0.3.
+- Whole SFA/MF buildings:
+  - Allows modeling inter-unit heat transfer using the `@sameas` attribute.
+  - Documents a workaround for modeling common spaces (conditioned or unconditioned).
+  - See the [documentation](https://openstudio-hpxml.readthedocs.io/en/latest/workflow_inputs.html#whole-sfa-mf-buildings) for more information.
 
 __Bugfixes__
 - Fixes ground-source heat pump plant loop fluid type (workaround for OpenStudio bug).

HPXMLtoOpenStudio/measure.xml

@@ -3,8 +3,8 @@
   <schema_version>3.1</schema_version>
   <name>hpxm_lto_openstudio</name>
   <uid>b1543b30-9465-45ff-ba04-1d1f85e763bc</uid>
-  <version_id>ebf347a8-a3b8-4096-a72c-078aa24e7d59</version_id>
-  <version_modified>2025-10-31T18:46:56Z</version_modified>
+  <version_id>93b82c0e-c47a-49e2-8ccd-5f255039b8b7</version_id>
+  <version_modified>2025-11-03T21:57:12Z</version_modified>
   <xml_checksum>D8922A73</xml_checksum>
   <class_name>HPXMLtoOpenStudio</class_name>
   <display_name>HPXML to OpenStudio Translator</display_name>
@@ -198,7 +198,7 @@
       <filename>airflow.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>A9DCF216</checksum>
+      <checksum>61D30A7A</checksum>
     </file>
     <file>
       <filename>battery.rb</filename>
@@ -348,7 +348,7 @@
       <filename>defaults.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>73012C00</checksum>
+      <checksum>C15FB902</checksum>
     </file>
     <file>
       <filename>electric_panel.rb</filename>
@@ -372,7 +372,7 @@
       <filename>geometry.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>07196F97</checksum>
+      <checksum>6E65634E</checksum>
     </file>
     <file>
       <filename>hotwater_appliances.rb</filename>
@@ -384,7 +384,7 @@
       <filename>hpxml.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>26FF824B</checksum>
+      <checksum>48EB5D1E</checksum>
     </file>
     <file>
       <filename>hpxml_schema/HPXML.xsd</filename>
@@ -402,7 +402,7 @@
       <filename>hpxml_schematron/EPvalidator.sch</filename>
       <filetype>sch</filetype>
       <usage_type>resource</usage_type>
-      <checksum>565E6550</checksum>
+      <checksum>D64CA904</checksum>
     </file>
     <file>
       <filename>hpxml_schematron/iso-schematron.xsd</filename>
@@ -420,7 +420,7 @@
       <filename>hvac_sizing.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>AFA48130</checksum>
+      <checksum>9A9AFA80</checksum>
     </file>
     <file>
       <filename>internal_gains.rb</filename>
@@ -474,7 +474,7 @@
       <filename>model.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>E01BEB72</checksum>
+      <checksum>4FD33DD9</checksum>
     </file>
     <file>
       <filename>output.rb</filename>
@@ -720,7 +720,7 @@
       <filename>test_airflow.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>709B2033</checksum>
+      <checksum>8113A3BB</checksum>
     </file>
     <file>
       <filename>test_battery.rb</filename>
@@ -810,7 +810,7 @@
       <filename>test_validation.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>A339372A</checksum>
+      <checksum>B2E99976</checksum>
     </file>
     <file>
       <filename>test_vehicle.rb</filename>

HPXMLtoOpenStudio/resources/airflow.rb

@@ -210,7 +210,7 @@ def self.get_values_from_air_infiltration_measurements(hpxml_bldg, weather)
     cfa = hpxml_bldg.building_construction.conditioned_floor_area
     measurement = get_infiltration_measurement_of_interest(hpxml_bldg)
 
-    default_infil_height, default_infil_volume = Defaults.get_infiltration_height_and_volume(hpxml_bldg)
+    default_infil_height, default_infil_volume = Defaults.get_infiltration_height_and_volume(hpxml_bldg, nil)
     infil_volume = measurement.infiltration_volume
     infil_volume = default_infil_volume if infil_volume.nil?
     infil_height = measurement.infiltration_height

HPXMLtoOpenStudio/resources/defaults.rb

@@ -57,8 +57,8 @@ def self.apply(runner, hpxml, hpxml_bldg, weather, schedules_file: nil, convert_
     apply_building_construction(hpxml.header, hpxml_bldg)
     apply_zone_spaces(hpxml_bldg)
     apply_climate_and_risk_zones(hpxml_bldg, weather, unit_num)
-    apply_attics(hpxml_bldg)
-    apply_foundations(hpxml_bldg)
+    apply_attics(hpxml_bldg, unit_num)
+    apply_foundations(hpxml_bldg, unit_num)
     apply_roofs(hpxml_bldg)
     apply_rim_joists(hpxml_bldg)
     apply_walls(hpxml_bldg)
@@ -73,7 +73,7 @@ def self.apply(runner, hpxml, hpxml_bldg, weather, schedules_file: nil, convert_
     apply_hvac(runner, hpxml_bldg, weather, convert_shared_systems, unit_num, hpxml.header)
     apply_hvac_control(hpxml_bldg, schedules_file, eri_version)
     apply_hvac_distribution(hpxml_bldg)
-    apply_infiltration(hpxml_bldg)
+    apply_infiltration(hpxml_bldg, unit_num)
     apply_hvac_location(hpxml_bldg)
     apply_ventilation_fans(hpxml_bldg, weather, eri_version)
     apply_water_heaters(hpxml_bldg, eri_version, schedules_file)
@@ -160,12 +160,12 @@ def self.unspin_azimuth(azimuth)
   # @return [nil]
   def self.add_zones_spaces_if_needed(hpxml_bldg, unit_num)
     if hpxml_bldg.conditioned_zones.empty?
-      hpxml_bldg.zones.add(id: "#{Constants::AutomaticallyAdded}Zone#{unit_num}",
+      hpxml_bldg.zones.add(id: get_id("#{Constants::AutomaticallyAdded}Zone", hpxml_bldg.conditioned_zones, unit_num),
                            zone_type: HPXML::ZoneTypeConditioned)
       hpxml_bldg.hvac_systems.each do |hvac_system|
         hvac_system.attached_to_zone_idref = hpxml_bldg.zones[-1].id
       end
-      hpxml_bldg.zones[-1].spaces.add(id: "#{Constants::AutomaticallyAdded}Space#{unit_num}",
+      hpxml_bldg.zones[-1].spaces.add(id: get_id("#{Constants::AutomaticallyAdded}Space", hpxml_bldg.conditioned_spaces, unit_num),
                                       floor_area: hpxml_bldg.building_construction.conditioned_floor_area)
       hpxml_bldg.surfaces.each do |surface|
         next unless HPXML::conditioned_locations_this_unit.include? surface.interior_adjacent_to
@@ -968,12 +968,13 @@ def self.apply_climate_and_risk_zones(hpxml_bldg, weather, unit_num)
   # Assigns default values for omitted optional inputs in the HPXML::Attic objects
   #
   # @param hpxml_bldg [HPXML::Building] HPXML Building object representing an individual dwelling unit
+  # @param unit_num [Integer] Dwelling unit number
   # @return [nil]
-  def self.apply_attics(hpxml_bldg)
+  def self.apply_attics(hpxml_bldg, unit_num)
     if hpxml_bldg.has_location(HPXML::LocationAtticUnvented)
       unvented_attics = hpxml_bldg.attics.select { |a| a.attic_type == HPXML::AtticTypeUnvented }
       if unvented_attics.empty?
-        hpxml_bldg.attics.add(id: 'UnventedAttic',
+        hpxml_bldg.attics.add(id: get_id('UnventedAttic', hpxml_bldg.attics, unit_num),
                               attic_type: HPXML::AtticTypeUnvented)
         unvented_attics << hpxml_bldg.attics[-1]
       end
@@ -991,7 +992,7 @@ def self.apply_attics(hpxml_bldg)
     if hpxml_bldg.has_location(HPXML::LocationAtticVented)
       vented_attics = hpxml_bldg.attics.select { |a| a.attic_type == HPXML::AtticTypeVented }
       if vented_attics.empty?
-        hpxml_bldg.attics.add(id: 'VentedAttic',
+        hpxml_bldg.attics.add(id: get_id('VentedAttic', hpxml_bldg.attics, unit_num),
                               attic_type: HPXML::AtticTypeVented)
         vented_attics << hpxml_bldg.attics[-1]
       end
@@ -1013,12 +1014,13 @@ def self.apply_attics(hpxml_bldg)
   # Assigns default values for omitted optional inputs in the HPXML::Foundation objects
   #
   # @param hpxml_bldg [HPXML::Building] HPXML Building object representing an individual dwelling unit
+  # @param unit_num [Integer] Dwelling unit number
   # @return [nil]
-  def self.apply_foundations(hpxml_bldg)
+  def self.apply_foundations(hpxml_bldg, unit_num)
     if hpxml_bldg.has_location(HPXML::LocationCrawlspaceUnvented)
       unvented_crawls = hpxml_bldg.foundations.select { |f| f.foundation_type == HPXML::FoundationTypeCrawlspaceUnvented }
       if unvented_crawls.empty?
-        hpxml_bldg.foundations.add(id: 'UnventedCrawlspace',
+        hpxml_bldg.foundations.add(id: get_id('UnventedCrawlspace', hpxml_bldg.foundations, unit_num),
                                    foundation_type: HPXML::FoundationTypeCrawlspaceUnvented)
         unvented_crawls << hpxml_bldg.foundations[-1]
       end
@@ -1036,7 +1038,7 @@ def self.apply_foundations(hpxml_bldg)
     if hpxml_bldg.has_location(HPXML::LocationCrawlspaceConditioned)
       cond_crawls = hpxml_bldg.foundations.select { |f| f.foundation_type == HPXML::FoundationTypeCrawlspaceConditioned }
       if cond_crawls.empty?
-        hpxml_bldg.foundations.add(id: 'ConditionedCrawlspace',
+        hpxml_bldg.foundations.add(id: get_id('ConditionedCrawlspace', hpxml_bldg.foundations, unit_num),
                                    foundation_type: HPXML::FoundationTypeCrawlspaceConditioned)
         cond_crawls << hpxml_bldg.foundations[-1]
       end
@@ -1054,7 +1056,7 @@ def self.apply_foundations(hpxml_bldg)
     if hpxml_bldg.has_location(HPXML::LocationBasementUnconditioned)
       uncond_bsmts = hpxml_bldg.foundations.select { |f| f.foundation_type == HPXML::FoundationTypeBasementUnconditioned }
       if uncond_bsmts.empty?
-        hpxml_bldg.foundations.add(id: 'UnconditionedBasement',
+        hpxml_bldg.foundations.add(id: get_id('UnconditionedBasement', hpxml_bldg.foundations, unit_num),
                                    foundation_type: HPXML::FoundationTypeBasementUnconditioned)
         uncond_bsmts << hpxml_bldg.foundations[-1]
       end
@@ -1072,7 +1074,7 @@ def self.apply_foundations(hpxml_bldg)
     if hpxml_bldg.has_location(HPXML::LocationBasementConditioned)
       cond_bsmts = hpxml_bldg.foundations.select { |f| f.foundation_type == HPXML::FoundationTypeBasementConditioned }
       if cond_bsmts.empty?
-        hpxml_bldg.foundations.add(id: 'ConditionedBasement',
+        hpxml_bldg.foundations.add(id: get_id('ConditionedBasement', hpxml_bldg.foundations, unit_num),
                                    foundation_type: HPXML::FoundationTypeBasementConditioned)
         cond_bsmts << hpxml_bldg.foundations[-1]
       end
@@ -1090,7 +1092,7 @@ def self.apply_foundations(hpxml_bldg)
     if hpxml_bldg.has_location(HPXML::LocationCrawlspaceVented)
       vented_crawls = hpxml_bldg.foundations.select { |f| f.foundation_type == HPXML::FoundationTypeCrawlspaceVented }
       if vented_crawls.empty?
-        hpxml_bldg.foundations.add(id: 'VentedCrawlspace',
+        hpxml_bldg.foundations.add(id: get_id('VentedCrawlspace', hpxml_bldg.foundations, unit_num),
                                    foundation_type: HPXML::FoundationTypeCrawlspaceVented)
         vented_crawls << hpxml_bldg.foundations[-1]
       end
@@ -1108,7 +1110,7 @@ def self.apply_foundations(hpxml_bldg)
     if hpxml_bldg.has_location(HPXML::LocationManufacturedHomeUnderBelly)
       belly_and_wing_foundations = hpxml_bldg.foundations.select { |f| f.foundation_type == HPXML::FoundationTypeBellyAndWing }
       if belly_and_wing_foundations.empty?
-        hpxml_bldg.foundations.add(id: 'BellyAndWing',
+        hpxml_bldg.foundations.add(id: get_id('BellyAndWing', hpxml_bldg.foundations, unit_num),
                                    foundation_type: HPXML::FoundationTypeBellyAndWing)
         belly_and_wing_foundations << hpxml_bldg.foundations[-1]
       end
@@ -1129,10 +1131,11 @@ def self.apply_foundations(hpxml_bldg)
   # Note: This needs to be called after we have applied defaults for ducts.
   #
   # @param hpxml_bldg [HPXML::Building] HPXML Building object representing an individual dwelling unit
+  # @param unit_num [Integer] Dwelling unit number
   # @return [nil]
-  def self.apply_infiltration(hpxml_bldg)
+  def self.apply_infiltration(hpxml_bldg, unit_num)
     infil_measurement = Airflow.get_infiltration_measurement_of_interest(hpxml_bldg)
-    default_infil_height, default_infil_volume = get_infiltration_height_and_volume(hpxml_bldg)
+    default_infil_height, default_infil_volume = get_infiltration_height_and_volume(hpxml_bldg, unit_num)
     if infil_measurement.infiltration_volume.nil?
       infil_measurement.infiltration_volume = default_infil_volume
       infil_measurement.infiltration_volume_isdefaulted = true
@@ -1213,7 +1216,7 @@ def self.apply_infiltration(hpxml_bldg)
     if infil_measurement.a_ext.nil?
       if (infil_measurement.infiltration_type == HPXML::InfiltrationTypeUnitTotal) &&
          [HPXML::ResidentialTypeApartment, HPXML::ResidentialTypeSFA].include?(hpxml_bldg.building_construction.residential_facility_type)
-        tot_cb_area, ext_cb_area = get_compartmentalization_boundary_areas(hpxml_bldg)
+        tot_cb_area, ext_cb_area = get_compartmentalization_boundary_areas(hpxml_bldg, unit_num)
         infil_measurement.a_ext = (ext_cb_area / tot_cb_area).round(5)
         infil_measurement.a_ext_isdefaulted = true
       end
@@ -1286,6 +1289,8 @@ def self.apply_roofs(hpxml_bldg)
   # @return [nil]
   def self.apply_rim_joists(hpxml_bldg)
     hpxml_bldg.rim_joists.each do |rim_joist|
+      next if rim_joist.sameas_id
+
       if rim_joist.azimuth.nil?
         rim_joist.azimuth = get_azimuth_from_orientation(rim_joist.orientation)
         rim_joist.azimuth_isdefaulted = true
@@ -1325,6 +1330,8 @@ def self.apply_rim_joists(hpxml_bldg)
   # @return [nil]
   def self.apply_walls(hpxml_bldg)
     hpxml_bldg.walls.each do |wall|
+      next if wall.sameas_id
+
       if wall.azimuth.nil?
         wall.azimuth = get_azimuth_from_orientation(wall.orientation)
         wall.azimuth_isdefaulted = true
@@ -1388,6 +1395,8 @@ def self.apply_walls(hpxml_bldg)
   # @return [nil]
   def self.apply_foundation_walls(hpxml_bldg)
     hpxml_bldg.foundation_walls.each do |foundation_wall|
+      next if foundation_wall.sameas_id
+
       if foundation_wall.type.nil?
         foundation_wall.type = HPXML::FoundationWallTypeSolidConcrete
         foundation_wall.type_isdefaulted = true
@@ -1448,6 +1457,8 @@ def self.apply_foundation_walls(hpxml_bldg)
   # @return [nil]
   def self.apply_floors(runner, hpxml_bldg)
     hpxml_bldg.floors.each do |floor|
+      next if floor.sameas_id
+
       if floor.floor_or_ceiling.nil?
         if floor.is_ceiling
           floor.floor_or_ceiling = HPXML::FloorOrCeilingCeiling
@@ -5743,12 +5754,13 @@ def self.get_mech_vent_fan_efficiency(vent_fan)
   # volume plus the volume of any spaces within the infiltration volume.
   #
   # @param hpxml_bldg [HPXML::Building] HPXML Building object representing an individual dwelling unit
+  # @param unit_num [Integer] Dwelling unit number
   # @return [Double, Double] Default infiltration height (ft) and volume (ft3)
-  def self.get_infiltration_height_and_volume(hpxml_bldg)
+  def self.get_infiltration_height_and_volume(hpxml_bldg, unit_num)
     # Make sure AverageCeilingHeight & WithinInfiltrationVolume properties have been set
     apply_building_construction(nil, hpxml_bldg)
-    apply_attics(hpxml_bldg)
-    apply_foundations(hpxml_bldg)
+    apply_attics(hpxml_bldg, unit_num)
+    apply_foundations(hpxml_bldg, unit_num)
 
     # Get base infiltration height, excluding foundations and attics
     avg_ceiling_height = hpxml_bldg.building_construction.average_ceiling_height
@@ -5816,11 +5828,12 @@ def self.get_infiltration_height_and_volume(hpxml_bldg)
   # Source: ANSI/RESNET/ICC 301
   #
   # @param hpxml_bldg [HPXML::Building] HPXML Building object representing an individual dwelling unit
+  # @param unit_num [Integer] Dwelling unit number
   # @return [Array<Double, Double>] Total and exterior compartmentalization areas (ft2)
-  def self.get_compartmentalization_boundary_areas(hpxml_bldg)
+  def self.get_compartmentalization_boundary_areas(hpxml_bldg, unit_num)
     # Make sure WithinInfiltrationVolume properties have been set
-    apply_attics(hpxml_bldg)
-    apply_foundations(hpxml_bldg)
+    apply_attics(hpxml_bldg, unit_num)
+    apply_foundations(hpxml_bldg, unit_num)
 
     total_area = 0.0 # Total surface area that bounds the Infiltration Volume
     exterior_area = 0.0 # Same as above excluding surfaces attached to garage, other housing units, or other multifamily spaces