urbanopt-cli 0.5.2 → 0.6.3

data/example_files/resources/hpxml-measures/SimulationOutputReport/measure.xml

@@ -3,8 +3,8 @@
   <schema_version>3.0</schema_version>
   <name>simulation_output_report</name>
   <uid>df9d170c-c21a-4130-866d-0d46b06073fd</uid>
-  <version_id>3b09cd0b-92a2-41c6-b70e-c41c938ff1d2</version_id>
-  <version_modified>20210309T001238Z</version_modified>
+  <version_id>75305b3d-ecfd-4831-8d14-9c791b2b2580</version_id>
+  <version_modified>20210420T225414Z</version_modified>
   <xml_checksum>9BF1E6AC</xml_checksum>
   <class_name>SimulationOutputReport</class_name>
   <display_name>HPXML Simulation Output Report</display_name>
@@ -640,6 +640,13 @@
       <type>Double</type>
       <model_dependent>false</model_dependent>
     </output>
+    <output>
+      <name>End Use: Fuel Oil: Generator MBtu</name>
+      <display_name>End Use: Fuel Oil: Generator MBtu</display_name>
+      <short_name>End Use: Fuel Oil: Generator MBtu</short_name>
+      <type>Double</type>
+      <model_dependent>false</model_dependent>
+    </output>
     <output>
       <name>End Use: Propane: Heating MBtu</name>
       <display_name>End Use: Propane: Heating MBtu</display_name>
@@ -759,6 +766,13 @@
       <type>Double</type>
       <model_dependent>false</model_dependent>
     </output>
+    <output>
+      <name>End Use: Wood Cord: Generator MBtu</name>
+      <display_name>End Use: Wood Cord: Generator MBtu</display_name>
+      <short_name>End Use: Wood Cord: Generator MBtu</short_name>
+      <type>Double</type>
+      <model_dependent>false</model_dependent>
+    </output>
     <output>
       <name>End Use: Wood Pellets: Heating MBtu</name>
       <display_name>End Use: Wood Pellets: Heating MBtu</display_name>
@@ -815,6 +829,13 @@
       <type>Double</type>
       <model_dependent>false</model_dependent>
     </output>
+    <output>
+      <name>End Use: Wood Pellets: Generator MBtu</name>
+      <display_name>End Use: Wood Pellets: Generator MBtu</display_name>
+      <short_name>End Use: Wood Pellets: Generator MBtu</short_name>
+      <type>Double</type>
+      <model_dependent>false</model_dependent>
+    </output>
     <output>
       <name>End Use: Coal: Heating MBtu</name>
       <display_name>End Use: Coal: Heating MBtu</display_name>
@@ -871,6 +892,13 @@
       <type>Double</type>
       <model_dependent>false</model_dependent>
     </output>
+    <output>
+      <name>End Use: Coal: Generator MBtu</name>
+      <display_name>End Use: Coal: Generator MBtu</display_name>
+      <short_name>End Use: Coal: Generator MBtu</short_name>
+      <type>Double</type>
+      <model_dependent>false</model_dependent>
+    </output>
   </outputs>
   <provenances />
   <tags>
@@ -900,12 +928,6 @@
       <usage_type>resource</usage_type>
       <checksum>4E3EAA6F</checksum>
     </file>
-    <file>
-      <filename>output_report_test.rb</filename>
-      <filetype>rb</filetype>
-      <usage_type>test</usage_type>
-      <checksum>4CF3D80C</checksum>
-    </file>
     <file>
       <version>
         <software_program>OpenStudio</software_program>
@@ -915,7 +937,13 @@
       <filename>measure.rb</filename>
       <filetype>rb</filetype>
       <usage_type>script</usage_type>
-      <checksum>F29271E9</checksum>
+      <checksum>19F36E24</checksum>
+    </file>
+    <file>
+      <filename>output_report_test.rb</filename>
+      <filetype>rb</filetype>
+      <usage_type>test</usage_type>
+      <checksum>A9C2B966</checksum>
     </file>
   </files>
 </measure>

data/example_files/resources/hpxml-measures/SimulationOutputReport/tests/output_report_test.rb

@@ -3,7 +3,6 @@
 require_relative '../../HPXMLtoOpenStudio/resources/minitest_helper'
 require 'openstudio'
 require 'openstudio/measure/ShowRunnerOutput'
-require 'minitest/autorun'
 require 'fileutils'
 require 'csv'
 require_relative '../measure.rb'
@@ -69,6 +68,7 @@ class SimulationOutputReportTest < MiniTest::Test
     'End Use: Fuel Oil: Lighting (MBtu)',
     'End Use: Fuel Oil: Fireplace (MBtu)',
     'End Use: Fuel Oil: Mech Vent Preheating (MBtu)',
+    'End Use: Fuel Oil: Generator (MBtu)',
     'End Use: Propane: Heating (MBtu)',
     'End Use: Propane: Hot Water (MBtu)',
     'End Use: Propane: Clothes Dryer (MBtu)',
