Add --ems-debug argument

Changelog.md

@@ -6,6 +6,7 @@ __New Features__
   - Improves handling of duct leakage specified using cfm25/cfm50.
 - Output updates:
   - **Breaking change**: Replaces "UnitX" prefixes with Building IDs in whole SFA/MF building timeseries outputs.
+- Adds a `run_simulation.rb --ems-debug` argument to generate the EnergyPlus EDD file for debugging EMS programs.
 
 __Bugfixes__
 - Fixes a misleading warning about adjusting inverted setpoints when heating setpoint is greater than cooling setpoint during non-overlapping heating/cooling seasons.

HPXMLtoOpenStudio/README.md

@@ -123,6 +123,17 @@ If true: 1) Writes in.osm file, 2) Generates additional log output, and 3) Creat
 
 <br/>
 
+**EMS Debug Mode?**
+
+If true, writes the EnergyPlus EDD file with timeseries debug output for each EMS program. Note that this file can be VERY large.
+
+- **Name:** ``ems_debug``
+- **Type:** ``Boolean``
+
+- **Required:** ``false``
+
+<br/>
+
 
 
 

HPXMLtoOpenStudio/measure.rb

@@ -97,6 +97,12 @@ def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
     arg.setDefaultValue(false)
     args << arg
 
+    arg = OpenStudio::Measure::OSArgument.makeBoolArgument('ems_debug', false)
+    arg.setDisplayName('EMS Debug Mode?')
+    arg.setDescription('If true, writes the EnergyPlus EDD file with timeseries debug output for each EMS program. Note that this file can be VERY large.')
+    arg.setDefaultValue(false)
+    args << arg
+
     return args
   end
 
@@ -157,7 +163,9 @@ def run(model, runner, user_arguments)
       Outputs.apply_output_file_controls(model, args[:debug])
       Outputs.apply_additional_properties(model, hpxml, hpxml_osm_map, args[:hpxml_path], args[:building_id], args[:hpxml_defaults_path])
       Outputs.create_custom_meters(model)
-      # Outputs.apply_ems_debug_output(model) # Uncomment to debug EMS
+      if args[:ems_debug]
+        Outputs.apply_ems_debug_output(model)
+      end
 
       # Write output files
       Outputs.write_debug_files(runner, model, weather, args[:debug], args[:output_dir])

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>9af3a707-de47-44da-b7c0-f7f342e996b6</version_id>
-  <version_modified>2026-02-09T23:23:03Z</version_modified>
+  <version_id>5a120116-1373-4af0-a27c-7cc4e9baa6ed</version_id>
+  <version_modified>2026-02-10T22:02:46Z</version_modified>
   <xml_checksum>D8922A73</xml_checksum>
   <class_name>HPXMLtoOpenStudio</class_name>
   <display_name>HPXML to OpenStudio Translator</display_name>
@@ -142,6 +142,25 @@
         </choice>
       </choices>
     </argument>
+    <argument>
+      <name>ems_debug</name>
+      <display_name>EMS Debug Mode?</display_name>
+      <description>If true, writes the EnergyPlus EDD file with timeseries debug output for each EMS program. Note that this file can be VERY large.</description>
+      <type>Boolean</type>
+      <required>false</required>
+      <model_dependent>false</model_dependent>
+      <default_value>false</default_value>
+      <choices>
+        <choice>
+          <value>true</value>
+          <display_name>true</display_name>
+        </choice>
+        <choice>
+          <value>false</value>
+          <display_name>false</display_name>
+        </choice>
+      </choices>
+    </argument>
   </arguments>
   <outputs />
   <provenances />
@@ -175,7 +194,7 @@
       <filename>README.md</filename>
       <filetype>md</filetype>
       <usage_type>readme</usage_type>
-      <checksum>CEF23103</checksum>
+      <checksum>1C614A83</checksum>
     </file>
     <file>
       <filename>README.md.erb</filename>
@@ -192,7 +211,7 @@
       <filename>measure.rb</filename>
       <filetype>rb</filetype>
       <usage_type>script</usage_type>
-      <checksum>A413C5F4</checksum>
+      <checksum>DF6F2409</checksum>
     </file>
     <file>
       <filename>airflow.rb</filename>

workflow/run_simulation.rb

@@ -18,7 +18,7 @@
 def run_workflow(basedir, rundir, hpxml, debug, skip_validation, add_comp_loads,
                  output_format, building_id, ep_input_format, stochastic_schedules,
                  hourly_outputs, daily_outputs, monthly_outputs, timestep_outputs,
-                 skip_simulation, master_seed)
+                 skip_simulation, master_seed, ems_debug)
 
   measures_dir = File.join(basedir, '..')
   measures = {}
@@ -46,6 +46,7 @@ def run_workflow(basedir, rundir, hpxml, debug, skip_validation, add_comp_loads,
   args['skip_validation'] = skip_validation
   args['building_id'] = building_id
   args['debug'] = debug
+  args['ems_debug'] = ems_debug
   measures[measure_subdir] = [args]
 
   if not skip_simulation
@@ -198,6 +199,11 @@ def run_workflow(basedir, rundir, hpxml, debug, skip_validation, add_comp_loads,
     options[:debug] = true
   end
 
+  options[:ems_debug] = false
+  opts.on('-e', '--ems-debug', 'Generate EnergyPlus EDD file for EMS debugging; can be VERY large') do |_t|
+    options[:ems_debug] = true
+  end
+
   opts.on_tail('-h', '--help', 'Display help') do
     puts opts
     exit!
@@ -243,7 +249,7 @@ def run_workflow(basedir, rundir, hpxml, debug, skip_validation, add_comp_loads,
   success = run_workflow(basedir, rundir, options[:hpxml], options[:debug], options[:skip_validation], options[:add_comp_loads],
                          options[:output_format], options[:building_id], options[:ep_input_format], options[:stochastic_schedules],
                          options[:hourly_outputs], options[:daily_outputs], options[:monthly_outputs], options[:timestep_outputs],
-                         options[:skip_simulation], options[:master_seed])
+                         options[:skip_simulation], options[:master_seed], options[:ems_debug])
 
   if not success
     exit! 1

workflow/template-build-and-run-hpxml-with-stochastic-occupancy.osw

@@ -57,6 +57,7 @@
         "hpxml_path": "../built.xml",
         "output_dir": "..",
         "debug": false,
+        "ems_debug": false,
         "add_component_loads": false,
         "skip_validation": false
       },

workflow/template-build-and-run-hpxml.osw

@@ -49,6 +49,7 @@
         "hpxml_path": "../built.xml",
         "output_dir": "..",
         "debug": false,
+        "ems_debug": false,
         "add_component_loads": false,
         "skip_validation": false
       },

workflow/template-run-hpxml-with-stochastic-occupancy-subset.osw

@@ -18,6 +18,7 @@
         "hpxml_path": "../built-stochastic-schedules.xml",
         "output_dir": "..",
         "debug": false,
+        "ems_debug": false,
         "add_component_loads": false,
         "skip_validation": false
       },

workflow/template-run-hpxml-with-stochastic-occupancy.osw

@@ -17,6 +17,7 @@
         "hpxml_path": "../built-stochastic-schedules.xml",
         "output_dir": "..",
         "debug": false,
+        "ems_debug": false,
         "add_component_loads": false,
         "skip_validation": false
       },

workflow/template-run-hpxml.osw

@@ -9,6 +9,7 @@
         "hpxml_path": "../../sample_files/base.xml",
         "output_dir": "..",
         "debug": false,
+        "ems_debug": false,
         "add_component_loads": false,
         "skip_validation": false,
         "building_id": ""

workflow/tests/test_other.rb

@@ -20,7 +20,7 @@ def test_run_simulation_output_formats
 
       # Check for output files
       run_dir = File.join(File.dirname(xml), 'run')
-      assert(File.exist? File.join(run_dir, 'eplusout.msgpack')) # Produced because --debug flag if used
+      assert(File.exist? File.join(run_dir, 'eplusout.msgpack')) # Produced because --debug flag is used
       assert(File.exist? File.join(run_dir, "results_annual.#{output_format}"))
       assert(File.exist? File.join(run_dir, "results_timeseries.#{output_format}"))
       assert(File.exist?(File.join(run_dir, "results_bills.#{output_format}")))
@@ -78,6 +78,21 @@ def test_run_simulation_idf_input
     refute(File.exist? File.join(run_dir, 'eplusout.msgpack'))
   end
 
+  def test_run_simulation_ems_debug
+    rb_path = File.join(File.dirname(__FILE__), '..', 'run_simulation.rb')
+    xml = File.join(File.dirname(__FILE__), '..', 'sample_files', 'base.xml')
+    command = "\"#{OpenStudio.getOpenStudioCLI}\" \"#{rb_path}\" -x \"#{xml}\" --ems-debug"
+    system(command, err: File::NULL)
+
+    # Check for output file
+    run_dir = File.join(File.dirname(xml), 'run')
+    edd_path = File.join(run_dir, 'eplusout.edd')
+    assert(File.exist? edd_path) # Produced because --ems-debug flag is used
+
+    # Cleanup
+    File.delete(edd_path)
+  end
+
   def test_run_simulation_faster_performance
     # Run w/ --skip-validation and w/o --add-component-loads arguments
     rb_path = File.join(File.dirname(__FILE__), '..', 'run_simulation.rb')