Pre peak check

docs/read_the_docs/source/basic_tutorial/architecture.rst

@@ -65,6 +65,7 @@ The BuildExistingModel and ApplyUpgrade meta measures call the following model m
   1     ResStockArguments             Model              No                      ResStock
   2     BuildResidentialHPXML         Model              No                      OS-HPXML
   3     BuildResidentialScheduleFile  Model              No                      OS-HPXML
+  4     ResStockArgumentsPostHPXML    Model              No                      ResStock
   ===== ============================= ================== ========= ============= ==========================
 
 .. _model-measures:
@@ -117,6 +118,16 @@ They contribute to the generation of the model.
        :start-after: <modeler_description>
        :end-before: <
 
+**ResStockArgumentsPostHPXML**
+
+    .. include:: ../../../../measures/ResStockArgumentsPostHPXML/measure.xml
+       :start-after: <description>
+       :end-before: <
+
+    .. include:: ../../../../measures/ResStockArgumentsPostHPXML/measure.xml
+       :start-after: <modeler_description>
+       :end-before: <
+
 .. _tutorial-apply-upgrade:
 
 **ApplyUpgrade**

docs/read_the_docs/source/changelog/changelog_dev.rst

@@ -141,3 +141,19 @@ Development Changelog
 
         Description:
         The purpose of this PR is to set a value in ResStockArguments for apartment units based on the type/size of MF building and where the unit is located (lower, middle, or upper story).
+
+    .. change::
+        :tags: workflow, feature
+        :pullreq: 929
+
+        **Date**: 2024-10-14
+
+        Title:
+        New ResStockArgumentsPostHPXML measure
+
+        Description:
+        This measure is added to the workflow to post-process the output of the BuildResidentialHPXML and BuildResidentialScheduleFile measures.
+
+        Assignees: Joe Robertson, Rajendra Adhikari
+
+        GitHub: `pull request 929 <https://github.com/NREL/resstock/pull/929>`_   

measures/ApplyUpgrade/measure.rb

@@ -519,11 +519,21 @@ def run(model, runner, user_arguments)
       register_logs(runner, new_runner)
       return false
     end
+    measures['ResStockArgumentsPostHPXML'] = [{}] if !measures.keys.include?('ResStockArgumentsPostHPXML')
+    measures['ResStockArgumentsPostHPXML'][0]['hpxml_path'] = hpxml_path
+    measures['ResStockArgumentsPostHPXML'][0]['output_csv_path'] = File.expand_path('../schedules.csv')
+    measures['ResStockArgumentsPostHPXML'][0]['building_id'] = values['building_id']
+    measures_hash = { 'ResStockArgumentsPostHPXML' => measures['ResStockArgumentsPostHPXML'] }
+    if not apply_measures(measures_dir, measures_hash, new_runner, model, true, 'OpenStudio::Measure::ModelMeasure', nil)
+      register_logs(runner, new_runner)
+      return false
+    end
 
     # Specify measures to run
     measures_to_apply_hash = { measures_dir => {} }
 
-    upgrade_measures = measures.keys - ['ResStockArguments', 'BuildResidentialHPXML', 'BuildResidentialScheduleFile']
+    upgrade_measures = measures.keys - ['ResStockArguments', 'BuildResidentialHPXML', 'BuildResidentialScheduleFile',
+                                        'ResStockArgumentsPostHPXML']
     upgrade_measures.each do |upgrade_measure|
       measures_to_apply_hash[measures_dir][upgrade_measure] = measures[upgrade_measure]
     end
@@ -537,14 +547,14 @@ def run(model, runner, user_arguments)
       register_logs(runner, new_runner)
       return false
     end
-
     # Copy upgraded.xml to home.xml for downstream HPXMLtoOpenStudio
     # This will overwrite home.xml from BuildExistingModel
     # We need upgraded.xml (and not just home.xml) for UpgradeCosts
     in_path = File.expand_path('../home.xml')
     FileUtils.cp(hpxml_path, in_path)
 
     register_logs(runner, resstock_arguments_runner)
+    register_logs(runner, new_runner)
 
     return true
   end

measures/BuildExistingModel/measure.rb

@@ -752,6 +752,16 @@ def run(model, runner, user_arguments)
       end
     end
 
