Merge pull request #2231 from NatLabRockies/hpwh_input_capacity

Change HPWH `HeatingCapacity` to be input capacity

Author: shorowit

Changelog.md

@@ -2,6 +2,7 @@
 
 __Features__
   - **Breaking change**: Conditioned crawlspaces are no longer allowed; use unvented crawlspace instead.
+  - **Breaking change**: For heat pump water heaters, ``HeatingCapacity`` is now *input* rather than *output* capacity, similar to other water heater types.
 
 __Bugfixes__
 - Fixes ERV supply outlet enthalpy calculation used to calculate latent effectiveness.

HPXMLtoOpenStudio/measure.xml

@@ -3,8 +3,8 @@
   <schema_version>3.1</schema_version>
   <name>hpxml_to_openstudio</name>
   <uid>b1543b30-9465-45ff-ba04-1d1f85e763bc</uid>
-  <version_id>f15d2212-6489-4380-9bfa-1065ab495ec6</version_id>
-  <version_modified>2026-06-30T14:06:12Z</version_modified>
+  <version_id>a38a2ae6-8e28-4610-b290-d0800e48bffb</version_id>
+  <version_modified>2026-07-06T17:36:47Z</version_modified>
   <xml_checksum>D8922A73</xml_checksum>
   <class_name>HPXMLToOpenStudio</class_name>
   <display_name>HPXML to OpenStudio Translator</display_name>
@@ -367,7 +367,7 @@
       <filename>defaults.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>413A9F47</checksum>
+      <checksum>4350A1B4</checksum>
     </file>
     <file>
       <filename>electric_panel.rb</filename>
@@ -433,7 +433,7 @@
       <filename>hvac.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>DF5A0B42</checksum>
+      <checksum>FC78CABE</checksum>
     </file>
     <file>
       <filename>hvac_sizing.rb</filename>
@@ -715,7 +715,7 @@
       <filename>waterheater.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>C428F4AB</checksum>
+      <checksum>38BFC5B0</checksum>
     </file>
     <file>
       <filename>weather.rb</filename>
@@ -751,13 +751,13 @@
       <filename>test_defaults.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>BE1661EA</checksum>
+      <checksum>2C65B351</checksum>
     </file>
     <file>
       <filename>test_electric_panel.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>91EBCCF9</checksum>
+      <checksum>C44399FB</checksum>
     </file>
     <file>
       <filename>test_enclosure.rb</filename>
@@ -841,7 +841,7 @@
       <filename>test_water_heater.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>F216022C</checksum>
+      <checksum>F2FE0274</checksum>
     </file>
     <file>
       <filename>test_weather.rb</filename>

HPXMLtoOpenStudio/resources/defaults.rb

@@ -3354,7 +3354,7 @@ def self.apply_water_heaters(hpxml_bldg, eri_version, schedules_file)
         water_heating_system.additional_properties.cop = get_water_heater_heat_pump_cop(water_heating_system)
 
         if water_heating_system.heating_capacity.nil?
-          water_heating_system.heating_capacity = (UnitConversions.convert(0.5, 'kW', 'Btu/hr') * water_heating_system.additional_properties.cop).round
+          water_heating_system.heating_capacity = UnitConversions.convert(0.5, 'kW', 'Btu/hr').round
           water_heating_system.heating_capacity_isdefaulted = true
         end
 
@@ -6493,7 +6493,7 @@ def self.get_window_ufactor_shgc(window)
 
   # Gets the default compressor type for a HVAC system.
   #
-  # @param [HPXML::HeatingSystem or HPXML::CoolingSystem or HPXML::HeatPump]
+  # @param hvac_system [HPXML::CoolingSystem or HPXML::HeatPump] The HPXML HVAC system of interest
   # @return [String] Compressor type (HPXML::HVACCompressorTypeXXX)
   def self.get_hvac_compressor_type(hvac_system)
     if HVAC.is_room_dx_hvac_system(hvac_system)
@@ -6505,7 +6505,7 @@ def self.get_hvac_compressor_type(hvac_system)
 
   # Gets the default EER for a HVAC system.
   #
-  # @param [HPXML::CoolingSystem or HPXML::HeatPump]
+  # @param hvac_system [HPXML::CoolingSystem or HPXML::HeatPump] The HPXML HVAC system of interest
   # @return [Double] Cooling EER2 (Btu/Wh)
   def self.get_hvac_eer2(hvac_system)
     seer2 = hvac_system.cooling_efficiency_seer2
