Merge pull request #701 from NREL/ansi_301_2022

ANSI 301-2022

.github/pull_request_template.md

@@ -9,10 +9,10 @@ PR Author: Check these when they're done. Not all may apply. ~~strikethrough~~ a
 PR Reviewer: Verify each has been completed.
 
 - [ ] OS-HPXML git subtree has been pulled
-- [ ] 301/ES rulesets and unit tests have been updated
 - [ ] 301validator.xml has been updated (reference EPvalidator.xml)
-- [ ] Workflow tests have been updated
+- [ ] Sample files have been added/updated (`openstudio tasks.rb update_hpxmls`)
+- [ ] Tests have been added/updated (e.g., `rulesets\tests` and/or `workflow/tests/*_test.rb`)
 - [ ] Documentation has been updated
 - [ ] Changelog has been updated
 - [ ] `openstudio tasks.rb update_measures` has been run
-- [ ] No unexpected regression test changes on CI
+- [ ] No unexpected changes to simulation results on CI

Changelog.md

@@ -1,10 +1,15 @@
 ## OpenStudio-ERI v1.8.0
 
 __New Features__
+- Implements ANSI/RESNET/ICC Standard 301-2022 and Addendum C.
+  - `ERICalculation/Version` and `CO2IndexCalculation/Version` can now be "2022C" or "2022".
+  - Allows modeling electric battery storage, including shared batteries ("2022C" or newer).
+  - The `ElectricAuxiliaryEnergy` input for boilers is no longer used.
 - **Breaking change**: Each `VentilationFan` must have one (and only one) `UsedFor...` element set to true.
 - Ground source heat pump model enhancements.
 - Allows `Roof/RadiantBarrier` to be omitted; defaults to false.
 - Adds more error-checking for inappropriate inputs (e.g., HVAC SHR=0 or clothes washer IMEF=0).
+- Allows `FractionDuctArea` as alternative to `DuctSurfaceArea`
 - Now defaults to -20F for `CompressorLockoutTemperature` for variable-speed air-to-air heat pumps.
 - Clarifies that Capacity=-1 can be used to autosize HVAC equipment for research purposes or to run tests.
   - It should *not* be used for a real home; a warning will be issued when it's used.

docs/source/capabilities.rst

@@ -5,8 +5,9 @@ ERI Capabilities
 ----------------
 The following ERI Standards are supported:
 
-- ANSI/RESNET/ICC 301-2014© Standard for the Calculation and Labeling of the Energy Performance of Low-Rise Residential Buildings using an Energy Rating Index
-- ANSI/RESNET/ICC 301-2019 Standard for the Calculation and Labeling of the Energy Performance of Dwelling and Sleeping Units using an Energy Rating Index
+- ANSI/RESNET/ICC 301-2014
+- ANSI/RESNET/ICC 301-2019
+- ANSI/RESNET/ICC 301-2022
 
 The following ENERGY STAR programs/versions are supported:
 

hpxml-measures/BuildResidentialHPXML/README.md

@@ -3669,6 +3669,17 @@ Multiplier on the hot water usage that can reflect, e.g., high/low usage occupan
 
 <br/>
 
+**General Water Use: Usage Multiplier**
+
+Multiplier on internal gains from general water use (floor mopping, shower evaporation, water films on showers, tubs & sinks surfaces, plant watering, etc.) that can reflect, e.g., high/low usage occupants. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.7.0/workflow_inputs.html#hpxml-building-occupancy'>HPXML Building Occupancy</a>) is used.
+
+- **Name:** ``general_water_use_usage_multiplier``
+- **Type:** ``Double``
+
+- **Required:** ``false``
+
+<br/>
+
 **Solar Thermal: System Type**
 
 The type of solar thermal system. Use 'none' if there is no solar thermal system.
@@ -4086,6 +4097,19 @@ The round trip efficiency of the lithium ion battery. If not provided, the OS-HP
 
 <br/>
 
+**Battery: Number of Bedrooms Served**
+
+Number of bedrooms served by the lithium ion battery. Required if single-family attached or apartment unit. Used to apportion battery charging/discharging to the unit of a SFA/MF building.
+
+- **Name:** ``battery_num_bedrooms_served``
+- **Type:** ``Integer``
+
+- **Units:** ``#``
+
+- **Required:** ``false``
+
+<br/>
+
 **Lighting: Present**
 
 Whether there is lighting energy use.