+    measures['ResStockArgumentsPostHPXML'] = [{}] if !measures.keys.include?('ResStockArgumentsPostHPXML')
+    measures['ResStockArgumentsPostHPXML'][0]['hpxml_path'] = hpxml_path
+    measures['ResStockArgumentsPostHPXML'][0]['output_csv_path'] = File.expand_path('../schedules.csv')
+    measures['ResStockArgumentsPostHPXML'][0]['building_id'] = args[:building_id]
+    measures_hash = { 'ResStockArgumentsPostHPXML' => measures['ResStockArgumentsPostHPXML'] }
+    if not apply_measures(measures_dir, measures_hash, new_runner, model, true, 'OpenStudio::Measure::ModelMeasure', nil)
+      register_logs(runner, new_runner)
+      return false
+    end
+
     # Copy existing.xml to home.xml for downstream HPXMLtoOpenStudio
     # We need existing.xml (and not just home.xml) for UpgradeCosts
     in_path = File.expand_path('../home.xml')
@@ -806,6 +816,7 @@ def run(model, runner, user_arguments)
     end
 
     register_logs(runner, resstock_arguments_runner)
+    register_logs(runner, new_runner)
 
     return true
   end

measures/ResStockArguments/README.md

@@ -6,7 +6,7 @@
 ## Description
 Measure that pre-processes the arguments passed to the BuildResidentialHPXML and BuildResidentialScheduleFile measures.
 
-Passes in all arguments from the options lookup, processes them, and then registers values to the runner to be used by other measures.
+Passes in all ResStockArguments arguments from the options lookup, processes them, and then registers values to the runner to be used by other measures.
 
 ## Arguments
 

measures/ResStockArguments/measure.rb

@@ -21,7 +21,7 @@ def description
 
   # human readable description of modeling approach
   def modeler_description
-    return 'Passes in all arguments from the options lookup, processes them, and then registers values to the runner to be used by other measures.'
+    return 'Passes in all ResStockArguments arguments from the options lookup, processes them, and then registers values to the runner to be used by other measures.'
   end
 
   # define the arguments that the user will input

