diff --git a/docs/scenario_workflow_translation_plan.md b/docs/scenario_workflow_translation_plan.md index d0caa1e..9857e0e 100644 --- a/docs/scenario_workflow_translation_plan.md +++ b/docs/scenario_workflow_translation_plan.md @@ -230,16 +230,16 @@ Use this roadmap as the tracker. Keep `Status` and `Delivered by` current when a ### PR 11: Scenario OSW Writer API -- Status: In Progress -- Delivered by: `scenario-workflow-11-12-scenario-osw-writer` branch, combined with PR 12 +- Status: Done +- Delivered by: PR #20, merged into `scenario-workflow`, combined with PR 12 - Scope: Add an API that writes baseline plus scenario OSWs for package scenarios with at least one mapped measure. - Done when: Generation tests show expected directories and skipped-scenario reporting. - Avoid: Writing OSWs for zero-mapped scenarios or changing baseline output. ### PR 12: Scenario Workflow Step Assembly -- Status: In Progress -- Delivered by: `scenario-workflow-11-12-scenario-osw-writer` branch, combined with PR 11 +- Status: Done +- Delivered by: PR #20, merged into `scenario-workflow`, combined with PR 11 - Scope: Deep-copy baseline OSW and append mapped retrofit steps in a practical OpenStudio construction order, not BuildingSync `MeasureID` order. Make sure `buildingsync-measures-gem` measures are on the OSW `measure_paths`; `develop` already provides `config/external_measure_repos.yml` for this. - Ordering: Keep the order data-driven. For example, give each mapping step a `workflow_phase` in `scenario_measure_map.json` (envelope, then internal loads, then HVAC equipment, then controls and operations) and stable-sort mapped steps by phase, breaking ties by reference order. OpenStudio already runs model measures before EnergyPlus and reporting measures, so phases only order model measures. - Done when: OSW tests assert baseline steps plus expected mapped measure steps and arguments, and every mapped `measure_dir_name` resolves from the OSW `measure_paths`. A multi-measure package listed out of phase order produces phase-ordered steps. A test covers the LED mapping, whose `SetLightingLoadsByLPD` step also exists in the baseline, and proves the baseline step's arguments are unchanged. @@ -247,8 +247,8 @@ Use this roadmap as the tracker. Keep `Status` and `Delivered by` current when a ### PR 13: Generic OSW Step Helpers -- Status: Planned -- Delivered by: - +- Status: In Progress +- Delivered by: `scenario-workflow-13-generic-osw-step-helpers` branch - Scope: Centralize mapped step appending and `OpenStudio::Extension.set_measure_argument` use. - Done when: Tests prove boolean, numeric, and string arguments serialize correctly. - Avoid: Broad rewrites of baseline populator methods or unintended baseline JSON changes. @@ -431,8 +431,8 @@ Use this section for stable facts future PRs need. Keep entries short and tied t ### PR 11 + PR 12: Scenario OSW Writer And Step Assembly -- Status: In Progress -- Delivered by: `scenario-workflow-11-12-scenario-osw-writer` branch. Combined because the writer cannot be tested meaningfully without step assembly. +- Status: Done +- Delivered by: PR #20, merged into `scenario-workflow`. Combined because the writer cannot be tested meaningfully without step assembly. - Handoff: `BOSS::Boss.write_baseline_and_scenario_osws(xml_file_path, output_dir, epw_file_path, standard_to_be_used)` builds one reader, one baseline OSW, one mapper, and one `{ building_type:, hvac_system_type: }` context per file. It writes `baseline/in.osw` and `scenarios//in.osw`, and returns `{ baseline_osw_path:, scenario_results:, parser_warnings: }`. Each scenario result has `scenario_id`, `scenario_name`, `report_id`, `package_id`, `status` (`:written` or `:skipped`), `osw_path` (`nil` when skipped), `skipped_measure_ids`, and `warnings`. Parser warnings are also logged. `write_baseline_osw`, `run_baseline_osw`, and the CLI are unchanged. - Handoff: Scenario IDs become directory names. IDs must match `\A[A-Za-z0-9](?:[A-Za-z0-9_.-]{0,62}[A-Za-z0-9_-])?\z` and must not be a Windows reserved device name. Otherwise the scenario is skipped with `:missing_scenario_output_id` or `:unsafe_scenario_output_id`. IDs that match case-insensitively skip every scenario in the group with `:conflicting_scenario_output_id`. Because allowed IDs are ASCII, no Unicode normalization is needed. Skipped-ID scenarios are not mapped. - Handoff: `scenario_measure_map.json` has a top-level `workflow_phases` array (`envelope`, `internal_loads`, `hvac_equipment`, `controls_operations`), and each step has a `workflow_phase`. The mapper validates that the phases are unique and non-blank and that every step uses a declared phase. It keeps `workflow_phase` on returned steps and exposes `#workflow_phases`. Maps without `workflow_phases` are still accepted, but their steps must not carry a phase. Plug-load controls are `controls_operations` and refrigeration replacement is `internal_loads`, even though both use `ReduceElectricEquipmentLoadsByPercentage`. @@ -445,6 +445,17 @@ Use this section for stable facts future PRs need. Keep entries short and tied t - Not run: Scenario simulations. These are PR 14/PR 18 scope. - Follow-up: PR 13 can reuse the private `build_scenario_osw` / `order_scenario_steps` helpers instead of adding new appending logic. PR 14 should run only OSWs with `status: :written`. +### PR 13: Generic OSW Step Helpers + +- Status: In Progress +- Delivered by: `scenario-workflow-13-generic-osw-step-helpers` branch +- Handoff: `OSWArgPopulator.append_step(osw, step, before_measure: nil)` deep-copies a complete step, adds an empty `arguments` hash if missing, and inserts it before the first `before_measure` step (or appends). It returns the inserted step and never adds `name` or default arguments. +- Handoff: `OSWArgPopulator.set_step_argument(step, name, value)` is the only `OpenStudio::Extension.set_measure_argument` call site. It passes a one-step workflow, so other steps with the same `measure_dir_name` (baseline `SetLightingLoadsByLPD`, repeated `ReduceElectricEquipmentLoadsByPercentage`) are untouched. Keys are symbolized by the extension; values are not coerced. +- Handoff: The eight baseline populators only swap their append/lambda setup for `step_argument_setter`; calculations, defaults, logging, and argument order are unchanged. `build_scenario_osw` appends prebuilt mapped steps through `append_step`; mapped arguments still do not go through the setter. +- Verification: `C:\Ruby32-x64\bin\ruby.exe -S bundle exec rspec spec/tests/unit spec/tests/integration/scenario_osw_generation_spec.rb` - 136 examples, 0 failures. Baseline step characterizations in `boss_spec.rb` are unchanged. +- Verification: `bundle exec rubocop` on the changed lib files drops from 156 to 100 offenses; none are new. +- Not run: Baseline simulations (`write_and_run_osws_spec.rb`); generated baseline JSON is pinned by unit specs. + ## Verification Commands Use the narrowest command that proves the current PR. Broaden only when the change justifies it. diff --git a/lib/BOSS/boss.rb b/lib/BOSS/boss.rb index 92550f3..c5c2e60 100644 --- a/lib/BOSS/boss.rb +++ b/lib/BOSS/boss.rb @@ -255,9 +255,9 @@ def order_scenario_steps(steps, workflow_phases) # Mapped steps go before the trailing openstudio_results reporting step. def build_scenario_osw(baseline_osw, mapped_steps, measure_paths, file_paths) scenario_osw = Marshal.load(Marshal.dump(baseline_osw)) - steps = scenario_osw[:steps] - insert_at = steps.index { |step| step[:measure_dir_name] == 'openstudio_results' } || steps.length - steps.insert(insert_at, *mapped_steps) + mapped_steps.each do |step| + OSWArgPopulator.append_step(scenario_osw, step, before_measure: 'openstudio_results') + end scenario_osw[:measure_paths] = measure_paths.dup scenario_osw[:file_paths] = file_paths.dup scenario_osw diff --git a/lib/BOSS/osw_arg_populator.rb b/lib/BOSS/osw_arg_populator.rb index 46ac09b..b8057bd 100644 --- a/lib/BOSS/osw_arg_populator.rb +++ b/lib/BOSS/osw_arg_populator.rb @@ -8,10 +8,32 @@ require 'BOSS/boss_logger' class OSWArgPopulator + # Inserts a deep copy of step before the first before_measure step, or appends it. + # Returns the inserted step. + def self.append_step(osw, step, before_measure: nil) + new_step = Marshal.load(Marshal.dump(step)) + new_step[:arguments] ||= {} + steps = osw[:steps] + index = before_measure && steps.index { |existing| existing[:measure_dir_name] == before_measure } + steps.insert(index || steps.length, new_step) + new_step + end + + # Sets one argument on this step only. set_measure_argument updates every step with the + # same measure_dir_name, so it is given a one-step workflow. + def self.set_step_argument(step, name, value) + OpenStudio::Extension.set_measure_argument({ steps: [step] }, step[:measure_dir_name], name, value) + step + end + + def self.step_argument_setter(osw, measure_dir_name) + step = append_step(osw, { measure_dir_name:, arguments: {} }) + ->(key, value) { set_step_argument(step, key, value) } + end + def self.populate_set_run_period_args(osw, bsync_reader) BOSS.BOSS_logger.info("+++++++++++++++++++++++++++ populating measure set_run_period +++++++++++++++++++++++") - osw[:steps].append({"measure_dir_name": "set_run_period", "arguments": {}}) - set_measure_argument = lambda {| key, value | OpenStudio::Extension.set_measure_argument(osw, "set_run_period", key, value) } + set_measure_argument = step_argument_setter(osw, "set_run_period") # Add args # - __SKIP__ @@ -35,8 +57,7 @@ def self.populate_set_run_period_args(osw, bsync_reader) def self.populate_change_building_location_args(osw, bsync_reader) BOSS.BOSS_logger.info("+++++++++++++++++++++ populating measure ChangeBuildingLocation +++++++++++++++++++++") - osw[:steps].append({"measure_dir_name": "ChangeBuildingLocation", "arguments": {}}) - set_measure_argument = lambda {| key, value | OpenStudio::Extension.set_measure_argument(osw, "ChangeBuildingLocation", key, value) } + set_measure_argument = step_argument_setter(osw, "ChangeBuildingLocation") # - __SKIP__ set_measure_argument.call("__SKIP__", false) @@ -57,8 +78,7 @@ def self.populate_change_building_location_args(osw, bsync_reader) def self.populate_create_bar_from_building_type_ratios_args(osw, bsync_reader) BOSS.BOSS_logger.info("++++ populating measure create_bar_from_building_type_ratios ++++++++++++++") - osw[:steps].append({"measure_dir_name": "create_bar_from_building_type_ratios", "arguments": {}}) - set_measure_argument = lambda {| key, value | OpenStudio::Extension.set_measure_argument(osw, "create_bar_from_building_type_ratios", key, value) } + set_measure_argument = step_argument_setter(osw, "create_bar_from_building_type_ratios") @@ -127,8 +147,7 @@ def self.populate_create_bar_from_building_type_ratios_args(osw, bsync_reader) def self.populate_create_typical_building_from_model_args(osw, bsync_reader) BOSS.BOSS_logger.info("+++++ populating measure create_typical_building_from_model +++++++++++++++") - osw[:steps].append({"measure_dir_name": "create_typical_building_from_model", "arguments": {}}) - set_measure_argument = lambda {| key, value | OpenStudio::Extension.set_measure_argument(osw, "create_typical_building_from_model", key, value) } + set_measure_argument = step_argument_setter(osw, "create_typical_building_from_model") # Add args # - __SKIP__ @@ -187,8 +206,7 @@ def self.populate_create_typical_building_from_model_args(osw, bsync_reader) def self.populate_set_lighting_loads_by_LPD_args(osw, bsync_reader) BOSS.BOSS_logger.info("++++++++++++++++++++++ populating measure SetLightingLoadsByLPD ++++++++++++++++++++") - osw[:steps].append({"measure_dir_name": "SetLightingLoadsByLPD", "arguments": {}}) - set_measure_argument = lambda {| key, value | OpenStudio::Extension.set_measure_argument(osw, "SetLightingLoadsByLPD", key, value) } + set_measure_argument = step_argument_setter(osw, "SetLightingLoadsByLPD") # skip if no total_installed_power or no usable floor area BOSS.BOSS_logger.info("|\t- gathering measure requirements...") @@ -229,8 +247,7 @@ def self.populate_set_lighting_loads_by_LPD_args(osw, bsync_reader) def self.populate_set_electric_equipment_loads_by_epd_args(osw, bsync_reader) BOSS.BOSS_logger.info("+++++ populating measure set_electric_equipment_loads_by_epd ++++++++++++++") - osw[:steps].append({"measure_dir_name": "set_electric_equipment_loads_by_epd", "arguments": {}}) - set_measure_argument = lambda {| key, value | OpenStudio::Extension.set_measure_argument(osw, "set_electric_equipment_loads_by_epd", key, value) } + set_measure_argument = step_argument_setter(osw, "set_electric_equipment_loads_by_epd") # skip if no total_weighted_average_load or no usable floor area BOSS.BOSS_logger.info("|\t- gathering measure requirements...") @@ -269,8 +286,7 @@ def self.populate_set_electric_equipment_loads_by_epd_args(osw, bsync_reader) end def self.populate_replace_baseline_windows_args(osw, bsync_reader) - osw[:steps].append({"measure_dir_name": "replace_baseline_windows", "arguments": {}}) - set_measure_argument = lambda {| key, value | OpenStudio::Extension.set_measure_argument(osw, "replace_baseline_windows", key, value) } + set_measure_argument = step_argument_setter(osw, "replace_baseline_windows") # skip if no window_data window_data = bsync_reader.get_window_data @@ -292,8 +308,7 @@ def self.populate_replace_baseline_windows_args(osw, bsync_reader) def self.populate_openstudio_results_args(osw, bsync_reader) BOSS.BOSS_logger.info("+++++++++++++++++++++++++ populating measure openstudio_results +++++++++++++++++++++") - osw[:steps].append({"measure_dir_name": "openstudio_results", "arguments": {}}) - set_measure_argument = lambda {| key, value | OpenStudio::Extension.set_measure_argument(osw, "openstudio_results", key, value) } + set_measure_argument = step_argument_setter(osw, "openstudio_results") # Add args # - __SKIP__ diff --git a/spec/tests/unit/boss_spec.rb b/spec/tests/unit/boss_spec.rb index 221d768..72141a7 100644 --- a/spec/tests/unit/boss_spec.rb +++ b/spec/tests/unit/boss_spec.rb @@ -479,6 +479,40 @@ def read_osw(path) end end + describe '.build_scenario_osw' do + let(:baseline_osw) do + { + steps: [ + { measure_dir_name: 'SetLightingLoadsByLPD', arguments: { __SKIP__: false, lpd: 1.0 } }, + { measure_dir_name: 'openstudio_results', arguments: { __SKIP__: false, reg_monthly_details: true } } + ], + measure_paths: ['/baseline/measures'], file_paths: ['/baseline/files'] + } + end + let(:mapped_steps) do + [ + { measure_dir_name: 'ReduceElectricEquipmentLoadsByPercentage', arguments: { __SKIP__: false, elecequip_power_reduction_percent: 20.0 } }, + { measure_dir_name: 'ReduceElectricEquipmentLoadsByPercentage', arguments: { __SKIP__: false, elecequip_power_reduction_percent: 5.0 } }, + { measure_dir_name: 'SetLightingLoadsByLPD', arguments: { __SKIP__: false, lpd: 0.6 } } + ] + end + + it 'inserts repeated and baseline-named measures without sharing or overwriting arguments' do + baseline_before = Marshal.load(Marshal.dump(baseline_osw)) + mapped_before = Marshal.load(Marshal.dump(mapped_steps)) + + first = described_class.send(:build_scenario_osw, baseline_osw, mapped_steps, ['/s/measures'], ['/s/files']) + second = described_class.send(:build_scenario_osw, baseline_osw, mapped_steps, ['/s/measures'], ['/s/files']) + first[:steps][1][:arguments][:elecequip_power_reduction_percent] = 99.0 + + expect(second[:steps]).to eq [baseline_before[:steps].first, *mapped_before, baseline_before[:steps].last] + expect(first[:steps][2]).to eq mapped_before[1] + expect(baseline_osw).to eq baseline_before + expect(mapped_steps).to eq mapped_before + expect(second.values_at(:measure_paths, :file_paths)).to eq [['/s/measures'], ['/s/files']] + end + end + describe '.scenario_output_id_warnings' do before { allow(BOSS.BOSS_logger).to receive(:warn) } diff --git a/spec/tests/unit/osw_arg_populator_spec.rb b/spec/tests/unit/osw_arg_populator_spec.rb new file mode 100644 index 0000000..2205bc5 --- /dev/null +++ b/spec/tests/unit/osw_arg_populator_spec.rb @@ -0,0 +1,93 @@ +# ******************************************************************************* +# OpenStudio(R), Copyright (c) Alliance for Energy Innovation, LLC. +# BuildingSync(R), Copyright (c) Alliance for Energy Innovation, LLC. +# See also https://github.com/BuildingSync/BOSS/blob/develop/LICENSE.md +# ******************************************************************************* + +require 'json' +require 'BOSS/osw_arg_populator' + +RSpec.describe OSWArgPopulator do + def round_trip(osw) + JSON.parse(JSON.pretty_generate(osw), symbolize_names: true) + end + + def results_step + { measure_dir_name: 'openstudio_results', arguments: { __SKIP__: false } } + end + + describe '.set_step_argument' do + it 'serializes boolean, numeric, and string arguments without coercion' do + osw = { steps: [] } + step = described_class.append_step(osw, { measure_dir_name: 'm', arguments: {} }) + { + 'on' => true, 'off' => false, 'zero' => 0, 'count' => 4, 'ratio' => 0.6, + 'text' => 'Inferred', 'empty' => '', 'numeric_text' => '4', 'boolean_text' => 'false' + }.each { |name, value| described_class.set_step_argument(step, name, value) } + + arguments = round_trip(osw)[:steps].first[:arguments] + expect(arguments).to eq( + on: true, off: false, zero: 0, count: 4, ratio: 0.6, + text: 'Inferred', empty: '', numeric_text: '4', boolean_text: 'false' + ) + expect(arguments[:count]).to be_an Integer + expect(arguments[:ratio]).to be_a Float + end + + it 'updates only the given step when other steps share its measure_dir_name' do + osw = { steps: [] } + baseline = described_class.append_step(osw, { measure_dir_name: 'SetLightingLoadsByLPD', arguments: { lpd: 1.0 } }) + first = described_class.append_step(osw, { measure_dir_name: 'SetLightingLoadsByLPD', arguments: { lpd: 0.6 } }) + described_class.append_step(osw, { measure_dir_name: 'SetLightingLoadsByLPD', arguments: { lpd: 0.5 } }) + + described_class.set_step_argument(first, 'lpd', 0.4) + described_class.set_step_argument(baseline, '__SKIP__', false) + + expect(osw[:steps].map { |step| step[:arguments] }).to eq [ + { lpd: 1.0, __SKIP__: false }, { lpd: 0.4 }, { lpd: 0.5 } + ] + expect(osw[:steps].map { |step| step.key?(:name) }).to all(be false) + end + end + + describe '.append_step' do + it 'appends at the end by default and keeps prepopulated argument types' do + osw = { steps: [results_step] } + described_class.append_step(osw, { measure_dir_name: 'm', arguments: { flag: true, n: 2, x: 1.5, s: '0.50' } }) + + steps = round_trip(osw)[:steps] + expect(steps.map { |step| step[:measure_dir_name] }).to eq ['openstudio_results', 'm'] + expect(steps.last[:arguments]).to eq(flag: true, n: 2, x: 1.5, s: '0.50') + end + + it 'inserts before the named measure in call order, or appends when it is absent' do + osw = { steps: [{ measure_dir_name: 'a', arguments: {} }, results_step] } + described_class.append_step(osw, { measure_dir_name: 'b', arguments: {} }, before_measure: 'openstudio_results') + described_class.append_step(osw, { measure_dir_name: 'c', arguments: {} }, before_measure: 'openstudio_results') + described_class.append_step(osw, { measure_dir_name: 'd', arguments: {} }, before_measure: 'missing') + + expect(osw[:steps].map { |step| step[:measure_dir_name] }).to eq ['a', 'b', 'c', 'openstudio_results', 'd'] + end + + it 'adds an arguments hash when the step has none' do + osw = { steps: [] } + expect(described_class.append_step(osw, { measure_dir_name: 'm' })).to eq(measure_dir_name: 'm', arguments: {}) + end + + it 'stores independent copies of the source step' do + source = { measure_dir_name: 'm', arguments: { s: 'value' } } + osw = { steps: [] } + first = described_class.append_step(osw, source) + second = described_class.append_step(osw, source) + + first[:arguments][:s] << '-changed' + described_class.set_step_argument(second, 'n', 1) + + expect(source).to eq(measure_dir_name: 'm', arguments: { s: 'value' }) + expect(osw[:steps]).to eq [ + { measure_dir_name: 'm', arguments: { s: 'value-changed' } }, + { measure_dir_name: 'm', arguments: { s: 'value', n: 1 } } + ] + end + end +end