Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 19 additions & 8 deletions docs/scenario_workflow_translation_plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -230,25 +230,25 @@ 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.
- Avoid: Mutating the baseline OSW, omitting baseline creation steps, nondeterministic step order, or hardcoding phase order in Ruby per measure.

### 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.
Expand Down Expand Up @@ -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/<scenario_id>/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`.
Expand All @@ -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.
Expand Down
6 changes: 3 additions & 3 deletions lib/BOSS/boss.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
47 changes: 31 additions & 16 deletions lib/BOSS/osw_arg_populator.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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__
Expand All @@ -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)
Expand All @@ -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")



Expand Down Expand Up @@ -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__
Expand Down Expand Up @@ -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...")
Expand Down Expand Up @@ -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...")
Expand Down Expand Up @@ -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
Expand All @@ -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__
Expand Down
34 changes: 34 additions & 0 deletions spec/tests/unit/boss_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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) }

Expand Down
93 changes: 93 additions & 0 deletions spec/tests/unit/osw_arg_populator_spec.rb
Original file line number Diff line number Diff line change
@@ -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
Loading