@@ -7102,7 +7102,7 @@ def self.get_service_feeder_power_default_values(runner, hpxml_bldg, service_fee
         if water_heating_system.water_heater_type == HPXML::WaterHeaterTypeStorage
           watts += UnitConversions.convert(water_heating_system.heating_capacity, 'btu/hr', 'w')
         elsif water_heating_system.water_heater_type == HPXML::WaterHeaterTypeHeatPump
-          watts += [UnitConversions.convert(Waterheater.get_heating_input_capacity(water_heating_system.heating_capacity, water_heating_system.additional_properties.cop), 'btu/hr', 'w'),
+          watts += [UnitConversions.convert(water_heating_system.heating_capacity, 'btu/hr', 'w'),
                     UnitConversions.convert(water_heating_system.backup_heating_capacity, 'btu/hr', 'w')].max
         elsif water_heating_system.water_heater_type == HPXML::WaterHeaterTypeTankless
           if hpxml_bldg.building_construction.number_of_bathrooms == 1

HPXMLtoOpenStudio/resources/hvac.rb

@@ -1058,21 +1058,21 @@ def self.get_dx_coil_power_watts_from_capacity(capacity, voltage)
     return power
   end
 
-  # Get the indoor unit (air handler) power (W).
+  # Get the indoor unit (air handler) power.
   #
-  # @param fan_watts_per_cfm [Double] Blower fan watts per cfm [W/cfm]
-  # @param airflow_cfm [Double] HVAC system airflow rate [cfm]
-  # @return [Double] Blower fan power [W]
+  # @param fan_watts_per_cfm [Double] Blower fan efficacy (W/cfm)
+  # @param airflow_cfm [Double] HVAC system airflow rate (cfm)
+  # @return [Double] Blower fan power (W)
   def self.get_blower_fan_power_watts(fan_watts_per_cfm, airflow_cfm)
     return 0.0 if fan_watts_per_cfm.nil? || airflow_cfm.nil?
 
     return fan_watts_per_cfm * airflow_cfm
   end
 
-  # Get the boiler or GHP pump power (W).
+  # Get the boiler or GHP pump power.
   #
   # @param hvac_system [HPXML::HeatingSystem or HPXML::HeatPump] The HPXML HVAC system of interest
-  # @return [Double] Pump power [W]
+  # @return [Double] Pump power (W)
   def self.get_pump_power_watts(hvac_system)
     if hvac_system.is_a?(HPXML::HeatingSystem) && (not hvac_system.electric_auxiliary_energy.nil?)
       return hvac_system.electric_auxiliary_energy / 2.08
@@ -1089,10 +1089,10 @@ def self.get_pump_power_watts(hvac_system)
 
   # Returns the heating input capacity, calculated as the heating rated (output) capacity divided by the rated efficiency.
   #
-  # @param heating_capacity [Double] Heating output capacity [Btu/hr]
-  # @param heating_efficiency_afue [Double] Rated efficiency [AFUE]
-  # @param heating_efficiency_percent [Double] Rated efficiency [Percent]
-  # @return [Double] The heating input capacity [Btu/hr]
+  # @param heating_capacity [Double] Heating output capacity (Btu/hr)
+  # @param heating_efficiency_afue [Double] Rated efficiency (AFUE)
+  # @param heating_efficiency_percent [Double] Rated efficiency (Percent)
+  # @return [Double] The heating input capacity (Btu/hr)
   def self.get_heating_input_capacity(heating_capacity, heating_efficiency_afue, heating_efficiency_percent)
     if not heating_efficiency_afue.nil?
       return heating_capacity / heating_efficiency_afue
@@ -2467,7 +2467,7 @@ def self.create_heat_pump_supplemental_heating_coil(model, obj_name, heat_pump,
   #
   # @param model [OpenStudio::Model::Model] OpenStudio Model object
   # @param obj_name [String] Name for the OpenStudio object
-  # @param fan_watts_per_cfm [Double] Fan efficacy watts per cfm
+  # @param fan_watts_per_cfm [Double] Blower fan efficacy (W/cfm)
   # @param fan_cfms [Array<Double>] Fan airflow rates at all speeds, both heating and cooling
   # @param hvac_system [HPXML::HeatingSystem or HPXML::CoolingSystem or HPXML::HeatPump] The HPXML HVAC system of interest
   # @return [OpenStudio::Model::FanSystemModel] OpenStudio FanSystemModel object

HPXMLtoOpenStudio/resources/waterheater.rb

@@ -973,7 +973,8 @@ def self.apply_hpwh_dxcoil(runner, model, water_heating_system, elevation, obj_n
     )
 
     # Assumptions and values
-    cap = UnitConversions.convert(water_heating_system.heating_capacity, 'Btu/hr', 'W') * unit_multiplier # kW
+    cop = water_heating_system.additional_properties.cop
+    cap = UnitConversions.convert(water_heating_system.heating_capacity, 'Btu/hr', 'W') * cop * unit_multiplier # W, output capacity
     shr = 0.88 # unitless
 
     # Calculate an altitude adjusted rated evaporator wetbulb temperature
@@ -987,8 +988,6 @@ def self.apply_hpwh_dxcoil(runner, model, water_heating_system, elevation, obj_n
     w_adj = Psychrometrics.w_fT_Twb_P(dp_rated, dp_rated, p_atm)
     twb_adj = Psychrometrics.Twb_fT_w_P(runner, rated_edb_F, w_adj, p_atm)
 
-    cop = water_heating_system.additional_properties.cop
-
     # Adjust COP based on RESNET HERS Addendum 77
     cv = water_heating_system.hpwh_containment_volume
     if not cv.nil?
@@ -1039,15 +1038,6 @@ def self.apply_hpwh_dxcoil(runner, model, water_heating_system, elevation, obj_n
     return coil
   end
 
-  # Returns the heating input capacity, calculated as the heating rated (output) capacity divided by the rated efficiency.
-  #
-  # @param heating_capacity [Double]
-  # @param heating_efficiency_cop [Double] Rated efficiency [COP]
-  # @return [Double] The heating input capacity [Btu/hr]
-  def self.get_heating_input_capacity(heating_capacity, heating_efficiency_cop)
-    return heating_capacity / UnitConversions.convert(heating_efficiency_cop, 'btu/hr', 'w')
-  end
-
   # Adds a WaterHeaterStratified object for the HPWH to the OpenStudio model.
   #
   # @param model [OpenStudio::Model::Model] OpenStudio Model object

HPXMLtoOpenStudio/tests/test_defaults.rb

@@ -3623,21 +3623,21 @@ def test_heat_pump_water_heaters
     hpxml_bldg.water_heating_systems[0].hpwh_confined_space_without_mitigation = nil
     XMLHelper.write_file(hpxml.to_doc, @tmp_hpxml_path)
     _default_hpxml, default_hpxml_bldg = _test_measure()
-    _test_default_heat_pump_water_heater_values(default_hpxml_bldg, [66.0, HPXML::WaterHeaterHPWHOperatingModeHybridAuto, 6366.0, 15355.0, false])
+    _test_default_heat_pump_water_heater_values(default_hpxml_bldg, [66.0, HPXML::WaterHeaterHPWHOperatingModeHybridAuto, 1706.0, 15355.0, false])
 
     # Test defaults w/ num occupants = 1, num bedrooms = 1
     hpxml_bldg.building_construction.number_of_bedrooms = 1
     hpxml_bldg.building_occupancy.number_of_residents = 1
     XMLHelper.write_file(hpxml.to_doc, @tmp_hpxml_path)
     _default_hpxml, default_hpxml_bldg = _test_measure()
-    _test_default_heat_pump_water_heater_values(default_hpxml_bldg, [50.0, HPXML::WaterHeaterHPWHOperatingModeHybridAuto, 6366.0, 15355.0, false])
+    _test_default_heat_pump_water_heater_values(default_hpxml_bldg, [50.0, HPXML::WaterHeaterHPWHOperatingModeHybridAuto, 1706.0, 15355.0, false])
 
     # Test defaults w/ num occupants = 10, num bedrooms = 1
     hpxml_bldg.building_construction.number_of_bedrooms = 1
     hpxml_bldg.building_occupancy.number_of_residents = 10
     XMLHelper.write_file(hpxml.to_doc, @tmp_hpxml_path)
     _default_hpxml, default_hpxml_bldg = _test_measure()
-    _test_default_heat_pump_water_heater_values(default_hpxml_bldg, [80.0, HPXML::WaterHeaterHPWHOperatingModeHybridAuto, 6366.0, 15355.0, false])
+    _test_default_heat_pump_water_heater_values(default_hpxml_bldg, [80.0, HPXML::WaterHeaterHPWHOperatingModeHybridAuto, 1706.0, 15355.0, false])
   end
 
   def test_indirect_water_heaters

HPXMLtoOpenStudio/tests/test_electric_panel.rb

@@ -632,7 +632,7 @@ def test_water_heater_hpwh_without_backup
     XMLHelper.write_file(hpxml.to_doc, @tmp_hpxml_path)
     _model, _hpxml, hpxml_bldg = _test_measure(args_hash)
 
-    _test_service_feeder_power(hpxml_bldg, HPXML::ElectricPanelLoadTypeWaterHeater, 804)
+    _test_service_feeder_power(hpxml_bldg, HPXML::ElectricPanelLoadTypeWaterHeater, 879)
     _test_occupied_spaces(hpxml_bldg, [HPXML::ElectricPanelLoadTypeWaterHeater], 2)
   end
 

HPXMLtoOpenStudio/tests/test_water_heater.rb

@@ -1034,7 +1034,7 @@ def test_tank_heat_pump_capacities
     ther_eff = 1.0
     cop = 3.731
     tank_height = 1.3343
-    cap = UnitConversions.convert(water_heating_system.heating_capacity, 'Btu/hr', 'W') # W
+    cap = UnitConversions.convert(water_heating_system.heating_capacity, 'Btu/hr', 'W') * cop # W
     backup_cap = UnitConversions.convert(water_heating_system.backup_heating_capacity, 'Btu/hr', 'W') # W
 
     # Check water heater

docs/source/workflow_inputs.rst

@@ -4138,7 +4138,7 @@ Each conventional storage water heater is entered as a ``/HPXML/Building/Buildin
   ``IsSharedSystem``                             boolean                                                 No        false     Whether it serves multiple dwelling units or shared laundry room
   ``TankVolume``                                 double             gal            > 0                   No        See [#]_  Nominal tank volume
   ``FractionDHWLoadServed``                      double             frac           >= 0, <= 1 [#]_       Yes                 Fraction of hot water load served [#]_
-  ``HeatingCapacity``                            double             Btu/hr         > 0                   No        See [#]_  Heating capacity
+  ``HeatingCapacity``                            double             Btu/hr         > 0                   No        See [#]_  Heating input capacity
   ``UniformEnergyFactor`` or ``EnergyFactor``    double             frac           < 1                   Yes                 EnergyGuide label rated efficiency
   ``UsageBin`` or ``FirstHourRating``            string or double   str or gal/hr  See [#]_ or > 0       No        See [#]_  EnergyGuide label usage bin/first hour rating
   ``RecoveryEfficiency``                         double             frac           > 0, <= 1 [#]_        No        See [#]_  Recovery efficiency
@@ -4239,7 +4239,7 @@ Each heat pump water heater is entered as a ``/HPXML/Building/BuildingDetails/Sy
   ``IsSharedSystem``                                   boolean                                                  No        false           Whether it serves multiple dwelling units or shared laundry room
   ``TankVolume``                                       double            gal            > 0                     No        See [#]_        Nominal tank volume
   ``FractionDHWLoadServed``                            double            frac           >= 0, <= 1 [#]_         Yes                       Fraction of hot water load served [#]_
-  ``HeatingCapacity``                                  double            Btu/hr         > 0                     No        See [#]_        Heating output capacity
+  ``HeatingCapacity``                                  double            Btu/hr         > 0                     No        See [#]_        Heating input capacity
   ``BackupHeatingCapacity``                            double            Btu/hr         >= 0                    No        15355 (4.5 kW)  Heating capacity of the electric resistance backup
   ``UniformEnergyFactor`` or ``EnergyFactor``          double            frac           > 1, <= 5               Yes                       EnergyGuide label rated efficiency
   ``HPWHDucting/ExhaustAirTermination``                string                           See [#]_                No        <none>          The location where HPWH exhaust air is ducted to
@@ -4270,7 +4270,7 @@ Each heat pump water heater is entered as a ``/HPXML/Building/BuildingDetails/Sy
   .. [#] The sum of all ``FractionDHWLoadServed`` (across all WaterHeatingSystems) must equal to 1.
   .. [#] FractionDHWLoadServed represents only the fraction of the hot water load associated with the hot water **fixtures**.
          Additional hot water load from clothes washers/dishwashers will be automatically assigned to the appropriate water heater(s).
-  .. [#] If HeatingCapacity not provided, defaults to 1706 Btu/hr (0.5 kW) multiplied by the heat pump COP.
+  .. [#] If HeatingCapacity not provided, defaults to 1706 Btu/hr (0.5 kW).
   .. [#] OpenStudio-HPXML currently only supports ExhaustAirTermination="outside" for heat pump water heaters located in conditioned space.
          Any other combination of ExhaustAirTermination value and water heater location will be ignored w/ a warning.
   .. [#] HPWHOperatingMode choices are "hybrid/auto" or "heat pump only".