NREL · joseph-robertson · Jun 4, 2025 · Jun 5, 2025 · Jun 5, 2025 · Jun 5, 2025
diff --git a/docs/technical_development_guide/source/advanced_tutorial/heat_pump_upgrades.rst b/docs/technical_development_guide/source/advanced_tutorial/heat_pump_upgrades.rst
@@ -96,10 +96,9 @@ For example:
 Retain the Existing Primary Heating System as Backup
 ****************************************************
 
-Use the ``Heat Pump Backup|Use Existing System`` option from the lookup to retain the existing primary heating system as backup.
-
+Set ``heat_pump_backup_use_existing_system=true`` for ``HVAC Heating Efficiency`` options in the lookup to retain the primary (existing) heating system as backup to the heat pump.
 In this case, all properties of the existing primary system are retained as properties of the heat pump backup heating system.
-The following properties are retained:
+The following properties of the existing heating system are retained:
 
 - fuel type
 - efficiency

diff --git a/docs/technical_development_guide/source/workflow_inputs/characteristics.rst b/docs/technical_development_guide/source/workflow_inputs/characteristics.rst
@@ -36997,6 +36997,12 @@ Arguments
      - Type
      - Choices
      - Description
+   * - ``geometry_unit_cfa``
+     - true
+     - ft^2
+     - Double
+     - auto
+     - The total floor area of the unit's conditioned space (including any conditioned basement floor area). E.g., '2000' or 'auto'.
    * - ``geometry_garage_protrusion``
      - true
      - Frac
@@ -37009,12 +37015,6 @@ Arguments
      - String
      -
      - E.g., '2000-2499'.
-   * - ``geometry_unit_cfa``
-     - true
-     - sqft
-     - Double
-     -
-     - E.g., '2000' or 'auto'.
 
 Options
 *******
@@ -37028,55 +37028,55 @@ From ``project_national`` the list of options, option stock sturation, and optio
 
    * - Option name
      - Stock saturation
+     - ``geometry_unit_cfa``
      - ``geometry_garage_protrusion``
      - ``geometry_unit_cfa_bin``
-     - ``geometry_unit_cfa``
 
    * - 0-499
      - 3.2%
+     - auto
      - 0.72
      - 0-499
-     - auto
    * - 500-749
      - 8.5%
+     - auto
      - 0.75
      - 500-749
-     - auto
    * - 750-999
      - 15%
+     - auto
      - 0.5
      - 750-999
-     - auto
    * - 1000-1499
      - 26%
+     - auto
      - 0.5
      - 1000-1499
-     - auto
    * - 1500-1999
      - 19%
+     - auto
      - 0.5
      - 1500-1999
-     - auto
    * - 2000-2499
      - 12%
+     - auto
      - 0.5
      - 2000-2499
-     - auto
    * - 2500-2999
      - 6.5%
+     - auto
      - 0.5
      - 2500-2999
-     - auto
    * - 3000-3999
      - 6.1%
+     - auto
      - 0.5
      - 3000-3999
-     - auto
    * - 4000+
      - 3%
+     - auto
      - 0.5
      - 4000+
-     - auto
 
 .. _geometry_floor_area_bin:
 
@@ -39237,8 +39237,8 @@ Arguments
      - true
      - 
      - Choice
-     - none, integrated, separate
-     - The backup type of the heat pump. If 'integrated', represents e.g. built-in electric strip heat or dual-fuel integrated furnace. If 'separate', represents e.g. electric baseboard or boiler based on the Heating System 2 specified below. Use 'none' if there is no backup heating.
+     - auto, none, integrated, separate
+     - The backup type of the heat pump. If 'integrated', represents e.g. built-in electric strip heat or dual-fuel integrated furnace. If 'separate', represents e.g. electric baseboard or boiler based on the Heating System 2 specified below. Use 'none' if there is no backup heating. E.g., 'integrated' or 'auto'. Use 'auto' when Backup Use Existing System is true.
    * - ``heat_pump_backup_heating_autosizing_limit``
      - false
      - Btu/hr
@@ -39249,14 +39249,14 @@ Arguments
      - true
      - 
      - Choice
-     - electricity, natural gas, fuel oil, propane
-     - The backup fuel type of the heat pump. Only applies if Backup Type is 'integrated'.
+     - auto, electricity, natural gas, fuel oil, propane
+     - The backup fuel type of the heat pump. Only applies if Backup Type is 'integrated'. E.g., 'electricity' or 'auto'. Use 'auto' when Backup Use Existing System is true.
    * - ``heat_pump_backup_heating_efficiency``
      - true
      - 
      - Double