hpxml-measures/BuildResidentialHPXML/measure.rb

@@ -2128,16 +2128,16 @@ def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
     args << arg
 
     recirculation_control_type_choices = OpenStudio::StringVector.new
-    recirculation_control_type_choices << HPXML::DHWRecirControlTypeNone
-    recirculation_control_type_choices << HPXML::DHWRecirControlTypeTimer
-    recirculation_control_type_choices << HPXML::DHWRecirControlTypeTemperature
-    recirculation_control_type_choices << HPXML::DHWRecirControlTypeSensor
-    recirculation_control_type_choices << HPXML::DHWRecirControlTypeManual
+    recirculation_control_type_choices << HPXML::DHWRecircControlTypeNone
+    recirculation_control_type_choices << HPXML::DHWRecircControlTypeTimer
+    recirculation_control_type_choices << HPXML::DHWRecircControlTypeTemperature
+    recirculation_control_type_choices << HPXML::DHWRecircControlTypeSensor
+    recirculation_control_type_choices << HPXML::DHWRecircControlTypeManual
 
     arg = OpenStudio::Measure::OSArgument::makeChoiceArgument('hot_water_distribution_recirc_control_type', recirculation_control_type_choices, false)
     arg.setDisplayName('Hot Water Distribution: Recirculation Control Type')
     arg.setDescription("If the distribution system is #{HPXML::DHWDistTypeRecirc}, the type of hot water recirculation control, if any.")
-    arg.setDefaultValue(HPXML::DHWRecirControlTypeNone)
+    arg.setDefaultValue(HPXML::DHWRecircControlTypeNone)
     args << arg
 
     arg = OpenStudio::Measure::OSArgument::makeDoubleArgument('hot_water_distribution_recirc_piping_length', false)
@@ -2205,6 +2205,11 @@ def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
     arg.setDescription("Multiplier on the hot water usage that can reflect, e.g., high/low usage occupants. If not provided, the OS-HPXML default (see <a href='#{docs_base_url}#hpxml-water-fixtures'>HPXML Water Fixtures</a>) is used.")
     args << arg
 
+    arg = OpenStudio::Measure::OSArgument::makeDoubleArgument('general_water_use_usage_multiplier', false)
+    arg.setDisplayName('General Water Use: Usage Multiplier')
+    arg.setDescription("Multiplier on internal gains from general water use (floor mopping, shower evaporation, water films on showers, tubs & sinks surfaces, plant watering, etc.) that can reflect, e.g., high/low usage occupants. If not provided, the OS-HPXML default (see <a href='#{docs_base_url}#hpxml-building-occupancy'>HPXML Building Occupancy</a>) is used.")
+    args << arg
+
     solar_thermal_system_type_choices = OpenStudio::StringVector.new
     solar_thermal_system_type_choices << 'none'
     solar_thermal_system_type_choices << HPXML::SolarThermalSystemType
@@ -2452,6 +2457,12 @@ def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
     arg.setUnits('Frac')
     args << arg
 
+    arg = OpenStudio::Measure::OSArgument::makeIntegerArgument('battery_num_bedrooms_served', false)
+    arg.setDisplayName('Battery: Number of Bedrooms Served')
+    arg.setDescription("Number of bedrooms served by the lithium ion battery. Required if #{HPXML::ResidentialTypeSFA} or #{HPXML::ResidentialTypeApartment}. Used to apportion battery charging/discharging to the unit of a SFA/MF building.")
+    arg.setUnits('#')
+    args << arg
+
     arg = OpenStudio::Measure::OSArgument::makeBoolArgument('lighting_present', true)
     arg.setDisplayName('Lighting: Present')
     arg.setDescription('Whether there is lighting energy use.')
@@ -4315,6 +4326,9 @@ def self.set_building_occupancy(hpxml_bldg, args)
     if args[:geometry_unit_num_occupants].is_initialized
       hpxml_bldg.building_occupancy.number_of_residents = args[:geometry_unit_num_occupants].get
     end