measures/ResStockArgumentsPostHPXML/measure.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+# see the URL below for information on how to write OpenStudio measures
+# http://nrel.github.io/OpenStudio-user-documentation/reference/measure_writing_guide/
+
+require_relative 'resources/hvac_flexibility/detailed_schedule_generator'
+require_relative 'resources/hvac_flexibility/setpoint_modifier'
+
+# start the measure
+class ResStockArgumentsPostHPXML < OpenStudio::Measure::ModelMeasure
+  # human readable name
+  def name
+    # Measure name should be the title case of the class name.
+    return 'ResStock Arguments Post-HPXML'
+  end
+
+  # human readable description
+  def description
+    return 'Measure that post-processes the output of the BuildResidentialHPXML and BuildResidentialScheduleFile measures.'
+  end
+
+  # human readable description of modeling approach
+  def modeler_description
+    return 'Passes in all ResStockArgumentsPostHPXML arguments from the options lookup, processes them, and then modifies output of other measures.'
+  end
+
+  # define the arguments that the user will input
+  def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
+    args = OpenStudio::Measure::OSArgumentVector.new
+
+    arg = OpenStudio::Measure::OSArgument.makeStringArgument('hpxml_path', false)
+    arg.setDisplayName('HPXML File Path')
+    arg.setDescription('Absolute/relative path of the HPXML file.')
+    args << arg
+
+    # Add args for flexibility inputs. Use hours format for the duration and minutes for the random offset. Offsets are degree F.
+    arg = OpenStudio::Measure::OSArgument.makeDoubleArgument('loadflex_peak_duration_hours', false)
+    arg.setDisplayName('Load Flexibility: Peak Duration (hours)')
+    arg.setDescription('Duration of the peak period in hours.')
+    arg.setDefaultValue(0)
+    args << arg
+
+    arg = OpenStudio::Measure::OSArgument.makeIntegerArgument('loadflex_peak_offset', false)
+    arg.setDisplayName('Load Flexibility: Peak Offset (deg F)')
+    arg.setDescription('Offset of the peak period in degrees Fahrenheit.')
+    arg.setDefaultValue(0)
+    args << arg
+
+    arg = OpenStudio::Measure::OSArgument.makeDoubleArgument('loadflex_pre_peak_duration_hours', false)
+    arg.setDisplayName('Load Flexibility: Pre-Peak Duration (hours)')
+    arg.setDescription('Duration of the pre-peak period in hours.')
+    arg.setDefaultValue(0)
+    args << arg
+
+    arg = OpenStudio::Measure::OSArgument.makeIntegerArgument('loadflex_pre_peak_offset', false)
+    arg.setDisplayName('Load Flexibility: Pre-Peak Offset (deg F)')
+    arg.setDescription('Offset of the pre-peak period in degrees Fahrenheit.')
+    arg.setDefaultValue(0)
+    args << arg
+
+    arg = OpenStudio::Measure::OSArgument.makeIntegerArgument('loadflex_random_shift_minutes', false)
+    arg.setDisplayName('Load Flexibility: Random Shift (minutes)')
+    arg.setDescription('Number of minutes to randomly shift the peak period. If minutes less than timestep, will be assumed to be 0.')
+    arg.setDefaultValue(0)
+    args << arg
+
+    arg = OpenStudio::Measure::OSArgument::makeStringArgument('output_csv_path', false)
+    arg.setDisplayName('Schedules: Output CSV Path')
+    arg.setDescription('Absolute/relative path of the csv file containing user-specified occupancy schedules. Relative paths are relative to the HPXML output path.')
+    args << arg
+
+    arg = OpenStudio::Measure::OSArgument.makeIntegerArgument('building_id', false)
+    arg.setDisplayName('Building Unit ID')
+    arg.setDescription('The building unit number (between 1 and the number of samples).')
+    args << arg
+
+    return args
+  end
+
+  # define what happens when the measure is run
+  def run(model, runner, user_arguments)
+    super(model, runner, user_arguments)
+
+    # use the built-in error checking
+    if !runner.validateUserArguments(arguments(model), user_arguments)
+      return false
+    end
+
+    # assign the user inputs to variables
+    args = runner.getArgumentValues(arguments(model), user_arguments)
+    if skip_load_flexibility?(args)
+      runner.registerInfo('Skipping ResStockArgumentsPostHPXML since load flexibility inputs are 0.')
+      return true
+    end
+
+    hpxml_path = args[:hpxml_path]
+    unless (Pathname.new hpxml_path).absolute?
+      hpxml_path = File.expand_path(File.join(File.dirname(__FILE__), hpxml_path))
+    end
+    unless File.exist?(hpxml_path) && hpxml_path.downcase.end_with?('.xml')
+      fail "'#{hpxml_path}' does not exist or is not an .xml file."
+    end
+
+    hpxml = HPXML.new(hpxml_path: hpxml_path)
+
+    # Parse the HPXML document
+    doc = XMLHelper.parse_file(hpxml_path)
+    hpxml_doc = XMLHelper.get_element(doc, '/HPXML')
+    doc_buildings = XMLHelper.get_elements(hpxml_doc, 'Building')
+
+    # Process each building
+    doc_buildings.each_with_index do |building, index|
+      schedule = create_schedule(hpxml, hpxml_path, runner, index)
+      modified_schedule = modify_schedule(hpxml, index, args, runner, schedule)
+      schedules_filepath = write_schedule(modified_schedule, args[:output_csv_path], index)
+      update_hpxml_schedule_filepath(building, schedules_filepath)
+    end
+
+    # Write out the modified hpxml
+    XMLHelper.write_file(doc, hpxml_path)
+    runner.registerInfo("Wrote file: #{hpxml_path} with modified schedules.")
+    true
+  end
+
+  def skip_load_flexibility?(args)
+    args[:loadflex_peak_duration_hours] == 0 && args[:loadflex_pre_peak_duration_hours] == 0
+  end
+
+  def create_schedule(hpxml, hpxml_path, runner, building_index)
+    generator = HVACScheduleGenerator.new(hpxml, hpxml_path, runner, building_index)
+    generator.get_heating_cooling_setpoint_schedule
+  end
+
+  def modify_schedule(hpxml, building_index, args, runner, schedule)
+    minutes_per_step = hpxml.header.timestep
+    hpxml_bldg = hpxml.buildings[building_index]
+    building_id = (args[:building_id] or 0).to_i
+    state = hpxml_bldg.state_code
+    sim_year = hpxml.header.sim_calendar_year
+    epw_path = Location.get_epw_path(hpxml_bldg, args[:hpxml_path])
+    weather = WeatherFile.new(epw_path: epw_path, runner: runner, hpxml: hpxml)
+    schedule_modifier = HVACScheduleModifier.new(state: state,
+                                                sim_year: sim_year,
+                                                weather: weather,
+                                                epw_path: epw_path,
+                                                minutes_per_step: minutes_per_step,
+                                                runner: runner)
+    flexibility_inputs = get_flexibility_inputs(args, minutes_per_step, building_id)
+    schedule_modifier.modify_setpoints(schedule, flexibility_inputs)
+  end
+
+  def get_flexibility_inputs(args, minutes_per_step, building_id)
+    srand(building_id)
+    max_random_shift_steps = (args[:loadflex_random_shift_minutes] / minutes_per_step).to_i
+    random_shift_steps = rand(-max_random_shift_steps..max_random_shift_steps)
+    FlexibilityInputs.new(
+      peak_duration_steps: (args[:loadflex_peak_duration_hours] * 60 / minutes_per_step).to_i,
+      peak_offset: args[:loadflex_peak_offset],
+      pre_peak_duration_steps: (args[:loadflex_pre_peak_duration_hours] * 60 / minutes_per_step).to_i,
+      pre_peak_offset: args[:loadflex_pre_peak_offset],
+      random_shift_steps: random_shift_steps
+    )
+  end
+
+  def write_schedule(schedule, output_csv_path, building_index)
+    schedules_filepath = File.join(File.dirname(output_csv_path), "detailed_schedules_#{building_index + 1}.csv")
+    CSV.open(schedules_filepath, 'w') do |csv|
+      csv << schedule.keys
+      schedule.values.transpose.each do |row|
+        csv << row.map { |x| '%.3g' % x }
+      end
+    end
+    return schedules_filepath
+  end
+
+  def update_hpxml_schedule_filepath(building, new_schedule_filepath)
+    building_extension = XMLHelper.create_elements_as_needed(building, ['BuildingDetails', 'BuildingSummary', 'extension'])
+    existing_schedules_filepaths = XMLHelper.get_values(building_extension, 'SchedulesFilePath', :string)
+    XMLHelper.add_element(building_extension, 'SchedulesFilePath', new_schedule_filepath, :string) unless existing_schedules_filepaths.include?(new_schedule_filepath)
+  end
+end
+
+# register the measure to be used by the application
+ResStockArgumentsPostHPXML.new.registerWithApplication