-     -
-     - The backup rated efficiency value of the heat pump. Percent for electricity fuel type. AFUE otherwise. Only applies if Backup Type is 'integrated'.
+     - auto
+     - The backup rated efficiency value of the heat pump. Percent for electricity fuel type. AFUE otherwise. Only applies if Backup Type is 'integrated'. E.g., '1' or 'auto'. Use 'auto' when Backup Use Existing System is true.
    * - ``heat_pump_backup_heating_capacity``
      - false
      - Btu/hr
@@ -39359,6 +39359,12 @@ Arguments
      - String
      -
      - Whether the heating system has a flue or chimney.
+   * - ``heat_pump_backup_use_existing_system``
+     - false
+     - 
+     - Boolean
+     - true, false
+     - Whether the heat pump uses the existing heating system as backup. If true and backup type of the heat pump is 'integrated', heat_pump_backup_xxx arguments are assigned values based on the existing heating system. If true and backup type of the heat pump is 'separate', heating_system_2_xxx arguments are assigned values based on the existing heating system. This argument is only applicable for heat pump upgrades.
    * - ``heat_pump_sizing_is_duct_limited``
      - false
      - 
@@ -39422,6 +39428,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - ``geothermal_loop_pipe_type``
      - ``geothermal_loop_pipe_diameter``
      - ``heating_system_has_flue_or_chimney``
+     - ``heat_pump_backup_use_existing_system``
      - ``heat_pump_sizing_is_duct_limited``
 
    * - ASHP, SEER 10, 6.2 HSPF
@@ -39471,6 +39478,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - ASHP, SEER 13, 7.7 HSPF
      - 7.4%
      - 
@@ -39518,6 +39526,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - ASHP, SEER 15, 8.5 HSPF
      - 7.2%
      - 
@@ -39565,6 +39574,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - Electric Baseboard, 100% Efficiency
      - 6.3%
      - 
@@ -39612,6 +39622,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - Electric Boiler, 100% AFUE
      - 0.21%
      - 
@@ -39659,6 +39670,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - Electric Furnace, 100% AFUE
      - 11%
      - 
@@ -39706,6 +39718,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - Electric Wall Furnace, 100% AFUE
      - 1.1%
      - 
@@ -39753,6 +39766,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - Fuel Boiler, 76% AFUE
      - 0.89%
      - 
@@ -39800,6 +39814,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - Fuel Boiler, 80% AFUE
      - 3.3%
      - 
@@ -39847,6 +39862,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - Fuel Boiler, 90% AFUE
      - 0.49%
      - 
@@ -39894,6 +39910,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - Fuel Furnace, 60% AFUE
      - 0.49%
      - 
@@ -39941,6 +39958,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - Fuel Furnace, 76% AFUE
      - 2.8%
      - 
@@ -39988,6 +40006,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - Fuel Furnace, 80% AFUE
      - 25%
      - 
@@ -40035,6 +40054,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - Fuel Furnace, 92.5% AFUE
      - 15%
      - 
@@ -40082,6 +40102,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - Fuel Wall/Floor Furnace, 60% AFUE
      - 3.2%
      - 
@@ -40129,6 +40150,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - Fuel Wall/Floor Furnace, 68% AFUE
      - 2.8%
      - 
@@ -40176,6 +40198,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - MSHP, SEER 14.5, 8.2 HSPF
      - 0.96%
      - 
@@ -40223,6 +40246,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - MSHP, SEER 29.3, 14 HSPF
      - 0.015%
      - 
@@ -40270,6 +40294,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - None
      - 1.1%
      - 
@@ -40317,6 +40342,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - auto
      - auto
      - false
+     - false
    * - Shared Heating
      - 9.6%
      - 
@@ -40364,6 +40390,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - 
      - 
      - 
+     - 
    * - Void
      - 0%
      - 
@@ -40411,6 +40438,7 @@ From ``project_national`` the list of options, option stock sturation, and optio
      - 
      - 
      - 
+     - 
 
 .. _hvac_heating_type:
 
@@ -41133,8 +41161,8 @@ Arguments
      - true
      - 
      - Choice
