Ensure we calculate net capacity even when blower fan heat is provided. Update tests/docs.

Author: shorowit

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>5081c516-4862-41dd-9c9b-a53be19985ea</version_id>
-  <version_modified>2024-06-17T19:50:27Z</version_modified>
+  <version_id>e3cf35e9-a352-4b87-9862-1b4c43330a84</version_id>
+  <version_modified>2024-06-17T22:16:28Z</version_modified>
   <xml_checksum>D8922A73</xml_checksum>
   <class_name>HPXMLtoOpenStudio</class_name>
   <display_name>HPXML to OpenStudio Translator</display_name>
@@ -387,7 +387,7 @@
       <filename>hvac_sizing.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>8A45B2BB</checksum>
+      <checksum>C4D7EF6D</checksum>
     </file>
     <file>
       <filename>lighting.rb</filename>
@@ -669,7 +669,7 @@
       <filename>test_hvac_sizing.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>75B3319A</checksum>
+      <checksum>36E97140</checksum>
     </file>
     <file>
       <filename>test_lighting.rb</filename>

HPXMLtoOpenStudio/resources/hvac_sizing.rb

@@ -79,9 +79,9 @@ def self.calculate(runner, weather, hpxml_bldg, hvac_systems, update_hpxml: true
       apply_hvac_equipment_adjustments(mj, runner, hvac_sizings, weather, hvac_heating, hvac_cooling, hvac_system, hpxml_bldg)
       apply_hvac_installation_quality(mj, hvac_sizings, hvac_heating, hvac_cooling, frac_zone_heat_load_served, frac_zone_cool_load_served, hpxml_bldg)
       apply_hvac_autosizing_factors_and_limits(hvac_sizings, hvac_heating, hvac_cooling)
-      apply_hvac_fixed_capacities(hvac_sizings, hvac_heating, hvac_cooling, hpxml_bldg)
+      apply_hvac_final_capacities(hvac_sizings, hvac_heating, hvac_cooling, hpxml_bldg)
+      apply_hvac_final_airflows(hvac_sizings, hvac_heating, hvac_cooling)
       apply_hvac_ground_loop(mj, runner, hvac_sizings, weather, hvac_cooling)
-      apply_hvac_finalize_airflows(hvac_sizings, hvac_heating, hvac_cooling)
       @all_hvac_sizings[hvac_system] = hvac_sizings
 
       if update_hpxml
@@ -1605,9 +1605,11 @@ def self.get_hvac_size_limits(hvac_cooling)
   # @param hvac_loads [TODO] TODO
   # @return [TODO] TODO
   def self.apply_hvac_loads_to_hvac_sizings(hvac_sizings, hvac_loads)
-    hvac_sizings.Cool_Load_Sens = hvac_loads.Cool_Sens
+    # Note: We subtract the blower heat below because we want to calculate a net capacity,
+    # not a gross capacity.
+    hvac_sizings.Cool_Load_Sens = hvac_loads.Cool_Sens - hvac_loads.Cool_BlowerHeat
     hvac_sizings.Cool_Load_Lat = hvac_loads.Cool_Lat
-    hvac_sizings.Cool_Load_Tot = hvac_loads.Cool_Tot
+    hvac_sizings.Cool_Load_Tot = hvac_loads.Cool_Tot - hvac_loads.Cool_BlowerHeat
     hvac_sizings.Heat_Load = hvac_loads.Heat_Tot
     hvac_sizings.Heat_Load_Supp = hvac_loads.Heat_Tot
   end
@@ -2606,15 +2608,15 @@ def self.apply_hvac_autosizing_factors_and_limits(hvac_sizings, hvac_heating, hv
     end
   end
 
-  # Fixed Sizing Equipment
+  # Finalize Capacity Calculations
   #
   # @param hvac_sizings [TODO] TODO
   # @param hvac_heating [TODO] TODO
   # @param hvac_cooling [TODO] TODO
   # @param hpxml_bldg [HPXML::Building] HPXML Building object representing an individual dwelling unit
   # @return [TODO] TODO
-  def self.apply_hvac_fixed_capacities(hvac_sizings, hvac_heating, hvac_cooling, hpxml_bldg)
-    # Override HVAC capacities if values are provided
+  def self.apply_hvac_final_capacities(hvac_sizings, hvac_heating, hvac_cooling, hpxml_bldg)
+    # Cooling
     if not hvac_cooling.nil?
       fixed_cooling_capacity = hvac_cooling.cooling_capacity
     end
@@ -2627,6 +2629,8 @@ def self.apply_hvac_fixed_capacities(hvac_sizings, hvac_heating, hvac_cooling, h
         hvac_sizings.Cool_Capacity_Sens *= fixed_cooling_capacity / autosized_cooling_capacity
       end
     end
+
+    # Heating
     if not hvac_heating.nil?
       fixed_heating_capacity = hvac_heating.heating_capacity
     elsif (not hvac_cooling.nil?) && hvac_cooling.has_integrated_heating
@@ -2640,6 +2644,8 @@ def self.apply_hvac_fixed_capacities(hvac_sizings, hvac_heating, hvac_cooling, h
         hvac_sizings.Heat_Airflow *= fixed_heating_capacity / autosized_heating_capacity
       end
     end
+
+    # Heat pump backup heating
     if hvac_heating.is_a? HPXML::HeatPump
       if not hvac_heating.backup_heating_capacity.nil?
         fixed_supp_heating_capacity = hvac_heating.backup_heating_capacity
@@ -2808,13 +2814,13 @@ def self.get_valid_num_bores(g_functions_json)
     return valid_num_bores
   end
 
-  # Finalize Sizing Calculations
+  # Finalize Airflow Calculations
   #
   # @param hvac_sizings [TODO] TODO
   # @param hvac_heating [TODO] TODO
   # @param hvac_cooling [TODO] TODO
   # @return [TODO] TODO
-  def self.apply_hvac_finalize_airflows(hvac_sizings, hvac_heating, hvac_cooling)
+  def self.apply_hvac_final_airflows(hvac_sizings, hvac_heating, hvac_cooling)
     if (not hvac_heating.nil?) && hvac_heating.respond_to?(:airflow_defect_ratio)
       if hvac_sizings.Heat_Airflow > 0
         hvac_sizings.Heat_Airflow *= (1.0 + hvac_heating.airflow_defect_ratio.to_f)

HPXMLtoOpenStudio/tests/test_hvac_sizing.rb

@@ -1177,11 +1177,20 @@ def test_manual_j_detailed_sizing_inputs
 
     # Test blower fan heat input
     args_hash['hpxml_path'] = File.absolute_path(@tmp_hpxml_path)
-    hpxml, hpxml_bldg = _create_hpxml('base.xml')
+    hpxml, hpxml_bldg = _create_hpxml('base-hvac-autosize.xml')
     hpxml_bldg.hvac_distributions[0].manualj_blower_fan_heat_btuh = 1234.0
     XMLHelper.write_file(hpxml.to_doc, @tmp_hpxml_path)
     _model, _test_hpxml, test_hpxml_bldg = _test_measure(args_hash)
     assert_equal(1234.0, test_hpxml_bldg.hvac_plant.cdl_sens_blowerheat)
+    orig_cooling_capacity = test_hpxml_bldg.cooling_systems[0].cooling_capacity
+
+    # Test blower fan heat input 2
+    # Check the autosized equipment capacity (net) doesn't change
+    hpxml_bldg.hvac_distributions[0].manualj_blower_fan_heat_btuh = 0.0
+    XMLHelper.write_file(hpxml.to_doc, @tmp_hpxml_path)
+    _model, _test_hpxml, test_hpxml_bldg = _test_measure(args_hash)
+    assert_equal(0.0, test_hpxml_bldg.hvac_plant.cdl_sens_blowerheat)
+    assert_equal(orig_cooling_capacity, test_hpxml_bldg.cooling_systems[0].cooling_capacity)
 
     # Test boiler hot water piping input
     args_hash['hpxml_path'] = File.absolute_path(@tmp_hpxml_path)

docs/source/workflow_inputs.rst

@@ -3097,7 +3097,7 @@ Each air distribution system is entered as a ``/HPXML/Building/BuildingDetails/S
   ``DistributionSystemType/AirDistribution/DuctLeakageMeasurement[DuctType="return"]``  element                        See [#]_             Return duct leakage value
   ``DistributionSystemType/AirDistribution/Ducts``                                      element                        No                   Supply/return ducts; multiple are allowed [#]_
   ``DistributionSystemType/AirDistribution/NumberofReturnRegisters``                    integer           >= 0         No        See [#]_   Number of return registers
-  ``DistributionSystemType/AirDistribution/extension/ManualJInputs/BlowerFanHeatBtuh``  double   Btu/hr   >= 0         No        0          Blower fan heat for ACCA Manual J design loads
+  ``DistributionSystemType/AirDistribution/extension/ManualJInputs/BlowerFanHeatBtuh``  double   Btu/hr   >= 0         No        0          Blower fan heat for ACCA Manual J design loads [#]_
   ``ConditionedFloorAreaServed``                                                        double   ft2      > 0          See [#]_             Conditioned floor area served
   ====================================================================================  =======  =======  ===========  ========  =========  ==========================
 
@@ -3106,6 +3106,8 @@ Each air distribution system is entered as a ``/HPXML/Building/BuildingDetails/S
   .. [#] Return duct leakage required if AirDistributionType is "regular velocity" or "gravity" and optional if AirDistributionType is "fan coil".
   .. [#] Provide a Ducts element for each supply duct and each return duct.
   .. [#] If NumberofReturnRegisters not provided and return ducts are present, defaults to one return register per conditioned floor per `ASHRAE Standard 152 <https://www.energy.gov/eere/buildings/downloads/ashrae-standard-152-spreadsheet>`_, rounded up to the nearest integer if needed.
+  .. [#] BlowerFanHeatBtuh should only be provided when calculating design loads for HVAC equipment whose performance data has not been adjusted for blower heat.
+         When provided, it can be calculated according to Manual J Section 25 or the default of 1707 Btu/hr (500 W) can be used.
   .. [#] ConditionedFloorAreaServed required only when duct surface area is defaulted (i.e., ``AirDistribution/Ducts`` are present without ``DuctSurfaceArea`` child elements).
 
 Additional information is entered in each ``DuctLeakageMeasurement``.
@@ -3186,10 +3188,12 @@ Each hydronic distribution system is entered as a ``/HPXML/Building/BuildingDeta
   ``SystemIdentifier``                                                                        id                             Yes                  Unique identifier
   ``DistributionSystemType/HydronicDistribution``                                             element                        Yes                  Type of distribution system
   ``DistributionSystemType/HydronicDistribution/HydronicDistributionType``                    string            See [#]_     Yes                  Type of hydronic distribution system
-  ``DistributionSystemType/HydronicDistribution/extension/ManualJInputs/HotWaterPipingBtuh``  double   Btu/hr   >= 0         No        0          Piping load for ACCA Manual J design loads
+  ``DistributionSystemType/HydronicDistribution/extension/ManualJInputs/HotWaterPipingBtuh``  double   Btu/hr   >= 0         No        0          Piping load for ACCA Manual J design loads [#]_
   ==========================================================================================  =======  =======  ===========  ========  =========  ====================================
 
   .. [#] HydronicDistributionType choices are "radiator", "baseboard", "radiant floor", "radiant ceiling", or "water loop".
+  .. [#] HotWaterPipingBtuh should only be provided when hydronic distribution pipes run through unconditioned spaces.
+         When provided, it can be calculated according to Manual J Section 26.
 
 .. _hvac_distribution_dse: