Allow diagnostic output

.github/workflows/config.yml

@@ -164,7 +164,7 @@ jobs:
           $env:OS_SHA="f953b6fcaf"
           Invoke-WebRequest -OutFile Windows.tar.gz -URI "https://github.com/NREL/OpenStudio/releases/download/v${env:OS_VERSION}/OpenStudio-${env:OS_VERSION}+${env:OS_SHA}-Windows.tar.gz"
           tar -xzf Windows.tar.gz
-          & .\OpenStudio-${env:OS_VERSION}+${env:OS_SHA}-Windows\bin\openstudio.exe workflow\energy_rating_index.rb -x workflow\sample_files\base.xml --hourly ALL --add-component-loads
+          & .\OpenStudio-${env:OS_VERSION}+${env:OS_SHA}-Windows\bin\openstudio.exe workflow\energy_rating_index.rb -x workflow\sample_files\base.xml --daily ALL --add-component-loads --diagnostic-output
 
   merge-results:
     runs-on: ubuntu-latest

Changelog.md

@@ -14,6 +14,7 @@ __New Features__
 - HERS software tests:
   - HERS Hot Water test HPXMLs have been updated to be direct EnergyPlus simulations (like the HERS HVAC & DSE tests already were); they are no longer run through ERI simulations.
   - HERS HVAC DSE tests now use duct effective R-values instead of nominal insulation R-values to demonstrate that they pass RESNET acceptance criteria.
+- Adds `--diagnostic-output` commandline argument to produce a diagnostic output file per the [HERS Diagnostic Output Schema](https://github.com/resnet-us/hers-diagnostic-schema).
 - Allows `AverageCeilingHeight` to be optionally provided for infiltration calculations.
 - Allows `Roof/RadiantBarrier` to be omitted; defaults to false.
 - Allows `FractionDuctArea` as alternative to `DuctSurfaceArea`

Gemfile

@@ -12,3 +12,4 @@ gem 'parallel'
 gem 'simplecov'
 gem 'simplecov-html'
 gem 'rubyzip'
+gem 'json-schema'

docs/source/usage_instructions.rst

@@ -41,6 +41,9 @@ You can also skip simulations (i.e., just generate the ERI Reference/Rated Home
 Or you can request all output files in JSON (instead of CSV) format:
 ``openstudio workflow/energy_rating_index.rb -x workflow/sample_files/base.xml --output-format json``
 
+Finally, you can generate a HERS diagnostic output file using, e.g.:
+``openstudio workflow/energy_rating_index.rb -x workflow/sample_files/base.xml --diagnostic-output``
+
 Run ``openstudio workflow/energy_rating_index.rb -h`` to see all available commands/arguments.
 
 Output

docs/source/workflow_outputs.rst

@@ -13,6 +13,7 @@ Upon completing an OpenStudio-ERI run, a variety of summary output files and sim
 - :ref:`home_timeseries_outputs_csv`
 - :ref:`home_configurations_hpxml`
 - :ref:`home_energyplus_files`
+- :ref:`hers_diagnostic_output`
 
 All CSV output files can be alternatively requested in JSON format; see :ref:`running`.
 
@@ -660,3 +661,11 @@ In addition, raw EnergyPlus simulation input/output files are available for each
   It is highly discouraged for software tools to read the raw EnergyPlus output files. 
   The EnergyPlus input/output files are made available for inspection, but the outputs for certain situations can be misleading if one does not know how the model was created. 
   If there are additional outputs of interest that are not available in the annual/timeseries output files, please send us a request.
+
+.. _hers_diagnostic_output:
+
+HERS Diagnostic Output
+----------------------
+
+A HERS diagnostic output file (``HERS_Diagnostic.json``) can be produced if the ``--output-diagnostic`` commandline argument is used; see the :ref:`running` section.
+The output file includes hourly data and is formatted per the `HERS Diagnostic Output Schema <https://github.com/resnet-us/hers-diagnostic-schema>`_.

hpxml-measures/Changelog.md

@@ -90,6 +90,7 @@ __Bugfixes__
 - Fixes buried duct effective R-values.
 - Fixes shared boiler default location (which could result in assuming there's a flue in conditioned space impacting infiltration).
 - Fixes timeseries hot water energy consumption adjustment lag (associated with hot water distribution).
+- Fixes possibility of negative timeseries delivered loads when there is a dehumidifier.
 
 ## OpenStudio-HPXML v1.7.0
 

hpxml-measures/HPXMLtoOpenStudio/measure.rb

@@ -2203,7 +2203,7 @@ def add_total_loads_output(model, hpxml_osm_map)
     htg_cond_load_sensors, clg_cond_load_sensors = {}, {}
     htg_duct_load_sensors, clg_duct_load_sensors = {}, {}
     total_heat_load_serveds, total_cool_load_serveds = {}, {}
-    dehumidifier_sensors = {}
+    dehumidifier_global_vars, dehumidifier_sensors = {}, {}
 
     hpxml_osm_map.each_with_index do |(hpxml_bldg, unit_model), unit|
       # Retrieve objects
@@ -2237,9 +2237,29 @@ def add_total_loads_output(model, hpxml_osm_map)
         clg_duct_load_sensors[unit][-1].setName('clg_load_duct')
       end
 
-      # Need to adjusted E+ EnergyTransfer meters for dehumidifier internal gains
       next if dehumidifier_name.nil?
 
+      # Need to adjust E+ EnergyTransfer meters for dehumidifier internal gains.
+      # We also offset the dehumidifier load by one timestep so that it aligns with the EnergyTransfer meters.
+
+      # Global Variable
+      dehumidifier_global_vars[unit] = OpenStudio::Model::EnergyManagementSystemGlobalVariable.new(model, "prev_#{dehumidifier_name}")
+
+      # Initialization Program
+      timestep_offset_program = OpenStudio::Model::EnergyManagementSystemProgram.new(model)
+      timestep_offset_program.setName("#{dehumidifier_name} timestep offset init program")
+      timestep_offset_program.addLine("Set #{dehumidifier_global_vars[unit].name} = 0")
+
+      # calling managers
+      manager = OpenStudio::Model::EnergyManagementSystemProgramCallingManager.new(model)
+      manager.setName("#{timestep_offset_program.name} calling manager")
+      manager.setCallingPoint('BeginNewEnvironment')
+      manager.addProgram(timestep_offset_program)
+      manager = OpenStudio::Model::EnergyManagementSystemProgramCallingManager.new(model)
+      manager.setName("#{timestep_offset_program.name} calling manager2")
+      manager.setCallingPoint('AfterNewEnvironmentWarmUpIsComplete')
+      manager.addProgram(timestep_offset_program)
+
       dehumidifier_sensors[unit] = OpenStudio::Model::EnergyManagementSystemSensor.new(model, 'Zone Dehumidifier Sensible Heating Energy')
       dehumidifier_sensors[unit].setName('ig_dehumidifier')
       dehumidifier_sensors[unit].setKeyName(dehumidifier_name)
@@ -2257,22 +2277,30 @@ def add_total_loads_output(model, hpxml_osm_map)
       for i in 0..htg_duct_load_sensors[unit].size - 1
         program.addLine("  Set loads_htg_tot = loads_htg_tot + (#{htg_duct_load_sensors[unit][i].name} - #{clg_duct_load_sensors[unit][i].name}) * #{total_heat_load_serveds[unit]}")
       end
-      if not dehumidifier_sensors[unit].nil?
-        program.addLine("  Set loads_htg_tot = loads_htg_tot - #{dehumidifier_sensors[unit].name}")
+      if not dehumidifier_global_vars[unit].nil?
+        program.addLine("  Set loads_htg_tot = loads_htg_tot - #{dehumidifier_global_vars[unit].name}")
       end
       program.addLine('EndIf')
     end
+    program.addLine('Set loads_htg_tot = (@Max loads_htg_tot 0)')
     for unit in 0..hpxml_osm_map.size - 1
       program.addLine("If #{clg_cond_load_sensors[unit].name} > 0")
       program.addLine("  Set loads_clg_tot = loads_clg_tot + (#{clg_cond_load_sensors[unit].name} - #{htg_cond_load_sensors[unit].name}) * #{total_cool_load_serveds[unit]}")
       for i in 0..clg_duct_load_sensors[unit].size - 1
         program.addLine("  Set loads_clg_tot = loads_clg_tot + (#{clg_duct_load_sensors[unit][i].name} - #{htg_duct_load_sensors[unit][i].name}) * #{total_cool_load_serveds[unit]}")
       end
-      if not dehumidifier_sensors[unit].nil?
-        program.addLine("  Set loads_clg_tot = loads_clg_tot + #{dehumidifier_sensors[unit].name}")
+      if not dehumidifier_global_vars[unit].nil?
+        program.addLine("  Set loads_clg_tot = loads_clg_tot + #{dehumidifier_global_vars[unit].name}")
       end
       program.addLine('EndIf')
     end
+    program.addLine('Set loads_clg_tot = (@Max loads_clg_tot 0)')
+    for unit in 0..hpxml_osm_map.size - 1
+      if not dehumidifier_global_vars[unit].nil?
+        # Store dehumidifier internal gain, will be used in EMS program next timestep
+        program.addLine("Set #{dehumidifier_global_vars[unit].name} = #{dehumidifier_sensors[unit].name}")
+      end
+    end
 
     # EMS calling manager
     program_calling_manager = OpenStudio::Model::EnergyManagementSystemProgramCallingManager.new(model)

hpxml-measures/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>74afbf86-1597-475c-9d85-162dda013201</version_id>
-  <version_modified>2024-05-24T00:01:31Z</version_modified>
+  <version_id>0ce29ed9-b37e-43a9-bfb7-7012551f3261</version_id>
+  <version_modified>2024-05-24T17:00:29Z</version_modified>
   <xml_checksum>D8922A73</xml_checksum>
   <class_name>HPXMLtoOpenStudio</class_name>
   <display_name>HPXML to OpenStudio Translator</display_name>
@@ -183,7 +183,7 @@
       <filename>measure.rb</filename>
       <filetype>rb</filetype>
       <usage_type>script</usage_type>
-      <checksum>4D2BAEDD</checksum>
+      <checksum>BC3E7A02</checksum>
     </file>
     <file>
       <filename>airflow.rb</filename>
@@ -381,7 +381,7 @@
       <filename>hvac.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>FC8B73E3</checksum>
+      <checksum>EE17B11F</checksum>
     </file>
     <file>
       <filename>hvac_sizing.rb</filename>

hpxml-measures/HPXMLtoOpenStudio/resources/hvac.rb

@@ -809,6 +809,7 @@ def self.apply_dehumidifiers(runner, model, dehumidifiers, conditioned_space, un
       d.energy_factor, d.capacity = apply_dehumidifier_ief_to_ef_inputs(d.type, w_coeff, ef_coeff, d.integrated_energy_factor, d.capacity)
     end
 
+    # Combine HPXML dehumidifiers into a single EnergyPlus dehumidifier
     total_capacity = dehumidifiers.map { |d| d.capacity }.sum
     avg_energy_factor = dehumidifiers.map { |d| d.energy_factor * d.capacity }.sum / total_capacity
     total_fraction_served = dehumidifiers.map { |d| d.fraction_served }.sum