Merge pull request #1693 from NREL/sfa_mf_default_shielding

Default shielding for SFA/MF

Changelog.md

@@ -56,6 +56,7 @@ __New Features__
   - Allows additional outdoor design condition inputs: `DailyTemperatureRange` and `HumidityDifference`.
   - Adds a new detailed output file with block/space load details by surface, AED curves, etc.
   - Miscellaneous improvements.
+- Updates default `ShieldingofHome` to be "well-shielded" for single-family attached and multifamily dwelling units.
 - Improves heating/cooling component loads; for timesteps where there is no heating/cooling load, assigns heat transfer to heating or cooling by comparing indoor temperature to the average of heating/cooling setpoints.
 - Adds net energy and net electricity timeseries output columns even when there is no PV or generator.
 - Adds more error-checking for inappropriate inputs (e.g., HVAC SHR=0 or clothes washer IMEF=0).

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>508bdb29-fdfd-46d3-b1e5-bafb8f6bf404</version_id>
-  <version_modified>2024-05-15T23:06:44Z</version_modified>
+  <version_id>46f04d09-a5c8-485b-a33e-096b981224db</version_id>
+  <version_modified>2024-05-16T00:57:35Z</version_modified>
   <xml_checksum>D8922A73</xml_checksum>
   <class_name>HPXMLtoOpenStudio</class_name>
   <display_name>HPXML to OpenStudio Translator</display_name>
@@ -189,7 +189,7 @@
       <filename>airflow.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>93C49D9A</checksum>
+      <checksum>CC83F731</checksum>
     </file>
     <file>
       <filename>battery.rb</filename>
@@ -351,7 +351,7 @@
       <filename>hpxml_defaults.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>2E5372C7</checksum>
+      <checksum>EEB1E5B7</checksum>
     </file>
     <file>
       <filename>hpxml_schema/HPXML.xsd</filename>
@@ -387,7 +387,7 @@
       <filename>hvac_sizing.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>9E1BADFB</checksum>
+      <checksum>828250E9</checksum>
     </file>
     <file>
       <filename>lighting.rb</filename>
@@ -639,7 +639,7 @@
       <filename>test_defaults.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>0A047ABC</checksum>
+      <checksum>8EEC2D8E</checksum>
     </file>
     <file>
       <filename>test_enclosure.rb</filename>

HPXMLtoOpenStudio/resources/airflow.rb

@@ -282,20 +282,18 @@ def self.set_wind_speed_correction(model, site)
       site_ap.ashrae_site_terrain_exponent = 0.33 # Towns, city outskirts, center of large cities
     end
 
-    # S-G Shielding Coefficients are roughly 1/3 of AIM2 Shelter Coefficients
-    site_ap.s_g_shielding_coef = site_ap.aim2_shelter_coeff / 3.0
-  end
-
-  def self.get_aim2_shelter_coefficient(shielding_of_home)
     # Mapping based on AIM-2 Model by Walker/Wilson
-    # Table 2: Estimates of Shelter Coefficient S_wo for No Flue
-    if shielding_of_home == HPXML::ShieldingNormal
-      return 0.50 # Class 4: "Very heavy shielding, many large obstructions within one house height"
-    elsif shielding_of_home == HPXML::ShieldingExposed
-      return 0.90 # Class 2: "Light local shielding with few obstructions within two house heights"
-    elsif shielding_of_home == HPXML::ShieldingWellShielded
-      return 0.30 # Class 5: "Complete shielding, with large buildings immediately adjacent"
+    # Table 2: Estimates of Shelter Coefficient S_wo for No Flue (flue effect is handled later)
+    if site.shielding_of_home == HPXML::ShieldingNormal
+      site_ap.aim2_shelter_coeff = 0.50 # Class 4: "Very heavy shielding, many large obstructions within one house height"
+    elsif site.shielding_of_home == HPXML::ShieldingExposed
+      site_ap.aim2_shelter_coeff = 0.90 # Class 2: "Light local shielding with few obstructions within two house heights"
+    elsif site.shielding_of_home == HPXML::ShieldingWellShielded
+      site_ap.aim2_shelter_coeff = 0.30 # Class 5: "Complete shielding, with large buildings immediately adjacent"
     end