+    if args[:general_water_use_usage_multiplier].is_initialized
+      hpxml_bldg.building_occupancy.general_water_use_usage_multiplier = args[:general_water_use_usage_multiplier].get
+    end
   end
 
   def self.set_building_construction(hpxml_bldg, args)
@@ -6401,13 +6415,22 @@ def self.set_battery(hpxml_bldg, args)
       round_trip_efficiency = args[:battery_round_trip_efficiency].get
     end
 
+    if [HPXML::ResidentialTypeSFA, HPXML::ResidentialTypeApartment].include? args[:geometry_unit_type]
+      if args[:battery_num_bedrooms_served].get > args[:geometry_unit_num_bedrooms]
+        is_shared_system = true
+        number_of_bedrooms_served = args[:battery_num_bedrooms_served].get
+      end
+    end
+
     hpxml_bldg.batteries.add(id: "Battery#{hpxml_bldg.batteries.size + 1}",
                              type: HPXML::BatteryTypeLithiumIon,
                              location: location,
                              rated_power_output: rated_power_output,
                              nominal_capacity_kwh: nominal_capacity_kwh,
                              usable_capacity_kwh: usable_capacity_kwh,
-                             round_trip_efficiency: round_trip_efficiency)
+                             round_trip_efficiency: round_trip_efficiency,
+                             is_shared_system: is_shared_system,
+                             number_of_bedrooms_served: number_of_bedrooms_served)
   end
 
   def self.set_lighting(hpxml_bldg, args)

hpxml-measures/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>1ad6ba02-2bb2-4bbc-81d6-29cbeb4fd106</version_id>
-  <version_modified>2024-01-31T16:50:00Z</version_modified>
+  <version_id>f2656ed9-4491-4e74-93ae-ad65beb77be6</version_id>
+  <version_modified>2024-02-01T23:33:18Z</version_modified>
   <xml_checksum>2C38F48B</xml_checksum>
   <class_name>BuildResidentialHPXML</class_name>
   <display_name>HPXML Builder</display_name>
@@ -4625,6 +4625,14 @@
       <required>false</required>
       <model_dependent>false</model_dependent>
     </argument>