measures/ResStockArgumentsPostHPXML/measure.xml

@@ -0,0 +1,56 @@
+<?xml version="1.0"?>
+<measure>
+  <schema_version>3.0</schema_version>
+  <name>res_stock_arguments_post_hpxml</name>
+  <uid>db102ce5-ac96-4ef9-90d3-abbe53478716</uid>
+  <version_id>e9a3773b-66b5-48a6-95e5-4ce42262a640</version_id>
+  <version_modified>20221103T232039Z</version_modified>
+  <xml_checksum>2C38F48B</xml_checksum>
+  <class_name>ResStockArgumentsPostHPXML</class_name>
+  <display_name>ResStock Arguments Post-HPXML</display_name>
+  <description>Measure that post-processes the output of the BuildResidentialHPXML and BuildResidentialScheduleFile measures.</description>
+  <modeler_description>Passes in all ResStockArgumentsPostHPXML arguments from the options lookup, processes them, and then modifies output of other measures.</modeler_description>
+  <arguments>
+    <argument>
+      <name>hpxml_path</name>
+      <display_name>HPXML File Path</display_name>
+      <description>Absolute/relative path of the HPXML file.</description>
+      <type>String</type>
+      <required>false</required>
+      <model_dependent>false</model_dependent>
+    </argument>
+    <argument>
+      <name>output_csv_path</name>
+      <display_name>Schedules: Output CSV Path</display_name>
+      <description>Absolute/relative path of the csv file containing user-specified occupancy schedules. Relative paths are relative to the HPXML output path.</description>
+      <type>String</type>
+      <required>false</required>
+      <model_dependent>false</model_dependent>
+    </argument>
+  </arguments>
+  <outputs />
+  <provenances />
+  <tags>
+    <tag>Whole Building.Space Types</tag>
+  </tags>
+  <attributes>
+    <attribute>
+      <name>Measure Type</name>
+      <value>ModelMeasure</value>
+      <datatype>string</datatype>
+    </attribute>
+  </attributes>
+  <files>
+    <file>
+      <version>
+        <software_program>OpenStudio</software_program>
+        <identifier>3.3.0</identifier>
+        <min_compatible>3.3.0</min_compatible>
+      </version>
+      <filename>measure.rb</filename>
+      <filetype>rb</filetype>
+      <usage_type>script</usage_type>
+      <checksum>5A9AF6DF</checksum>
+    </file>
+  </files>
+</measure>