+
+    # S-G Shielding Coefficients are roughly 1/3 of AIM2 Shelter Coefficients
+    site_ap.s_g_shielding_coef = site_ap.aim2_shelter_coeff / 3.0
   end
 
   def self.apply_infiltration_to_unconditioned_space(model, space, ach, ela, c_w_SG, c_s_SG, duct_lk_imbals)
@@ -2011,7 +2009,7 @@ def self.apply_infiltration_to_conditioned(site, conditioned_ach50, conditioned_
         y_i = 0.2 # Fraction of leakage through the flue; 0.2 is a "typical" value according to THE ALBERTA AIR INFIL1RATION MODEL, Walker and Wilson, 1990
         s_wflue = 1.0 # Flue Shelter Coefficient
       else
-        y_i = 0.0 # Fraction of leakage through the flu
+        y_i = 0.0 # Fraction of leakage through the flue
         s_wflue = 0.0 # Flue Shelter Coefficient
       end
 

HPXMLtoOpenStudio/resources/hpxml_defaults.rb

@@ -664,16 +664,20 @@ def self.apply_site(hpxml_bldg)
     end
 
     if hpxml_bldg.site.shielding_of_home.nil?
-      hpxml_bldg.site.shielding_of_home = HPXML::ShieldingNormal
+      if [HPXML::ResidentialTypeApartment, HPXML::ResidentialTypeSFA].include?(hpxml_bldg.building_construction.residential_facility_type)
+        # Shielding Class 5 is ACCA MJ8 default for Table 5B/5E for townhouses and condos
+        hpxml_bldg.site.shielding_of_home = HPXML::ShieldingWellShielded
+      else
+        # Shielding Class 4 is ACCA MJ8 default for Table 5A/5D and ANSI/RESNET 301 default
+        hpxml_bldg.site.shielding_of_home = HPXML::ShieldingNormal
+      end
       hpxml_bldg.site.shielding_of_home_isdefaulted = true
     end
 
     if hpxml_bldg.site.ground_conductivity.nil?
       hpxml_bldg.site.ground_conductivity = 1.0 # Btu/hr-ft-F
       hpxml_bldg.site.ground_conductivity_isdefaulted = true
     end
-
-    hpxml_bldg.site.additional_properties.aim2_shelter_coeff = Airflow.get_aim2_shelter_coefficient(hpxml_bldg.site.shielding_of_home)
   end
 
   def self.apply_neighbor_buildings(hpxml_bldg)

HPXMLtoOpenStudio/resources/hvac_sizing.rb

@@ -1237,10 +1237,24 @@ def self.process_load_infiltration_ventilation(mj, hpxml_bldg, all_zone_loads, a
       q_fireplace = 20.0 # Assume 1 fireplace, average leakiness
     end
 
+    # Determine if we are in a higher or lower shielding class
+    # Combines the effects of terrain and wind shielding
+    shielding_class = 4
+    if hpxml_bldg.site.shielding_of_home == HPXML::ShieldingWellShielded
+      shielding_class += 1
+    elsif hpxml_bldg.site.shielding_of_home == HPXML::ShieldingExposed
+      shielding_class -= 1
+    end
+    if hpxml_bldg.site.site_type == HPXML::SiteTypeUrban
+      shielding_class += 1
+    elsif hpxml_bldg.site.site_type == HPXML::SiteTypeRural
+      shielding_class -= 1
+    end
+    shielding_class = [[shielding_class, 5].min, 1].max
+
     # Set stack/wind coefficients from Tables 5D/5E
     c_s = 0.015 * ncfl_ag
-    c_w_base = [0.0133 * hpxml_bldg.site.additional_properties.aim2_shelter_coeff - 0.0027, 0.0].max # Linear relationship between shelter coefficient and c_w coefficients by shielding class
-    c_w = c_w_base * ncfl_ag**0.4
+    c_w = (0.0065 - 0.00266 * (shielding_class - 3)) * ncfl_ag**0.4
 
     ela_in2 = UnitConversions.convert(ela, 'ft^2', 'in^2')
     windspeed_cooling_mph = 7.5 # Table 5D/5E Wind Velocity Value footnote

HPXMLtoOpenStudio/tests/test_defaults.rb

@@ -373,7 +373,15 @@ def test_site
     hpxml_bldg.site.soil_type = nil
     XMLHelper.write_file(hpxml.to_doc, @tmp_hpxml_path)
     _default_hpxml, default_hpxml_bldg = _test_measure()
-    _test_default_site_values(default_hpxml_bldg, HPXML::SiteTypeSuburban, HPXML::ShieldingNormal, 1.201923076923077, 0.025, nil, nil)
+    _test_default_site_values(default_hpxml_bldg, HPXML::SiteTypeSuburban, HPXML::ShieldingNormal, 1.202, 0.025, nil, nil)
+
+    # Test defaults w/ apartment unit
+    hpxml, hpxml_bldg = _create_hpxml('base-bldgtype-mf-unit.xml')
+    hpxml_bldg.site.site_type = nil
+    hpxml_bldg.site.shielding_of_home = nil
+    XMLHelper.write_file(hpxml.to_doc, @tmp_hpxml_path)
+    _default_hpxml, default_hpxml_bldg = _test_measure()
+    _test_default_site_values(default_hpxml_bldg, HPXML::SiteTypeSuburban, HPXML::ShieldingWellShielded, 1.0, 0.0208, HPXML::SiteSoilTypeUnknown, HPXML::SiteSoilMoistureTypeMixed)
   end
 
   def test_neighbor_buildings
@@ -4266,8 +4274,8 @@ def _test_default_building_values(hpxml_bldg, dst_enabled, dst_begin_month, dst_
   def _test_default_site_values(hpxml_bldg, site_type, shielding_of_home, ground_conductivity, ground_diffusivity, soil_type, moisture_type)
     assert_equal(site_type, hpxml_bldg.site.site_type)
     assert_equal(shielding_of_home, hpxml_bldg.site.shielding_of_home)
-    assert_equal(ground_conductivity, hpxml_bldg.site.ground_conductivity)
-    assert_equal(ground_diffusivity, hpxml_bldg.site.ground_diffusivity)
+    assert_in_epsilon(ground_conductivity, hpxml_bldg.site.ground_conductivity, 0.01)
+    assert_in_epsilon(ground_diffusivity, hpxml_bldg.site.ground_diffusivity, 0.01)
     if soil_type.nil?
       assert_nil(hpxml_bldg.site.soil_type)
     else

docs/source/workflow_inputs.rst

@@ -451,7 +451,7 @@ Site information is entered in ``/HPXML/Building/BuildingDetails/BuildingSummary
   Element                           Type      Units        Constraints  Required  Default   Notes
   ================================  ========  ===========  ===========  ========  ========  ============================================================
   ``SiteType``                      string                 See [#]_     No        suburban  Terrain type for infiltration model
-  ``ShieldingofHome``               string                 See [#]_     No        normal    Presence of nearby buildings, trees, obstructions for infiltration model
+  ``ShieldingofHome``               string                 See [#]_     No        See [#]_  Presence of nearby buildings, trees, obstructions for infiltration model
   ``Soil/SoilType``                 string                 See [#]_     No        unknown   Soil type
   ``Soil/MoistureType``             string                 See [#]_     No        mixed     Soil moisture type
   ``Soil/Conductivity``             double    Btu/hr-ft-F  > 0          No        See [#]_  Soil thermal conductivity
@@ -461,6 +461,7 @@ Site information is entered in ``/HPXML/Building/BuildingDetails/BuildingSummary
 
   .. [#] SiteType choices are "rural", "suburban", or "urban".
   .. [#] ShieldingofHome choices are "normal", "exposed", or "well-shielded".
+  .. [#] If ShieldingofHome not provided, defaults to "normal" for single-family detached or manufactured home and "well-shielded" for single-family attached or apartment unit.
   .. [#] SoilType choices are "sand", "silt", "clay", "loam", "gravel", or "unknown".
   .. [#] MoistureType choices are "dry", "wet", or "mixed".
   .. [#] If Conductivity not provided, defaults to Diffusivity / 0.0208 if Diffusivity provided, otherwise defaults based on SoilType and MoistureType:

workflow/tests/ACCA_Examples/Bell_Residence.xml

@@ -23,6 +23,7 @@
       <BuildingSummary>
         <Site>
           <SiteType>suburban</SiteType>
+          <ShieldingofHome>normal</ShieldingofHome>
           <Soil>
             <Conductivity>0.5</Conductivity>
           </Soil>

workflow/tests/ACCA_Examples/Cobb_Residence.xml

@@ -23,6 +23,7 @@
       <BuildingSummary>
         <Site>
           <SiteType>suburban</SiteType>
+          <ShieldingofHome>well-shielded</ShieldingofHome>
           <Soil>
             <Conductivity>0.8</Conductivity>
           </Soil>
@@ -154,7 +155,7 @@
             <HousePressure>50.0</HousePressure>
             <BuildingAirLeakage>
               <UnitofMeasure>ACH</UnitofMeasure>
-              <AirLeakage>4.4</AirLeakage>
+              <AirLeakage>5.9</AirLeakage>
             </BuildingAirLeakage>
           </AirInfiltrationMeasurement>
         </AirInfiltration>

workflow/tests/ACCA_Examples/Long_Residence.xml

@@ -23,6 +23,7 @@
       <BuildingSummary>
         <Site>
           <SiteType>suburban</SiteType>
+          <ShieldingofHome>normal</ShieldingofHome>
           <Soil>
             <Conductivity>0.8</Conductivity>
           </Soil>

workflow/tests/ACCA_Examples/Smith_Residence.xml

@@ -22,7 +22,7 @@
     <BuildingDetails>
       <BuildingSummary>
         <Site>
-          <SiteType>suburban</SiteType>
+          <SiteType>rural</SiteType>
           <ShieldingofHome>exposed</ShieldingofHome>
           <Soil>
             <Conductivity>0.8</Conductivity>

workflow/tests/ACCA_Examples/Vatilo_Residence.xml

@@ -23,6 +23,7 @@
       <BuildingSummary>
         <Site>
           <SiteType>suburban</SiteType>
+          <ShieldingofHome>normal</ShieldingofHome>
           <Soil>
             <Conductivity>0.8</Conductivity>
           </Soil>

workflow/tests/ACCA_Examples/Victor_Residence.xml

@@ -23,6 +23,7 @@
       <BuildingSummary>
         <Site>
           <SiteType>suburban</SiteType>
+          <ShieldingofHome>normal</ShieldingofHome>
           <Soil>
             <Conductivity>0.8</Conductivity>
           </Soil>

workflow/tests/ACCA_Examples/Walker_Residence.xml

@@ -23,6 +23,7 @@
       <BuildingSummary>
         <Site>
           <SiteType>suburban</SiteType>
+          <ShieldingofHome>normal</ShieldingofHome>
           <Soil>
             <Conductivity>0.2</Conductivity>
           </Soil>

workflow/tests/base_results/results_hers_hvac.csv

@@ -1,8 +1,8 @@
 Test Case,HVAC (kWh or therm),HVAC Fan (kWh)
-HVAC1a.xml,6277.29,805.36
-HVAC1b.xml,4660.42,805.36
-HVAC2a.xml,639.46,623.66
-HVAC2b.xml,554.19,623.66
+HVAC1a.xml,6277.0,803.89
+HVAC1b.xml,4660.12,803.89
+HVAC2a.xml,639.47,623.36
+HVAC2b.xml,554.21,623.36
 HVAC2c.xml,7623.36,1192.21
 HVAC2d.xml,4619.68,1192.21
-HVAC2e.xml,14617.8,623.66
+HVAC2e.xml,14618.09,623.36