@@ -86,6 +86,7 @@ class SimulationOutputReportTest < MiniTest::Test
     'End Use: Wood Cord: Lighting (MBtu)',
     'End Use: Wood Cord: Fireplace (MBtu)',
     'End Use: Wood Cord: Mech Vent Preheating (MBtu)',
+    'End Use: Wood Cord: Generator (MBtu)',
     'End Use: Wood Pellets: Heating (MBtu)',
     'End Use: Wood Pellets: Hot Water (MBtu)',
     'End Use: Wood Pellets: Clothes Dryer (MBtu)',
@@ -94,6 +95,7 @@ class SimulationOutputReportTest < MiniTest::Test
     'End Use: Wood Pellets: Lighting (MBtu)',
     'End Use: Wood Pellets: Fireplace (MBtu)',
     'End Use: Wood Pellets: Mech Vent Preheating (MBtu)',
+    'End Use: Wood Pellets: Generator (MBtu)',
     'End Use: Coal: Heating (MBtu)',
     'End Use: Coal: Hot Water (MBtu)',
     'End Use: Coal: Clothes Dryer (MBtu)',
@@ -102,6 +104,7 @@ class SimulationOutputReportTest < MiniTest::Test
     'End Use: Coal: Lighting (MBtu)',
     'End Use: Coal: Fireplace (MBtu)',
     'End Use: Coal: Mech Vent Preheating (MBtu)',
+    'End Use: Coal: Generator (MBtu)',
     'Load: Heating (MBtu)',
     'Load: Cooling (MBtu)',
     'Load: Hot Water: Delivered (MBtu)',
@@ -212,6 +215,7 @@ class SimulationOutputReportTest < MiniTest::Test
     'End Use: Fuel Oil: Grill',
     'End Use: Fuel Oil: Lighting',
     'End Use: Fuel Oil: Fireplace',
+    'End Use: Fuel Oil: Generator',
     'End Use: Propane: Heating',
     'End Use: Propane: Hot Water',
     'End Use: Propane: Clothes Dryer',
@@ -227,6 +231,7 @@ class SimulationOutputReportTest < MiniTest::Test
     'End Use: Wood Cord: Grill',
     'End Use: Wood Cord: Lighting',
     'End Use: Wood Cord: Fireplace',
+    'End Use: Wood Cord: Generator',
     'End Use: Wood Pellets: Heating',
     'End Use: Wood Pellets: Hot Water',
     'End Use: Wood Pellets: Clothes Dryer',
@@ -234,6 +239,7 @@ class SimulationOutputReportTest < MiniTest::Test
     'End Use: Wood Pellets: Grill',
     'End Use: Wood Pellets: Lighting',
     'End Use: Wood Pellets: Fireplace',
+    'End Use: Wood Pellets: Generator',
     'End Use: Coal: Heating',
     'End Use: Coal: Hot Water',
     'End Use: Coal: Clothes Dryer',
@@ -241,6 +247,7 @@ class SimulationOutputReportTest < MiniTest::Test
     'End Use: Coal: Grill',
     'End Use: Coal: Lighting',
     'End Use: Coal: Fireplace',
+    'End Use: Coal: Generator',
   ]
 
   TimeseriesColsWaterUses = [
@@ -383,6 +390,7 @@ class SimulationOutputReportTest < MiniTest::Test
     'enduseFuelOilClothesDryer',
     'enduseFuelOilRangeOven',
     'enduseFuelOilMechVentPreheating',
+    'enduseFuelOilGenerator',
     'endusePropaneHeating',
     'endusePropaneHotWater',
     'endusePropaneClothesDryer',
@@ -394,22 +402,26 @@ class SimulationOutputReportTest < MiniTest::Test
     'enduseWoodCordClothesDryer',
     'enduseWoodCordRangeOven',
     'enduseWoodCordMechVentPreheating',
+    'enduseWoodCordGenerator',
     'enduseWoodPelletsHeating',
     'enduseWoodPelletsHotWater',
     'enduseWoodPelletsClothesDryer',
     'enduseWoodPelletsRangeOven',
     'enduseWoodPelletsMechVentPreheating',
+    'enduseWoodPelletsGenerator',
     'enduseCoalHeating',
     'enduseCoalHotWater',
     'enduseCoalClothesDryer',
     'enduseCoalRangeOven',
     'enduseCoalMechVentPreheating',
+    'enduseCoalGenerator',
     'loadHeating',
     'loadCooling',
     'loadHotWaterDelivered',
     'hpxml_cfa',
     'hpxml_nbr',
     'hpxml_nst',
+    'hpxml_residential_facility_type',
   ]
 
   def all_timeseries_cols
