Allow Modeling Two Speed & Var Speed Geothermal Heat Pumps

BuildResidentialHPXML/README.md

@@ -193,6 +193,19 @@ Research feature to select the type of defrost model. Use standard for default E
 
 <br/>
 
+**Simulation Control: Geothermal Model Type**
+
+Research feature to select the type of geothermal model. Use simple for simple E+ geothermal coil modeling. Use advanced for an improved model that better accounts for coil staging; using advanced may impact simulation runtime. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.10.0/workflow_inputs.html#hpxml-simulation-control'>HPXML Simulation Control</a>) is used.
+
+- **Name:** ``simulation_control_geothermal_model_type``
+- **Type:** ``Choice``
+
+- **Required:** ``false``
+
+- **Choices:** `simple`, `advanced`
+
+<br/>
+
 **Simulation Control: HVAC On-Off Thermostat Deadband**
 
 Research feature to model on-off thermostat deadband and start-up degradation for single or two speed AC/ASHP systems, and realistic time-based staging for two speed AC/ASHP systems. Currently only supported with 1 min timestep.
@@ -2048,7 +2061,7 @@ The rated efficiency value of the cooling system. Ignored for evaporative cooler
 
 **Cooling System: Cooling Compressor Type**
 
-The compressor type of the cooling system. Only applies to central air conditioner and mini-split. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.10.0/workflow_inputs.html#central-air-conditioner'>Central Air Conditioner</a>, <a href='https://openstudio-hpxml.readthedocs.io/en/v1.10.0/workflow_inputs.html#mini-split-air-conditioner'>Mini-Split Air Conditioner</a>) is used.
+The compressor type of the cooling system. Only applies to central air conditioner and mini-split.
 
 - **Name:** ``cooling_system_cooling_compressor_type``
 - **Type:** ``Choice``
@@ -2287,7 +2300,7 @@ The rated cooling efficiency value of the heat pump.
 
 **Heat Pump: Cooling Compressor Type**
 
-The compressor type of the heat pump. Only applies to air-to-air and mini-split. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.10.0/workflow_inputs.html#air-to-air-heat-pump'>Air-to-Air Heat Pump</a>, <a href='https://openstudio-hpxml.readthedocs.io/en/v1.10.0/workflow_inputs.html#mini-split-heat-pump'>Mini-Split Heat Pump</a>) is used.
+The compressor type of the heat pump. Only applies to air-to-air, mini-split and ground-to-air.
 
 - **Name:** ``heat_pump_cooling_compressor_type``
 - **Type:** ``Choice``

BuildResidentialHPXML/measure.rb

@@ -127,6 +127,14 @@ def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
     arg.setDescription("Research feature to select the type of defrost model. Use #{HPXML::AdvancedResearchDefrostModelTypeStandard} for default E+ defrost setting. Use #{HPXML::AdvancedResearchDefrostModelTypeAdvanced} for an improved model that better accounts for load and energy use during defrost; using #{HPXML::AdvancedResearchDefrostModelTypeAdvanced} may impact simulation runtime. If not provided, the OS-HPXML default (see <a href='#{docs_base_url}#hpxml-simulation-control'>HPXML Simulation Control</a>) is used.")
     args << arg
 
+    geothermal_model_type_choices = OpenStudio::StringVector.new
+    geothermal_model_type_choices << HPXML::AdvancedResearchGeothermalModelTypeSimple
+    geothermal_model_type_choices << HPXML::AdvancedResearchGeothermalModelTypeAdvanced
+    arg = OpenStudio::Measure::OSArgument::makeChoiceArgument('simulation_control_geothermal_model_type', geothermal_model_type_choices, false)
+    arg.setDisplayName('Simulation Control: Geothermal Model Type')
+    arg.setDescription("Research feature to select the type of geothermal model. Use #{HPXML::AdvancedResearchGeothermalModelTypeSimple} for simple E+ geothermal coil modeling. Use #{HPXML::AdvancedResearchGeothermalModelTypeAdvanced} for an improved model that better accounts for coil staging; using #{HPXML::AdvancedResearchGeothermalModelTypeAdvanced} may impact simulation runtime. If not provided, the OS-HPXML default (see <a href='#{docs_base_url}#hpxml-simulation-control'>HPXML Simulation Control</a>) is used.")
+    args << arg
+
     arg = OpenStudio::Measure::OSArgument::makeDoubleArgument('simulation_control_onoff_thermostat_deadband', false)
     arg.setDisplayName('Simulation Control: HVAC On-Off Thermostat Deadband')
     arg.setDescription('Research feature to model on-off thermostat deadband and start-up degradation for single or two speed AC/ASHP systems, and realistic time-based staging for two speed AC/ASHP systems. Currently only supported with 1 min timestep.')