-     - none, integrated, separate
-     - The backup type of the heat pump. If 'integrated', represents e.g. built-in electric strip heat or dual-fuel integrated furnace. If 'separate', represents e.g. electric baseboard or boiler based on the Heating System 2 specified below. Use 'none' if there is no backup heating.
+     - auto, none, integrated, separate
+     - The backup type of the heat pump. If 'integrated', represents e.g. built-in electric strip heat or dual-fuel integrated furnace. If 'separate', represents e.g. electric baseboard or boiler based on the Heating System 2 specified below. Use 'none' if there is no backup heating. E.g., 'integrated' or 'auto'. Use 'auto' when Backup Use Existing System is true.
    * - ``heat_pump_backup_heating_autosizing_limit``
      - false
      - Btu/hr
@@ -41145,14 +41173,14 @@ Arguments
      - true
      - 
      - Choice
-     - electricity, natural gas, fuel oil, propane
-     - The backup fuel type of the heat pump. Only applies if Backup Type is 'integrated'.
+     - auto, electricity, natural gas, fuel oil, propane
+     - The backup fuel type of the heat pump. Only applies if Backup Type is 'integrated'. E.g., 'electricity' or 'auto'. Use 'auto' when Backup Use Existing System is true.
    * - ``heat_pump_backup_heating_efficiency``
      - true
      - 
      - Double
-     -
-     - The backup rated efficiency value of the heat pump. Percent for electricity fuel type. AFUE otherwise. Only applies if Backup Type is 'integrated'.
+     - auto
+     - The backup rated efficiency value of the heat pump. Percent for electricity fuel type. AFUE otherwise. Only applies if Backup Type is 'integrated'. E.g., '1' or 'auto'. Use 'auto' when Backup Use Existing System is true.
    * - ``heat_pump_backup_heating_capacity``
      - false
      - Btu/hr

diff --git a/docs/technical_development_guide/source/workflow_inputs/create_characteristics_rst.rb b/docs/technical_development_guide/source/workflow_inputs/create_characteristics_rst.rb
@@ -87,14 +87,24 @@ def get_measure_xml(filepath)
   end
 
   # Add "auto" to Choices for optional String/Double/Integer
-  if (properties['description'].include?('OS-HPXML default') && ['String', 'Double', 'Integer'].include?(properties['type'])) || (name == 'year_built') || (name == 'geometry_unit_num_occupants') # these last 2 are special because ResStockArguments provides the default instead of OS-HPXML
+  extra_args_with_auto = ['year_built', 'geometry_unit_num_occupants', 'geometry_unit_cfa', 'heat_pump_backup_heating_efficiency'] # these are special because ResStockArguments provides the default instead of OS-HPXML
+  if (properties['description'].include?('OS-HPXML default') && ['String', 'Double', 'Integer'].include?(properties['type'])) ||
+     extra_args_with_auto.include?(name)
     resstockarguments_xml[name]['choices'].unshift('auto')
   end
 
   # Convert href to rst for description
   resstockarguments_xml[name]['description'] = href_to_rst(resstockarguments_xml[name]['description'])
 end
 
+# Display arguments in Arguments and Options table by the order they appear in BuildResidentialHPXML, otherwise use ResStockArguments if only defined there
+arg_order = buildreshpxmlarguments_xml.keys
+resstockarguments_xml.keys.each do |k|
+  if !arg_order.include?(k)
+    arg_order << k
+  end
+end
+
 source_report_cols = ['Description', 'Created by', 'Source', 'Assumption']
 arguments_cols = ['Name', 'Required', 'Units', 'Type', 'Choices', 'Description']
 
@@ -181,8 +191,15 @@ def get_measure_xml(filepath)
       line = "   * - #{arguments_col}" if i == 0
       f.puts(line)
     end
-
-    r_arguments = r_arguments.sort_by &resstockarguments_xml.keys.method(:index)
+    if parameter == 'HVAC Heating Efficiency'
+      puts "r_arguments 1 #{r_arguments}"
+    end
+    # r_arguments = r_arguments.sort_by &resstockarguments_xml.keys.method(:index)
+    # r_arguments = r_arguments.sort
+    r_arguments = r_arguments.sort_by &arg_order.method(:index)
+    if parameter == 'HVAC Heating Efficiency'
+      puts "r_arguments 2 #{r_arguments}"
+    end
     r_arguments.each do |r_argument|
       f.puts("   * - ``#{r_argument}``")
       f.puts("     - #{resstockarguments_xml[r_argument]['required']}")