@@ -426,6 +438,7 @@ class SimulationOutputReportTest < MiniTest::Test
 
   def test_annual_only
     args_hash = { 'hpxml_path' => '../workflow/sample_files/base.xml',
+                  'add_component_loads' => true,
                   'timeseries_frequency' => 'hourly',
                   'include_timeseries_fuel_consumptions' => false,
                   'include_timeseries_end_use_consumptions' => false,
@@ -446,6 +459,7 @@ class SimulationOutputReportTest < MiniTest::Test
 
   def test_annual_only2
     args_hash = { 'hpxml_path' => '../workflow/sample_files/base.xml',
+                  'add_component_loads' => true,
                   'timeseries_frequency' => 'none',
                   'include_timeseries_fuel_consumptions' => true,
                   'include_timeseries_end_use_consumptions' => true,
@@ -554,6 +568,7 @@ class SimulationOutputReportTest < MiniTest::Test
 
   def test_timeseries_hourly_component_loads
     args_hash = { 'hpxml_path' => '../workflow/sample_files/base.xml',
+                  'add_component_loads' => true,
                   'timeseries_frequency' => 'hourly',
                   'include_timeseries_fuel_consumptions' => false,
                   'include_timeseries_end_use_consumptions' => false,
@@ -973,14 +988,14 @@ class SimulationOutputReportTest < MiniTest::Test
     require 'oga'
     old_hpxml_path = File.join(File.dirname(__FILE__), '../../workflow/sample_files/base.xml')
     [Constants.CalcTypeERIReferenceHome, Constants.CalcTypeERIReferenceHome].each do |eri_design|
-      new_hpxml_path = File.join(File.dirname(__FILE__), '../../workflow/sample_files/base-eri.xml')
+      new_hpxml_path = File.join(File.dirname(__FILE__), '../../workflow/tests/test-eri.xml')
       FileUtils.cp(old_hpxml_path, new_hpxml_path)
       hpxml = HPXML.new(hpxml_path: new_hpxml_path)
       hpxml.header.eri_design = eri_design
       XMLHelper.write_file(hpxml.to_oga(), new_hpxml_path)
 
       # Run tests
-      args_hash = { 'hpxml_path' => '../workflow/sample_files/base-eri.xml',
+      args_hash = { 'hpxml_path' => '../workflow/tests/test-eri.xml',
                     'timeseries_frequency' => 'hourly',
                     'include_timeseries_fuel_consumptions' => true,
                     'include_timeseries_end_use_consumptions' => true,
@@ -1032,7 +1047,7 @@ class SimulationOutputReportTest < MiniTest::Test
     workflow.setWorkflowSteps(steps)
     osw_path = File.join(File.dirname(template_osw), 'test.osw')
     workflow.saveAs(osw_path)
-    assert_equal(11, found_args.size)
+    assert_equal(args_hash.size, found_args.size)
 
     # Run OSW
     success = system("#{OpenStudio.getOpenStudioCLI} run -w #{osw_path}")
@@ -1042,9 +1057,11 @@ class SimulationOutputReportTest < MiniTest::Test
     File.delete(osw_path)
 
     if not eri_design.nil?
-      annual_csv = File.join(File.dirname(template_osw), File.dirname(args_hash['hpxml_path']), "#{eri_design.gsub(' ', '')}.csv")
-      timeseries_csv = File.join(File.dirname(template_osw), File.dirname(args_hash['hpxml_path']), "#{eri_design.gsub(' ', '')}_Hourly.csv")
-      eri_csv = File.join(File.dirname(template_osw), File.dirname(args_hash['hpxml_path']), "#{eri_design.gsub(' ', '')}_ERI.csv")
+      output_dir = File.dirname(File.join(File.dirname(__FILE__), '..', args_hash['hpxml_path']))
+      hpxml_name = File.basename(args_hash['hpxml_path']).gsub('.xml', '')
+      annual_csv = File.join(output_dir, "#{hpxml_name}.csv")
+      timeseries_csv = File.join(output_dir, "#{hpxml_name}_Hourly.csv")
+      eri_csv = File.join(output_dir, "#{hpxml_name}_ERI.csv")
     else
       annual_csv = File.join(File.dirname(template_osw), 'run', 'results_annual.csv')
       timeseries_csv = File.join(File.dirname(template_osw), 'run', 'results_timeseries.csv')

data/example_files/resources/hpxml-measures/docs/source/getting_started.rst

@@ -6,7 +6,7 @@ Setup
 
 To get started:
 
-#. Download `OpenStudio 3.1.0 <https://github.com/NREL/OpenStudio/releases/tag/v3.1.0>`_ and install the Command Line Interface/EnergyPlus components, or use the `nrel/openstudio docker image <https://hub.docker.com/r/nrel/openstudio>`_.
+#. Download `OpenStudio 3.2.0 <https://github.com/NREL/OpenStudio/releases/tag/v3.2.0>`_ and install the Command Line Interface/EnergyPlus components, or use the `nrel/openstudio docker image <https://hub.docker.com/r/nrel/openstudio>`_.
 #. Download the `latest release <https://github.com/NREL/OpenStudio-HPXML/releases>`_.
 
 Running

data/example_files/resources/hpxml-measures/docs/source/intro.rst

@@ -47,6 +47,7 @@ There are additional ways that software developers using this workflow can reduc
 - Run on Linux/Mac platform, which is significantly faster than Windows.
 - Run on computing environments with 1) fast CPUs, 2) sufficient memory, and 3) enough processors to allow all simulations to run in parallel.
 - Limit requests for timeseries output (e.g., ``--hourly``, ``--daily``, ``--timestep`` arguments) and limit the number of output variables requested.
+- Avoid using the ``--add-component-loads`` argument if heating/cooling component loads are not of interest.
 - Use the ``--skip-validation`` argument if the HPXML input file has already been validated against the Schema & Schematron documents.
 
 License

data/example_files/resources/hpxml-measures/docs/source/workflow_inputs.rst

@@ -636,15 +636,15 @@ Each heating system (other than a heat pump) is entered as an ``/HPXML/Building/
   =================================  ========  ======  ===========  ========  =========  ===============================
   ``SystemIdentifier``               id                             Yes                  Unique identifier
   ``HeatingSystemType``              element           1 [#]_       Yes                  Type of heating system
-  ``FractionHeatLoadServed``         double    frac    0 - 1 [#]_   Yes                  Fraction of heating load served
   ``HeatingSystemFuel``              string            See [#]_     Yes                  Fuel type
   ``HeatingCapacity``                double    Btu/hr  >= 0         No        autosized  Input heating capacity
+  ``FractionHeatLoadServed``         double    frac    0 - 1 [#]_   Yes                  Fraction of heating load served
   =================================  ========  ======  ===========  ========  =========  ===============================
 
   .. [#] HeatingSystemType child element choices are ``ElectricResistance``, ``Furnace``, ``WallFurnace``, ``FloorFurnace``, ``Boiler``, ``Stove``, ``PortableHeater``, ``FixedHeater``, or ``Fireplace``.
-  .. [#] The sum of all ``FractionHeatLoadServed`` (across both HeatingSystems and HeatPumps) must be less than or equal to 1.
   .. [#] HeatingSystemFuel choices are  "electricity", "natural gas", "fuel oil", "fuel oil 1", "fuel oil 2", "fuel oil 4", "fuel oil 5/6", "diesel", "propane", "kerosene", "coal", "coke", "bituminous coal", "wood", or "wood pellets".
          For ``ElectricResistance``, "electricity" is required.
+  .. [#] The sum of all ``FractionHeatLoadServed`` (across both HeatingSystems and HeatPumps) must be less than or equal to 1.
 
 Electric Resistance
 ~~~~~~~~~~~~~~~~~~~
@@ -671,8 +671,8 @@ If a furnace is specified, additional information is entered in ``HeatingSystem`
   ``extension/AirflowDefectRatio``                 double  frac   > -1         No        0.0        Deviation between design/installed airflows [#]_
   ===============================================  ======  =====  ===========  ========  =========  ================================================
 
-  .. [#] HVACDistribution type must be AirDistribution or DSE.
-  .. [#] If FanPowerWattsPerCFM not provided, defaulted to 0.5 W/cfm if AFUE <= 0.9, else 0.375 W/cfm.
+  .. [#] HVACDistribution type must be AirDistribution (type: "regular velocity" or "gravity") or DSE.
+  .. [#] If FanPowerWattsPerCFM not provided, defaulted to 0 W/cfm if gravity distribution system, else 0.5 W/cfm if AFUE <= 0.9, else 0.375 W/cfm.
   .. [#] If there is a cooling system attached to the DistributionSystem, the heating and cooling systems cannot have different values for FanPowerWattsPerCFM.
   .. [#] AirflowDefectRatio is defined as (InstalledAirflow - DesignAirflow) / DesignAirflow; a value of zero means no airflow defect.
          See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information.
@@ -702,26 +702,42 @@ If a boiler is specified, additional information is entered in ``HeatingSystem``
   ``IsSharedSystem``                                                          boolean                        No        false     Whether it serves multiple dwelling units
   ``DistributionSystem``                                                      idref             See [#]_     Yes                 ID of attached distribution system
   ``AnnualHeatingEfficiency[Units="AFUE"]/Value``                             double    frac    0 - 1        Yes                 Rated efficiency
-  ``ElectricAuxiliaryEnergy``                                                 double    kWh/yr  >= 0         No [#]_   See [#]_  Electric auxiliary energy
   ==========================================================================  ========  ======  ===========  ========  ========  =========================================
 
   .. [#] For in-unit boilers, HVACDistribution type must be HydronicDistribution (type: "radiator", "baseboard", "radiant floor", "radiant ceiling", or "water loop") or DSE.
          For shared boilers, HVACDistribution type must be HydronicDistribution (type: "radiator", "baseboard", "radiant floor", "radiant ceiling", or "water loop") or AirDistribution (type: "fan coil").
          If the shared boiler has "water loop" distribution, a :ref:`hvac_heatpump_wlhp` must also be specified.
-  .. [#] | For shared boilers, ElectricAuxiliaryEnergy can alternatively be calculated as follows per `ANSI/RESNET/ICC 301-2019 <https://codes.iccsafe.org/content/RESNETICC3012019>`_:
-         | EAE = (SP / N_dweq + aux_in) * HLH
-         | where
-         | SP = Shared pump power [W] provided as ``extension/SharedLoopWatts``,
-         | N_dweq = Number of units served by the shared system provided as ``NumberofUnitsServed``,
-         | aux_in = In-unit fan coil power [W] provided as ``extension/FanCoilWatts``,
-         | HLH = Annual heating load hours.
-  .. [#] If ElectricAuxiliaryEnergy not provided (nor calculated for shared boilers), defaults as follows per `ANSI/RESNET/ICC 301-2019 <https://codes.iccsafe.org/content/RESNETICC3012019>`_.
-
-         - **Oil boiler**: 330
-         - **Gas boiler (in-unit)**: 170
-         - **Gas boiler (shared, w/ baseboard)**: 220
-         - **Gas boiler (shared, w/ water loop heat pump)**: 265
-         - **Gas boiler (shared, w/ fan coil)**: 438
+
+If an in-unit boiler if specified, additional information is entered in ``HeatingSystem``.
+
+  ===========================  ========  ======  ===========  ========  ========  =========================
+  Element                      Type      Units   Constraints  Required  Default   Notes
+  ===========================  ========  ======  ===========  ========  ========  =========================
+  ``ElectricAuxiliaryEnergy``  double    kWh/yr  >= 0         No        See [#]_  Electric auxiliary energy
+  ===========================  ========  ======  ===========  ========  ========  =========================
+
+  .. [#] If ElectricAuxiliaryEnergy not provided, defaults as follows:
+
+         - **Oil boiler**: 330 kWh/yr
+         - **Gas boiler**: 170 kWh/yr
+
+If instead a shared boiler is specified, additional information is entered in ``HeatingSystem``.
+
+  ============================================================  ========  ===========  ===========  ========  ========  =========================
+  Element                                                       Type      Units        Constraints  Required  Default   Notes
+  ============================================================  ========  ===========  ===========  ========  ========  =========================
+  ``NumberofUnitsServed``                                       integer                > 1          Yes                 Number of dwelling units served
+  ``ElectricAuxiliaryEnergy`` or ``extension/SharedLoopWatts``  double    kWh/yr or W  >= 0         No        See [#]_  Electric auxiliary energy or shared loop power
+  ``ElectricAuxiliaryEnergy`` or ``extension/FanCoilWatts``     double    kWh/yr or W  >= 0         No [#]_             Electric auxiliary energy or fan coil power
+  ============================================================  ========  ===========  ===========  ========  ========  =========================
+
+  .. [#] If ElectricAuxiliaryEnergy nor SharedLoopWatts provided, defaults as follows:
+  
+         - **Shared boiler w/ baseboard**: 220 kWh/yr
+         - **Shared boiler w/ water loop heat pump**: 265 kWh/yr
+         - **Shared boiler w/ fan coil**: 438 kWh/yr
+
+  .. [#] FanCoilWatts only used if boiler connected to fan coil and SharedLoopWatts provided.
 
 Stove
 ~~~~~
@@ -797,7 +813,7 @@ If a central air conditioner is specified, additional information is entered in
   ``extension/ChargeDefectRatio``                  double    frac    > -1         No        0.0        Deviation between design/installed charges [#]_
   ===============================================  ========  ======  ===========  ========  =========  ================================================
 
-  .. [#] HVACDistribution type must be AirDistribution or DSE.
+  .. [#] HVACDistribution type must be AirDistribution (type: "regular velocity") or DSE.
   .. [#] CompressorType choices are "single stage", "two stage", or "variable speed".
   .. [#] If CompressorType not provided, defaults to "single stage" if SEER <= 15, else "two stage" if SEER <= 21, else "variable speed".
   .. [#] If FanPowerWattsPerCFM not provided, defaults to using attached furnace W/cfm if available, else 0.5 W/cfm if SEER <= 13.5, else 0.375 W/cfm.
@@ -832,7 +848,7 @@ If an evaporative cooler is specified, additional information is entered in ``Co
   ``CoolingCapacity``                double    Btu/hr  >= 0         No        autosized  Cooling capacity
   =================================  ========  ======  ===========  ========  =========  ==================================
 
-  .. [#] If provided, HVACDistribution type must be AirDistribution or DSE.
+  .. [#] If provided, HVACDistribution type must be AirDistribution (type: "regular velocity") or DSE.
 
 Mini-Split
 ~~~~~~~~~~
@@ -849,7 +865,7 @@ If a mini-split is specified, additional information is entered in ``CoolingSyst
   ``extension/ChargeDefectRatio``                  double    frac    > -1         No        0.0        Deviation between design/installed charges [#]_
   ===============================================  ========  ======  ===========  ========  =========  ===============================================
 
-  .. [#] If provided, HVACDistribution type must be AirDistribution or DSE.
+  .. [#] If provided, HVACDistribution type must be AirDistribution (type: "regular velocity") or DSE.
   .. [#] ChargeDefectRatio is defined as (InstalledCharge - DesignCharge) / DesignCharge; a value of zero means no refrigerant charge defect.
          See ANSI/RESNET/ACCA 310-2020 Standard for Grading the Installation of HVAC Systems for more information.
 
@@ -886,7 +902,7 @@ If a chiller is specified, additional information is entered in ``CoolingSystem`
 
   .. [#] HVACDistribution type must be HydronicDistribution (type: "radiator", "baseboard", "radiant floor", "radiant ceiling", or "water loop") or AirDistribution (type: "fan coil").
          If the chiller has "water loop" distribution, a :ref:`hvac_heatpump_wlhp` must also be specified.
-  .. [#] FanCoilWatts only required if chiller connected to a fan coil.
+  .. [#] FanCoilWatts only required if chiller connected to fan coil.
   
 .. note::
 
@@ -971,7 +987,7 @@ If an air-to-air heat pump is specified, additional information is entered in ``
   ``extension/ChargeDefectRatio``                  double    frac    > -1         No        0.0        Deviation between design/installed charges [#]_
   ===============================================  ========  ======  ===========  ========  =========  ================================================
 
-  .. [#] HVACDistribution type must be AirDistribution or DSE.
+  .. [#] HVACDistribution type must be AirDistribution (type: "regular velocity") or DSE.
   .. [#] CompressorType choices are "single stage", "two stage", or "variable speed".
   .. [#] If CompressorType not provided, defaults to "single stage" if SEER <= 15, else "two stage" if SEER <= 21, else "variable speed".
   .. [#] The sum of all ``FractionHeatLoadServed`` (across both HeatingSystems and HeatPumps) must be less than or equal to 1.
@@ -1002,7 +1018,7 @@ If a mini-split heat pump is specified, additional information is entered in ``H
   ``extension/ChargeDefectRatio``                  double    frac    > -1         No        0.0        Deviation between design/installed charges [#]_
   ===============================================  ========  ======  ===========  ========  =========  ==============================================
 
-  .. [#] If provided, HVACDistribution type must be AirDistribution or DSE.
+  .. [#] If provided, HVACDistribution type must be AirDistribution (type: "regular velocity") or DSE.
   .. [#] The sum of all ``FractionHeatLoadServed`` (across both HeatingSystems and HeatPumps) must be less than or equal to 1.
   .. [#] The sum of all ``FractionCoolLoadServed`` (across both CoolingSystems and HeatPumps) must be less than or equal to 1.
   .. [#] ChargeDefectRatio is defined as (InstalledCharge - DesignCharge) / DesignCharge; a value of zero means no refrigerant charge defect.
@@ -1028,7 +1044,7 @@ If a ground-to-air heat pump is specified, additional information is entered in
   ===============================================  ========  ======  ===========  ========  =========  ==============================================
   Element                                          Type      Units   Constraints  Required  Default    Notes
   ===============================================  ========  ======  ===========  ========  =========  ==============================================
-  ``IsSharedSystem``                               boolean                        No        false      Whether it serves multiple dwelling units [#]_
+  ``IsSharedSystem``                               boolean                        No        false      Whether it has a shared hydronic circulation loop [#]_
   ``DistributionSystem``                           idref             See [#]_     Yes                  ID of attached distribution system
   ``HeatingCapacity``                              double    Btu/hr  >= 0         No        autosized  Heating capacity (excluding any backup heating)
   ``CoolingCapacity``                              double    Btu/hr  >= 0         No        autosized  Cooling capacity
@@ -1046,7 +1062,7 @@ If a ground-to-air heat pump is specified, additional information is entered in
   ===============================================  ========  ======  ===========  ========  =========  ==============================================
 
   .. [#] IsSharedSystem should be true if the SFA/MF building has multiple ground source heat pumps connected to a shared hydronic circulation loop.
-  .. [#] HVACDistribution type must be AirDistribution or DSE.
+  .. [#] HVACDistribution type must be AirDistribution (type: "regular velocity") or DSE.
   .. [#] The sum of all ``FractionHeatLoadServed`` (across both HeatingSystems and HeatPumps) must be less than or equal to 1.
   .. [#] The sum of all ``FractionCoolLoadServed`` (across both CoolingSystems and HeatPumps) must be less than or equal to 1.
   .. [#] NumberofUnitsServed only required if IsSharedSystem is true, in which case it must be > 1.
@@ -1079,7 +1095,7 @@ If a water-loop-to-air heat pump is specified, additional information is entered
   ``AnnualHeatingEfficiency[Units="COP"]/Value``   double    W/W     > 0          See [#]_             Rated heating efficiency
   ===============================================  ========  ======  ===========  ========  =========  ==============================================
 
-  .. [#] HVACDistribution type must be AirDistribution or DSE.
+  .. [#] HVACDistribution type must be AirDistribution (type: "regular velocity") or DSE.
   .. [#] CoolingCapacity required if there is a shared chiller or cooling tower with water loop distribution.
   .. [#] AnnualCoolingEfficiency required if there is a shared chiller or cooling tower with water loop distribution.
   .. [#] AnnualHeatingEfficiency required if there is a shared boiler with water loop distribution.
@@ -1166,7 +1182,7 @@ Each separate HVAC distribution system is entered as a ``/HPXML/Building/Buildin
   ==============================  =======  =======  ===========  ========  =========  =============================
 
   .. [#] DistributionSystemType child element choices are ``AirDistribution``, ``HydronicDistribution``, or ``Other=DSE``.
-  .. [#] ConditionedFloorAreaServed is required for AirDistribution type.
+  .. [#] ConditionedFloorAreaServed required only when DistributionSystemType is AirDistribution and ``AirDistribution/Ducts`` are present.
 
 .. note::
   
@@ -1184,17 +1200,18 @@ To define an air distribution system, additional information is entered in ``HVA
   =============================================  =======  =======  ===========  ========  =========  ==========================
   Element                                        Type     Units    Constraints  Required  Default    Notes
   =============================================  =======  =======  ===========  ========  =========  ==========================
-  ``AirDistributionType``                        string            See [#]_     See [#]_             Type of air distribution
-  ``DuctLeakageMeasurement[DuctType="supply"]``  element           1            Yes                  Supply duct leakage value
-  ``DuctLeakageMeasurement[DuctType="return"]``  element           1            Yes                  Return duct leakage value
+  ``AirDistributionType``                        string            See [#]_     Yes                  Type of air distribution
+  ``DuctLeakageMeasurement[DuctType="supply"]``  element           1            See [#]_             Supply duct leakage value
+  ``DuctLeakageMeasurement[DuctType="return"]``  element           1            See [#]_             Return duct leakage value
   ``Ducts``                                      element           >= 0         No                   Supply/return ducts [#]_
   ``NumberofReturnRegisters``                    integer           >= 0         No        See [#]_   Number of return registers
   =============================================  =======  =======  ===========  ========  =========  ==========================
   
-  .. [#] AirDistributionType choices are "gravity", "high velocity", "regular velocity", or "fan coil".
-  .. [#] AirDistributionType only required if the distribution system is for shared boilers/chillers with fan coils, in which case value must be "fan coil".
+  .. [#] AirDistributionType choices are "regular velocity", "gravity", or "fan coil" and are further restricted based on attached HVAC system type (e.g., only "regular velocity" or "gravity" for a furnace, only "fan coil" for a shared boiler, etc.).
+  .. [#] Supply duct leakage required if AirDistributionType is "regular velocity" or "gravity" and optional if AirDistributionType is "fan coil".
+  .. [#] 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, 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.
+  .. [#] If NumberofReturnRegisters not provided and ``AirDistribution/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.
 
 Additional information is entered in each ``DuctLeakageMeasurement``.
 
@@ -1795,7 +1812,7 @@ If not entered, the simulation will not include generators.
   ``NumberofBedroomsServed``  integer           > 1          See [#]_           Number of bedrooms served
   ==========================  =======  =======  ===========  ========  =======  ============================================
 
-  .. [#] FuelType choices are "natural gas" or "propane".
+  .. [#] FuelType choices are "natural gas", "fuel oil", "fuel oil 1", "fuel oil 2", "fuel oil 4", "fuel oil 5/6", "diesel", "propane", "kerosene", "coal", "coke", "bituminous coal", "anthracite coal", "wood", or "wood pellets".
   .. [#] AnnualOutputkWh must also be < AnnualConsumptionkBtu*3.412 (i.e., the generator must consume more energy than it produces).
   .. [#] NumberofBedroomsServed only required if IsSharedSystem is true, in which case it must be > NumberofBedrooms.
          Annual consumption and annual production will be apportioned to the dwelling unit using its number of bedrooms divided by the total number of bedrooms served by the generator.
@@ -2417,28 +2434,28 @@ HPXML Locations
 
 The various locations used in an HPXML file are defined as follows:
 
-  ==============================  ===========================================  =======================================  =============
-  Value                           Description                                  Temperature                              Building Type
-  ==============================  ===========================================  =======================================  =============
-  outside                         Ambient environment                          Weather data                             Any
-  ground                                                                       EnergyPlus calculation                   Any
-  living space                    Above-grade conditioned floor area           EnergyPlus calculation                   Any
-  attic - vented                                                               EnergyPlus calculation                   Any
-  attic - unvented                                                             EnergyPlus calculation                   Any
-  basement - conditioned          Below-grade conditioned floor area           EnergyPlus calculation                   Any
-  basement - unconditioned                                                     EnergyPlus calculation                   Any
-  crawlspace - vented                                                          EnergyPlus calculation                   Any
-  crawlspace - unvented                                                        EnergyPlus calculation                   Any
-  garage                          Single-family garage (not shared parking)    EnergyPlus calculation                   Any
-  other housing unit              E.g., conditioned adjacent unit or corridor  Same as living space                     SFA/MF only
-  other heated space              E.g., shared laundry/equipment space         Avg of living space/outside; min of 68F  SFA/MF only
-  other multifamily buffer space  E.g., enclosed unconditioned stairwell       Avg of living space/outside; min of 50F  SFA/MF only
-  other non-freezing space        E.g., shared parking garage ceiling          Floats with outside; minimum of 40F      SFA/MF only
-  other exterior                  Water heater outside                         Weather data                             Any
-  exterior wall                   Ducts in exterior wall                       Avg of living space/outside              Any
-  under slab                      Ducts under slab (ground)                    EnergyPlus calculation                   Any
-  roof deck                       Ducts on roof deck (outside)                 Weather data                             Any
-  ==============================  ===========================================  =======================================  =============
+  ==============================  =======================================================  =======================================  =============
+  Value                           Description                                              Temperature                              Building Type
+  ==============================  =======================================================  =======================================  =============
+  outside                         Ambient environment                                      Weather data                             Any
+  ground                                                                                   EnergyPlus calculation                   Any
+  living space                    Above-grade conditioned floor area                       EnergyPlus calculation                   Any
+  attic - vented                                                                           EnergyPlus calculation                   Any
+  attic - unvented                                                                         EnergyPlus calculation                   Any
+  basement - conditioned          Below-grade conditioned floor area                       EnergyPlus calculation                   Any
+  basement - unconditioned                                                                 EnergyPlus calculation                   Any
+  crawlspace - vented                                                                      EnergyPlus calculation                   Any
+  crawlspace - unvented                                                                    EnergyPlus calculation                   Any
+  garage                          Single-family garage (not shared parking)                EnergyPlus calculation                   Any
+  other housing unit              E.g., conditioned adjacent unit or conditioned corridor  Same as living space                     SFA/MF only
+  other heated space              E.g., shared laundry/equipment space                     Avg of living space/outside; min of 68F  SFA/MF only
+  other multifamily buffer space  E.g., enclosed unconditioned stairwell                   Avg of living space/outside; min of 50F  SFA/MF only
+  other non-freezing space        E.g., shared parking garage ceiling                      Floats with outside; minimum of 40F      SFA/MF only
+  other exterior                  Water heater outside                                     Weather data                             Any
+  exterior wall                   Ducts in exterior wall                                   Avg of living space/outside              Any
+  under slab                      Ducts under slab (ground)                                EnergyPlus calculation                   Any
+  roof deck                       Ducts on roof deck (outside)                             Weather data                             Any
+  ==============================  =======================================================  =======================================  =============
 
 Validating & Debugging Errors
 -----------------------------

data/example_files/resources/hpxml-measures/docs/source/workflow_outputs.rst

@@ -60,7 +60,7 @@ So the sum of all end uses for a given fuel (e.g., sum of all "End Use: Natural
    End Use: Electricity: Cooling Fans/Pumps (MBtu)
    End Use: Electricity: Hot Water (MBtu)                              Excludes recirc pump and solar thermal pump
    End Use: Electricity: Hot Water Recirc Pump (MBtu)
-   End Use: Electricity: Hot Water Solar Thermal Pump (MBtu)
+   End Use: Electricity: Hot Water Solar Thermal Pump (MBtu)           Non-zero only when using detailed (not simple) solar thermal inputs
    End Use: Electricity: Lighting Interior (MBtu)
    End Use: Electricity: Lighting Garage (MBtu)
    End Use: Electricity: Lighting Exterior (MBtu)
@@ -208,8 +208,12 @@ Current peak building loads are listed below.
 Annual Component Building Loads
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+**Note**: This section is only available if the ``--add-component-loads`` argument is used.
+The argument is not used by default for faster performance.
+
 Component loads represent the estimated contribution of different building components to the annual heating/cooling building loads.
 The sum of component loads for heating (or cooling) will roughly equal the annual heating (or cooling) building load reported above.
+
 Current component loads disaggregated by Heating/Cooling are listed below.
    
    ================================================= =========================================================================================================