@@ -1278,7 +1286,7 @@ def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
 
     arg = OpenStudio::Measure::OSArgument::makeChoiceArgument('cooling_system_cooling_compressor_type', compressor_type_choices, false)
     arg.setDisplayName('Cooling System: Cooling Compressor Type')
-    arg.setDescription("The compressor type of the cooling system. Only applies to #{HPXML::HVACTypeCentralAirConditioner} and #{HPXML::HVACTypeMiniSplitAirConditioner}. If not provided, the OS-HPXML default (see <a href='#{docs_base_url}#central-air-conditioner'>Central Air Conditioner</a>, <a href='#{docs_base_url}#mini-split-air-conditioner'>Mini-Split Air Conditioner</a>) is used.")
+    arg.setDescription("The compressor type of the cooling system. Only applies to #{HPXML::HVACTypeCentralAirConditioner} and #{HPXML::HVACTypeMiniSplitAirConditioner}.")
     args << arg
 
     arg = OpenStudio::Measure::OSArgument::makeDoubleArgument('cooling_system_cooling_sensible_heat_fraction', false)
@@ -1423,7 +1431,7 @@ def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
 
     arg = OpenStudio::Measure::OSArgument::makeChoiceArgument('heat_pump_cooling_compressor_type', compressor_type_choices, false)
     arg.setDisplayName('Heat Pump: Cooling Compressor Type')
-    arg.setDescription("The compressor type of the heat pump. Only applies to #{HPXML::HVACTypeHeatPumpAirToAir} and #{HPXML::HVACTypeHeatPumpMiniSplit}. If not provided, the OS-HPXML default (see <a href='#{docs_base_url}#air-to-air-heat-pump'>Air-to-Air Heat Pump</a>, <a href='#{docs_base_url}#mini-split-heat-pump'>Mini-Split Heat Pump</a>) is used.")
+    arg.setDescription("The compressor type of the heat pump. Only applies to #{HPXML::HVACTypeHeatPumpAirToAir}, #{HPXML::HVACTypeHeatPumpMiniSplit} and #{HPXML::HVACTypeHeatPumpGroundToAir}.")
     args << arg
 
     arg = OpenStudio::Measure::OSArgument::makeDoubleArgument('heat_pump_cooling_sensible_heat_fraction', false)
@@ -4306,6 +4314,13 @@ def self.set_header(runner, hpxml, args)
       hpxml.header.defrost_model_type = args[:simulation_control_defrost_model_type]
     end
 
+    if not args[:simulation_control_geothermal_model_type].nil?
+      if (not hpxml.header.geothermal_model_type.nil?) && (hpxml.header.geothermal_model_type != args[:simulation_control_geothermal_model_type])
+        errors << "'Simulation Control: Geothermal Model Type' cannot vary across dwelling units."
+      end
+      hpxml.header.geothermal_model_type = args[:simulation_control_geothermal_model_type]
+    end
+
     if not args[:simulation_control_onoff_thermostat_deadband].nil?
       if (not hpxml.header.hvac_onoff_thermostat_deadband.nil?) && (hpxml.header.hvac_onoff_thermostat_deadband != args[:simulation_control_onoff_thermostat_deadband])
         errors << "'Simulation Control: HVAC On-Off Thermostat Deadband' cannot vary across dwelling units."
@@ -5838,7 +5853,7 @@ def self.set_heat_pumps(hpxml_bldg, args)
       end
     end
 
-    if [HPXML::HVACTypeHeatPumpAirToAir, HPXML::HVACTypeHeatPumpMiniSplit].include? heat_pump_type
+    if [HPXML::HVACTypeHeatPumpAirToAir, HPXML::HVACTypeHeatPumpMiniSplit, HPXML::HVACTypeHeatPumpGroundToAir].include? heat_pump_type
       compressor_type = args[:heat_pump_cooling_compressor_type]
     end
 

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>a7c704f4-4cc1-4365-8496-fc3fb3c37566</version_id>
-  <version_modified>2025-03-28T22:12:04Z</version_modified>
+  <version_id>73e45dca-72a8-4377-ad9e-df7023eb81a7</version_id>
+  <version_modified>2025-03-31T18:58:36Z</version_modified>
   <xml_checksum>2C38F48B</xml_checksum>
   <class_name>BuildResidentialHPXML</class_name>
   <display_name>HPXML Builder</display_name>