+    <argument>
+      <name>general_water_use_usage_multiplier</name>
+      <display_name>General Water Use: Usage Multiplier</display_name>
+      <description>Multiplier on internal gains from general water use (floor mopping, shower evaporation, water films on showers, tubs &amp; sinks surfaces, plant watering, etc.) that can reflect, e.g., high/low usage occupants. If not provided, the OS-HPXML default (see &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.7.0/workflow_inputs.html#hpxml-building-occupancy'&gt;HPXML Building Occupancy&lt;/a&gt;) is used.</description>
+      <type>Double</type>
+      <required>false</required>
+      <model_dependent>false</model_dependent>
+    </argument>
     <argument>
       <name>solar_thermal_system_type</name>
       <display_name>Solar Thermal: System Type</display_name>
@@ -5133,6 +5141,15 @@
       <required>false</required>
       <model_dependent>false</model_dependent>
     </argument>
+    <argument>
+      <name>battery_num_bedrooms_served</name>
+      <display_name>Battery: Number of Bedrooms Served</display_name>
+      <description>Number of bedrooms served by the lithium ion battery. Required if single-family attached or apartment unit. Used to apportion battery charging/discharging to the unit of a SFA/MF building.</description>
+      <type>Integer</type>
+      <units>#</units>
+      <required>false</required>
+      <model_dependent>false</model_dependent>
+    </argument>
     <argument>
       <name>lighting_present</name>
       <display_name>Lighting: Present</display_name>
@@ -7132,7 +7149,7 @@
       <filename>README.md</filename>
       <filetype>md</filetype>
       <usage_type>readme</usage_type>
-      <checksum>25A31E46</checksum>
+      <checksum>A8644FE1</checksum>
     </file>
     <file>
       <filename>README.md.erb</filename>
@@ -7149,7 +7166,7 @@
       <filename>measure.rb</filename>
       <filetype>rb</filetype>
       <usage_type>script</usage_type>
-      <checksum>1F8CBA31</checksum>
+      <checksum>538AD9A0</checksum>
     </file>
     <file>
       <filename>geometry.rb</filename>
@@ -7161,7 +7178,7 @@
       <filename>test_build_residential_hpxml.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>85F5709E</checksum>
+      <checksum>63FD5BD3</checksum>
     </file>
   </files>
 </measure>

hpxml-measures/BuildResidentialHPXML/tests/test_build_residential_hpxml.rb

@@ -562,7 +562,7 @@ def _set_measure_argument_values(hpxml_file, args)
       args['water_heater_num_units_served'] = 1
       args['hot_water_distribution_system_type'] = HPXML::DHWDistTypeStandard
       args['hot_water_distribution_standard_piping_length'] = 50
-      args['hot_water_distribution_recirc_control_type'] = HPXML::DHWRecirControlTypeNone
+      args['hot_water_distribution_recirc_control_type'] = HPXML::DHWRecircControlTypeNone
       args['hot_water_distribution_recirc_piping_length'] = 50
       args['hot_water_distribution_recirc_branch_piping_length'] = 50
       args['hot_water_distribution_recirc_pump_power'] = 50

hpxml-measures/BuildResidentialScheduleFile/measure.xml

@@ -3,8 +3,8 @@
   <schema_version>3.1</schema_version>
   <name>build_residential_schedule_file</name>
   <uid>f770b2db-1a9f-4e99-99a7-7f3161a594b1</uid>
-  <version_id>3606c838-78bd-44c3-a156-89c18187577f</version_id>
-  <version_modified>2024-01-22T22:47:29Z</version_modified>
+  <version_id>2302dda7-e4bb-4acd-9d56-7d33c175f30f</version_id>
+  <version_modified>2024-02-07T22:56:16Z</version_modified>
   <xml_checksum>03F02484</xml_checksum>
   <class_name>BuildResidentialScheduleFile</class_name>
   <display_name>Schedule File Builder</display_name>
@@ -150,7 +150,7 @@
       <filename>constants.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>EED44A60</checksum>
+      <checksum>665E2812</checksum>
     </file>
     <file>
       <filename>cooking_consumption_dist.csv</filename>
@@ -204,7 +204,7 @@
       <filename>schedules.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>8365F2E1</checksum>
+      <checksum>B2F4A689</checksum>
     </file>
     <file>
       <filename>schedules_config.md</filename>

hpxml-measures/BuildResidentialScheduleFile/resources/constants.rb

@@ -13,6 +13,22 @@ def self.CeilingFanWeekendFractions
     return '0.04, 0.037, 0.037, 0.036, 0.033, 0.036, 0.043, 0.047, 0.034, 0.023, 0.024, 0.025, 0.024, 0.028, 0.031, 0.032, 0.039, 0.053, 0.063, 0.067, 0.071, 0.069, 0.059, 0.05'
   end
 
+  def self.LightingInteriorMonthlyMultipliers
+    return '1.075, 1.064951905, 1.0375, 1.0, 0.9625, 0.935048095, 0.925, 0.935048095, 0.9625, 1.0, 1.0375, 1.064951905'
+  end
+
+  def self.PlugLoadsOtherWeekdayFractions
+    return '0.035, 0.033, 0.032, 0.031, 0.032, 0.033, 0.037, 0.042, 0.043, 0.043, 0.043, 0.044, 0.045, 0.045, 0.044, 0.046, 0.048, 0.052, 0.053, 0.05, 0.047, 0.045, 0.04, 0.036'
+  end
+
+  def self.PlugLoadsOtherWeekendFractions
+    return '0.035, 0.033, 0.032, 0.031, 0.032, 0.033, 0.037, 0.042, 0.043, 0.043, 0.043, 0.044, 0.045, 0.045, 0.044, 0.046, 0.048, 0.052, 0.053, 0.05, 0.047, 0.045, 0.04, 0.036'
+  end
+
+  def self.PlugLoadsOtherMonthlyMultipliers
+    return '1.248, 1.257, 0.993, 0.989, 0.993, 0.827, 0.821, 0.821, 0.827, 0.99, 0.987, 1.248'
+  end
+
   def self.SinkDurationProbability
     return '0.901242, 0.076572, 0.01722, 0.003798, 0.000944, 0.000154, 4.6e-05, 2.2e-05, 2.0e-06'
   end