@@ -171,6 +171,24 @@
         </choice>
       </choices>
     </argument>
+    <argument>
+      <name>simulation_control_geothermal_model_type</name>
+      <display_name>Simulation Control: Geothermal Model Type</display_name>
+      <description>Research feature to select the type of geothermal model. Use simple for simple E+ geothermal coil modeling. Use advanced for an improved model that better accounts for coil staging; using advanced may impact simulation runtime. If not provided, the OS-HPXML default (see &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.10.0/workflow_inputs.html#hpxml-simulation-control'&gt;HPXML Simulation Control&lt;/a&gt;) is used.</description>
+      <type>Choice</type>
+      <required>false</required>
+      <model_dependent>false</model_dependent>
+      <choices>
+        <choice>
+          <value>simple</value>
+          <display_name>simple</display_name>
+        </choice>
+        <choice>
+          <value>advanced</value>
+          <display_name>advanced</display_name>
+        </choice>
+      </choices>
+    </argument>
     <argument>
       <name>simulation_control_onoff_thermostat_deadband</name>
       <display_name>Simulation Control: HVAC On-Off Thermostat Deadband</display_name>
@@ -2633,7 +2651,7 @@
     <argument>
       <name>cooling_system_cooling_compressor_type</name>
       <display_name>Cooling System: Cooling Compressor Type</display_name>
-      <description>The compressor type of the cooling system. Only applies to central air conditioner and mini-split. If not provided, the OS-HPXML default (see &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.10.0/workflow_inputs.html#central-air-conditioner'&gt;Central Air Conditioner&lt;/a&gt;, &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.10.0/workflow_inputs.html#mini-split-air-conditioner'&gt;Mini-Split Air Conditioner&lt;/a&gt;) is used.</description>
+      <description>The compressor type of the cooling system. Only applies to central air conditioner and mini-split.</description>
       <type>Choice</type>
       <required>false</required>
       <model_dependent>false</model_dependent>
@@ -2914,7 +2932,7 @@
     <argument>
       <name>heat_pump_cooling_compressor_type</name>
       <display_name>Heat Pump: Cooling Compressor Type</display_name>
-      <description>The compressor type of the heat pump. Only applies to air-to-air and mini-split. If not provided, the OS-HPXML default (see &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.10.0/workflow_inputs.html#air-to-air-heat-pump'&gt;Air-to-Air Heat Pump&lt;/a&gt;, &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.10.0/workflow_inputs.html#mini-split-heat-pump'&gt;Mini-Split Heat Pump&lt;/a&gt;) is used.</description>
+      <description>The compressor type of the heat pump. Only applies to air-to-air, mini-split and ground-to-air.</description>
       <type>Choice</type>
       <required>false</required>
       <model_dependent>false</model_dependent>
@@ -7664,7 +7682,7 @@
       <filename>README.md</filename>
       <filetype>md</filetype>
       <usage_type>readme</usage_type>
-      <checksum>F4222EA2</checksum>
+      <checksum>402FE34E</checksum>
     </file>
     <file>
       <filename>README.md.erb</filename>
@@ -7681,7 +7699,7 @@
       <filename>measure.rb</filename>
       <filetype>rb</filetype>
       <usage_type>script</usage_type>
-      <checksum>9D0AE8A8</checksum>
+      <checksum>942CB7D2</checksum>
     </file>
     <file>
       <filename>constants.rb</filename>

Changelog.md

@@ -3,6 +3,8 @@
 __New Features__
 - HVAC modeling updates:
   - **Breaking Change**: `CompressorType` required for central and mini-split air conditioners and heat pumps.
+  - Allows modeling two-speed and variable-speed geothermal heat pumps with `CompressorType` to be "two stage" or "variable speed".
+  - Optional input `h:SimulationControl/AdvancedResearchFeatures/GeothermalModelType` to choose the "simple" or "advanced" geothermal heat pump models, "advanced" geothermal model uses E+ variable speed coils.
 - Electric vehicle enhancements:
   - Allows detailed modeling of electric vehicles (batteries and charging/discharging) using `Vehicles` as an alternative to the simple EV charging `PlugLoad`.
   - Adds EV driving unmet hours output.
@@ -183,7 +185,7 @@ __New Features__
   - Adds new optional arguments for registering (with the OpenStudio runner) annual or monthly utility bills.
 - Advanced research features:
   - **Breaking change**: Replaces `SimulationControl/TemperatureCapacitanceMultiplier` with `SimulationControl/AdvancedResearchFeatures/TemperatureCapacitanceMultiplier`.
-  - Allows an optional boolean input `SimulationControl/AdvancedResearchFeatures/DefrostModelType` for heat pump advanced defrost model.
+  - Allows an optional input `SimulationControl/AdvancedResearchFeatures/DefrostModelType` for heat pump advanced defrost model.
   - Adds maximum power ratio detailed schedule for variable-speed HVAC systems to model shedding controls per [AHRI 1380](https://www.ahrinet.org/search-standards/ahri-1380-i-p-demand-response-through-variable-capacity-hvac-systems-residential-and-small).
 
 __Bugfixes__

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>3fee514e-82e1-4c56-a9b8-165b08a34988</version_id>
-  <version_modified>2025-04-11T17:17:29Z</version_modified>
+  <version_id>3e0544f9-14dc-4d80-90e9-38540c8da440</version_id>
+  <version_modified>2025-04-17T21:22:14Z</version_modified>
   <xml_checksum>D8922A73</xml_checksum>
   <class_name>HPXMLtoOpenStudio</class_name>
   <display_name>HPXML to OpenStudio Translator</display_name>
@@ -333,13 +333,13 @@
       <filename>defaults.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>63F848DF</checksum>
+      <checksum>E8DE7FF4</checksum>
     </file>
     <file>
       <filename>energyplus.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>071927F3</checksum>
+      <checksum>B85422F4</checksum>
     </file>
     <file>
       <filename>generator.rb</filename>
@@ -363,7 +363,7 @@
       <filename>hpxml.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>12014DE1</checksum>
+      <checksum>62B7E3B6</checksum>
     </file>
     <file>
       <filename>hpxml_schema/HPXML.xsd</filename>
@@ -381,7 +381,7 @@
       <filename>hpxml_schematron/EPvalidator.xml</filename>
       <filetype>xml</filetype>
       <usage_type>resource</usage_type>
-      <checksum>3749B48F</checksum>
+      <checksum>72AADB6A</checksum>
     </file>
     <file>
       <filename>hpxml_schematron/iso-schematron.xsd</filename>
@@ -393,13 +393,25 @@
       <filename>hvac.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>FB9ACEF1</checksum>
+      <checksum>1FCCD669</checksum>
+    </file>
+    <file>
+      <filename>hvac.rb.bak</filename>
+      <filetype>bak</filetype>
+      <usage_type>resource</usage_type>
+      <checksum>E97906D0</checksum>
     </file>
     <file>
       <filename>hvac_sizing.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>A079BB8E</checksum>
+      <checksum>AED29027</checksum>
+    </file>
+    <file>
+      <filename>hvac_sizing.rb.bak</filename>
+      <filetype>bak</filetype>
+      <usage_type>resource</usage_type>
+      <checksum>5C5B18CE</checksum>
     </file>
     <file>
       <filename>internal_gains.rb</filename>
@@ -453,7 +465,7 @@
       <filename>model.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>F0F4648E</checksum>
+      <checksum>A57C8FAE</checksum>
     </file>
     <file>
       <filename>output.rb</filename>
@@ -735,13 +747,13 @@
       <filename>test_hvac.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>E30F0328</checksum>
+      <checksum>C57D23EB</checksum>
     </file>
     <file>
       <filename>test_hvac_sizing.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>DF5913B9</checksum>
+      <checksum>9FFCC607</checksum>
     </file>
     <file>
       <filename>test_lighting.rb</filename>
@@ -783,7 +795,7 @@
       <filename>test_validation.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>F55AEAC1</checksum>
+      <checksum>0C825287</checksum>
     </file>
     <file>
       <filename>test_vehicle.rb</filename>
@@ -795,7 +807,7 @@
       <filename>test_water_heater.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>60CD4A1F</checksum>
+      <checksum>906475AB</checksum>
     </file>
     <file>
       <filename>test_weather.rb</filename>