From abc7c64755fd8dab9897aea21a5166333984b891 Mon Sep 17 00:00:00 2001 From: JieXiong9119 <69597597+JieXiong9119@users.noreply.github.com> Date: Thu, 12 Nov 2026 15:01:11 -0700 Subject: [PATCH 1/4] add target binder work with the companion added measure in bs-measure-gem --- docs/scenario_workflow_translation_plan.md | 5 +- lib/BOSS/hvac_target_binder.rb | 60 +++++++++++++++++ spec/tests/unit/hvac_target_binder_spec.rb | 78 ++++++++++++++++++++++ 3 files changed, 142 insertions(+), 1 deletion(-) create mode 100644 lib/BOSS/hvac_target_binder.rb create mode 100644 spec/tests/unit/hvac_target_binder_spec.rb diff --git a/docs/scenario_workflow_translation_plan.md b/docs/scenario_workflow_translation_plan.md index 16eb229..9e24bed 100644 --- a/docs/scenario_workflow_translation_plan.md +++ b/docs/scenario_workflow_translation_plan.md @@ -294,12 +294,15 @@ Use this roadmap as the tracker. Keep `Status` and `Delivered by` current when a ### PR 14C: Model Target Binding -- Status: Planned +- Status: In progress - Delivered by: - - Depends on: PR 14B. - Scope: Bind selected BuildingSync premises to the actual OpenStudio zone and equipment names the topology and modifier measures need. OSWs are written before the model exists, so this step must prove how names are resolved at run time. A new runtime measure belongs in `buildingsync-measures-gem`, not BOSS. - Done when: A model-based test proves exact zone/object binding, full shared-system scope for `replace`, and self-contained scenario OSWs. - Avoid: Placeholder or guessed names, blank `target_zone_names` defaults, or making scenarios wait on baseline runs. +- Findings: BOSS baseline zones come from `create_bar_from_building_type_ratios` and carry no BuildingSync IDs, and no v2.7.0 fixture links premises on HVAC deliveries. A probe workflow showed that a measure cannot change a later OSW step's arguments at run time. +- Decision: bind whole-building premises only (`Building`, `Site`, `Facility`). `BOSS::HvacTargetBinder` (`lib/BOSS/hvac_target_binder.rb`) emits an `apply_hvac_topology_to_zone_scope` step with `zone_scope = all_model_zones`; zone, space, and section links return `missing_input`. The new upstream measure resolves every model zone by exact name at run time and runs the selected topology measure, so `replace` always gets the full zone list and scenario OSWs do not depend on a baseline run. Its Minitest suite (`apply_hvac_topology_to_zone_scope_test.rb`) covers create, full-scope replace of a shared air loop, topology safety checks, and an empty model. +- Remaining: commit and merge `apply_hvac_topology_to_zone_scope` upstream, then bump the CI checkout ref in `.github/workflows/ci.yml` (still `c7efd32`). Modifier object binding (`modify_existing_*`) waits for PR 14E. Quantity-versus-zone-count guards cannot run for whole-building scope before the model exists. ### PR 14D: Baseline HVAC Integration diff --git a/lib/BOSS/hvac_target_binder.rb b/lib/BOSS/hvac_target_binder.rb new file mode 100644 index 0000000..96298c0 --- /dev/null +++ b/lib/BOSS/hvac_target_binder.rb @@ -0,0 +1,60 @@ +# frozen_string_literal: true + +# ******************************************************************************* +# 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 +# ******************************************************************************* + +module BOSS + # Binds a matched HvacTopologySelector result to model zones. + # + # BOSS baseline geometry is generated (create_bar_from_building_type_ratios), so model zones + # have no BuildingSync IDs. Only whole-building premises can be bound; they resolve to every + # model zone at run time through buildingsync-measures-gem apply_hvac_topology_to_zone_scope. + # Zone, space, and section links return :missing_input. + class HvacTargetBinder + BINDING_MEASURE = 'apply_hvac_topology_to_zone_scope' + WHOLE_BUILDING_PREMISES = ['Building', 'Site', 'Facility'].freeze + STANDARDS_TEMPLATES = ['90.1-2013', '90.1-2016', '90.1-2019'].freeze + OPERATIONS = ['create', 'replace'].freeze + + Binding = Struct.new(:status, :step, :messages, keyword_init: true) + + # @param result [HvacTopologySelector::Result] + # @param operation [String] 'create' or 'replace' + # @param standards_template [String] one of STANDARDS_TEMPLATES + # @return [Binding] status :bound with an OSW step spec, or the reason it cannot bind + def bind(result, operation:, standards_template:) + raise ArgumentError, "Unsupported operation '#{operation}'" if !OPERATIONS.include?(operation) + if !STANDARDS_TEMPLATES.include?(standards_template) + raise ArgumentError, "Unsupported standards_template '#{standards_template}'" + end + return Binding.new(status: result.status, step: nil, messages: result.messages) if result.status != :match + + unbound = result.premises.reject { |premise| WHOLE_BUILDING_PREMISES.include?(premise[:type]) } + if result.premises.empty? || !unbound.empty? + refs = unbound.map { |premise| "#{premise[:type]} #{premise[:id]}" } + return Binding.new( + status: :missing_input, step: nil, + messages: ["#{result.configuration} links #{refs.empty? ? 'no premises' : refs.join(', ')}; " \ + 'only whole-building premises can be bound to generated baseline zones.'] + ) + end + + Binding.new( + status: :bound, + step: { + measure_dir_name: BINDING_MEASURE, + arguments: { + topology_measure: result.measure, + operation: operation, + zone_scope: 'all_model_zones', + standards_template: standards_template + } + }, + messages: [] + ) + end + end +end diff --git a/spec/tests/unit/hvac_target_binder_spec.rb b/spec/tests/unit/hvac_target_binder_spec.rb new file mode 100644 index 0000000..109eb2e --- /dev/null +++ b/spec/tests/unit/hvac_target_binder_spec.rb @@ -0,0 +1,78 @@ +# frozen_string_literal: true + +# ******************************************************************************* +# 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/constants' +require 'BOSS/external_measure_repo_manager' +require 'BOSS/hvac_topology_selector' +require 'BOSS/hvac_target_binder' + +RSpec.describe BOSS::HvacTargetBinder do + def match_result(premises, measure: 'hvac_ptac') + BOSS::HvacTopologySelector::Result.new( + status: :match, configuration: 'Packaged Terminal Air Conditioner', measure: measure, + hvac_system_id: 'HVAC-1', record_ids: ['D-1'], premises: premises, group_key: [:delivery, 'D-1'], messages: [] + ) + end + + let(:binder) { described_class.new } + + ['Building', 'Site', 'Facility'].each do |type| + it "binds #{type} premises to all model zones through the runtime binding measure" do + binding = binder.bind(match_result([{ type: type, id: "#{type}-1" }]), + operation: 'replace', standards_template: '90.1-2016') + expect(binding.status).to eq(:bound) + expect(binding.step).to eq( + measure_dir_name: 'apply_hvac_topology_to_zone_scope', + arguments: { topology_measure: 'hvac_ptac', operation: 'replace', zone_scope: 'all_model_zones', + standards_template: '90.1-2016' } + ) + end + end + + it 'returns missing input for zone or space premises instead of guessing names' do + premises = [{ type: 'Building', id: 'B-1' }, { type: 'ThermalZone', id: 'TZ-1' }] + binding = binder.bind(match_result(premises), operation: 'create', standards_template: '90.1-2019') + expect(binding.status).to eq(:missing_input) + expect(binding.step).to be_nil + expect(binding.messages.first).to include('ThermalZone TZ-1') + end + + it 'returns missing input when no premises are linked' do + binding = binder.bind(match_result([]), operation: 'create', standards_template: '90.1-2019') + expect(binding.status).to eq(:missing_input) + end + + it 'passes non-match selector results through unchanged' do + result = match_result([{ type: 'Building', id: 'B-1' }]).dup + result.status = :mapping_gap + result.messages = ['gap'] + binding = binder.bind(result, operation: 'create', standards_template: '90.1-2019') + expect(binding).to have_attributes(status: :mapping_gap, step: nil, messages: ['gap']) + end + + it 'rejects templates and operations the topology measures do not support' do + result = match_result([{ type: 'Building', id: 'B-1' }]) + expect { binder.bind(result, operation: 'create', standards_template: 'DOE Ref Pre-1980') } + .to raise_error(ArgumentError, /standards_template/) + expect { binder.bind(result, operation: 'delete', standards_template: '90.1-2019') } + .to raise_error(ArgumentError, /operation/) + end + + it 'matches the binding measure arguments in the configured measure source' do + dirs = BOSS::ExternalMeasureRepoManager.new.resolved_measure_directories(include_scenario_only: true) + xml_path = dirs.map { |dir| File.join(dir, described_class::BINDING_MEASURE, 'measure.xml') }.find { |p| File.file?(p) } + skip 'apply_hvac_topology_to_zone_scope is not in the configured measure source' if xml_path.nil? + + doc = REXML::Document.new(File.read(xml_path)) + names = doc.get_elements('measure/arguments/argument/name').map(&:text) + expect(names).to eq(['topology_measure', 'operation', 'zone_scope', 'standards_template']) + topologies = doc.get_elements("measure/arguments/argument[name='topology_measure']/choices/choice/value").map(&:text) + expect(topologies).to include('hvac_ptac', 'hvac_doas', 'hvac_vav_hw_reheat') + end +end From 67e7d4f7d0a39ab7b134db6f248357150df7a2f2 Mon Sep 17 00:00:00 2001 From: JieXiong9119 <69597597+JieXiong9119@users.noreply.github.com> Date: Thu, 12 Nov 2026 16:53:58 -0700 Subject: [PATCH 2/4] update target binder to accept target zones --- .github/workflows/ci.yml | 2 +- docs/scenario_workflow_translation_plan.md | 3 +- lib/BOSS/hvac_target_binder.rb | 40 +++++++++++++--------- spec/tests/unit/hvac_target_binder_spec.rb | 23 ++++++++++++- 4 files changed, 48 insertions(+), 20 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 356f64c..76c34ec 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -29,7 +29,7 @@ jobs: uses: actions/checkout@v4 with: repository: BuildingSync/buildingsync-measures-gem - ref: c7efd329ae30b345d238de5c4dcddeceb8ba0298 + ref: bdf14e8e11e9859eb437faa5cd3d15cf18b57ba8 path: buildingsync-measures-gem - name: Setup run: | diff --git a/docs/scenario_workflow_translation_plan.md b/docs/scenario_workflow_translation_plan.md index 9e24bed..5ac647f 100644 --- a/docs/scenario_workflow_translation_plan.md +++ b/docs/scenario_workflow_translation_plan.md @@ -302,7 +302,8 @@ Use this roadmap as the tracker. Keep `Status` and `Delivered by` current when a - Avoid: Placeholder or guessed names, blank `target_zone_names` defaults, or making scenarios wait on baseline runs. - Findings: BOSS baseline zones come from `create_bar_from_building_type_ratios` and carry no BuildingSync IDs, and no v2.7.0 fixture links premises on HVAC deliveries. A probe workflow showed that a measure cannot change a later OSW step's arguments at run time. - Decision: bind whole-building premises only (`Building`, `Site`, `Facility`). `BOSS::HvacTargetBinder` (`lib/BOSS/hvac_target_binder.rb`) emits an `apply_hvac_topology_to_zone_scope` step with `zone_scope = all_model_zones`; zone, space, and section links return `missing_input`. The new upstream measure resolves every model zone by exact name at run time and runs the selected topology measure, so `replace` always gets the full zone list and scenario OSWs do not depend on a baseline run. Its Minitest suite (`apply_hvac_topology_to_zone_scope_test.rb`) covers create, full-scope replace of a shared air loop, topology safety checks, and an empty model. -- Remaining: commit and merge `apply_hvac_topology_to_zone_scope` upstream, then bump the CI checkout ref in `.github/workflows/ci.yml` (still `c7efd32`). Modifier object binding (`modify_existing_*`) waits for PR 14E. Quantity-versus-zone-count guards cannot run for whole-building scope before the model exists. +- Remaining: merge `apply_hvac_topology_to_zone_scope` upstream; CI now pins the branch commit `bdf14e8`, which must be replaced with the merged commit. Modifier object binding (`modify_existing_*`) waits for PR 14E. Quantity-versus-zone-count guards cannot run for whole-building scope before the model exists. +- Explicit zone scope: upstream `apply_hvac_topology_to_zone_scope` now also takes `zone_scope = explicit_zone_names` with `zone_names_json` (a JSON array, so names may contain commas), and topology measures accept JSON `target_zone_names`. `HvacTargetBinder#bind` takes optional `zone_names:` and then emits that scope for any premises. No BOSS caller passes zone names yet: generated baseline zone names are not known when the OSW is written. ### PR 14D: Baseline HVAC Integration diff --git a/lib/BOSS/hvac_target_binder.rb b/lib/BOSS/hvac_target_binder.rb index 96298c0..9d661b0 100644 --- a/lib/BOSS/hvac_target_binder.rb +++ b/lib/BOSS/hvac_target_binder.rb @@ -6,13 +6,15 @@ # See also https://github.com/BuildingSync/BOSS/blob/develop/LICENSE.md # ******************************************************************************* +require 'json' + module BOSS # Binds a matched HvacTopologySelector result to model zones. # # BOSS baseline geometry is generated (create_bar_from_building_type_ratios), so model zones - # have no BuildingSync IDs. Only whole-building premises can be bound; they resolve to every - # model zone at run time through buildingsync-measures-gem apply_hvac_topology_to_zone_scope. - # Zone, space, and section links return :missing_input. + # have no BuildingSync IDs. Whole-building premises resolve to every model zone at run time + # through buildingsync-measures-gem apply_hvac_topology_to_zone_scope. Other premises bind only + # when the caller passes the exact model zone names; otherwise they return :missing_input. class HvacTargetBinder BINDING_MEASURE = 'apply_hvac_topology_to_zone_scope' WHOLE_BUILDING_PREMISES = ['Building', 'Site', 'Facility'].freeze @@ -24,13 +26,19 @@ class HvacTargetBinder # @param result [HvacTopologySelector::Result] # @param operation [String] 'create' or 'replace' # @param standards_template [String] one of STANDARDS_TEMPLATES + # @param zone_names [Array, nil] exact model zone names for the result's premises; + # when given, the step uses zone_scope explicit_zone_names instead of all_model_zones # @return [Binding] status :bound with an OSW step spec, or the reason it cannot bind - def bind(result, operation:, standards_template:) + def bind(result, operation:, standards_template:, zone_names: nil) raise ArgumentError, "Unsupported operation '#{operation}'" if !OPERATIONS.include?(operation) if !STANDARDS_TEMPLATES.include?(standards_template) raise ArgumentError, "Unsupported standards_template '#{standards_template}'" end + if !zone_names.nil? && (zone_names.empty? || !zone_names.all? { |name| name.is_a?(String) && !name.strip.empty? }) + raise ArgumentError, 'zone_names must be a non-empty array of non-empty strings' + end return Binding.new(status: result.status, step: nil, messages: result.messages) if result.status != :match + return Binding.new(status: :bound, step: step(result, operation, standards_template, zone_names), messages: []) if zone_names unbound = result.premises.reject { |premise| WHOLE_BUILDING_PREMISES.include?(premise[:type]) } if result.premises.empty? || !unbound.empty? @@ -42,19 +50,17 @@ def bind(result, operation:, standards_template:) ) end - Binding.new( - status: :bound, - step: { - measure_dir_name: BINDING_MEASURE, - arguments: { - topology_measure: result.measure, - operation: operation, - zone_scope: 'all_model_zones', - standards_template: standards_template - } - }, - messages: [] - ) + Binding.new(status: :bound, step: step(result, operation, standards_template, nil), messages: []) + end + + private + + def step(result, operation, standards_template, zone_names) + scope = zone_names ? { zone_scope: 'explicit_zone_names', zone_names_json: JSON.generate(zone_names.uniq) } : { zone_scope: 'all_model_zones' } + { + measure_dir_name: BINDING_MEASURE, + arguments: { topology_measure: result.measure, operation: operation, **scope, standards_template: standards_template } + } end end end diff --git a/spec/tests/unit/hvac_target_binder_spec.rb b/spec/tests/unit/hvac_target_binder_spec.rb index 109eb2e..969cb09 100644 --- a/spec/tests/unit/hvac_target_binder_spec.rb +++ b/spec/tests/unit/hvac_target_binder_spec.rb @@ -43,6 +43,25 @@ def match_result(premises, measure: 'hvac_ptac') expect(binding.messages.first).to include('ThermalZone TZ-1') end + it 'binds any premises to explicit zone names as a JSON array' do + premises = [{ type: 'ThermalZone', id: 'TZ-1' }] + binding = binder.bind(match_result(premises), operation: 'replace', standards_template: '90.1-2019', + zone_names: ['Office, East', 'Core', 'Core']) + expect(binding.status).to eq(:bound) + expect(binding.step[:arguments]).to eq( + topology_measure: 'hvac_ptac', operation: 'replace', zone_scope: 'explicit_zone_names', + zone_names_json: '["Office, East","Core"]', standards_template: '90.1-2019' + ) + end + + it 'rejects empty or blank explicit zone names' do + result = match_result([{ type: 'Building', id: 'B-1' }]) + [[], [''], [nil]].each do |names| + expect { binder.bind(result, operation: 'create', standards_template: '90.1-2019', zone_names: names) } + .to raise_error(ArgumentError, /zone_names/) + end + end + it 'returns missing input when no premises are linked' do binding = binder.bind(match_result([]), operation: 'create', standards_template: '90.1-2019') expect(binding.status).to eq(:missing_input) @@ -71,7 +90,9 @@ def match_result(premises, measure: 'hvac_ptac') doc = REXML::Document.new(File.read(xml_path)) names = doc.get_elements('measure/arguments/argument/name').map(&:text) - expect(names).to eq(['topology_measure', 'operation', 'zone_scope', 'standards_template']) + expect(names).to eq(['topology_measure', 'operation', 'zone_scope', 'zone_names_json', 'standards_template']) + scopes = doc.get_elements("measure/arguments/argument[name='zone_scope']/choices/choice/value").map(&:text) + expect(scopes).to eq(['all_model_zones', 'explicit_zone_names']) topologies = doc.get_elements("measure/arguments/argument[name='topology_measure']/choices/choice/value").map(&:text) expect(topologies).to include('hvac_ptac', 'hvac_doas', 'hvac_vav_hw_reheat') end From be0f3c63133209645a557acd3f49e9dffc13fe43 Mon Sep 17 00:00:00 2001 From: JieXiong9119 <69597597+JieXiong9119@users.noreply.github.com> Date: Thu, 12 Nov 2026 23:38:36 -0700 Subject: [PATCH 3/4] add binder for modifier measures --- docs/scenario_workflow_translation_plan.md | 5 +- lib/BOSS/hvac_target_binder.rb | 64 ++++++++++++++++++ spec/tests/unit/hvac_target_binder_spec.rb | 76 ++++++++++++++++++++++ 3 files changed, 143 insertions(+), 2 deletions(-) diff --git a/docs/scenario_workflow_translation_plan.md b/docs/scenario_workflow_translation_plan.md index 5ac647f..ad548eb 100644 --- a/docs/scenario_workflow_translation_plan.md +++ b/docs/scenario_workflow_translation_plan.md @@ -302,7 +302,8 @@ Use this roadmap as the tracker. Keep `Status` and `Delivered by` current when a - Avoid: Placeholder or guessed names, blank `target_zone_names` defaults, or making scenarios wait on baseline runs. - Findings: BOSS baseline zones come from `create_bar_from_building_type_ratios` and carry no BuildingSync IDs, and no v2.7.0 fixture links premises on HVAC deliveries. A probe workflow showed that a measure cannot change a later OSW step's arguments at run time. - Decision: bind whole-building premises only (`Building`, `Site`, `Facility`). `BOSS::HvacTargetBinder` (`lib/BOSS/hvac_target_binder.rb`) emits an `apply_hvac_topology_to_zone_scope` step with `zone_scope = all_model_zones`; zone, space, and section links return `missing_input`. The new upstream measure resolves every model zone by exact name at run time and runs the selected topology measure, so `replace` always gets the full zone list and scenario OSWs do not depend on a baseline run. Its Minitest suite (`apply_hvac_topology_to_zone_scope_test.rb`) covers create, full-scope replace of a shared air loop, topology safety checks, and an empty model. -- Remaining: merge `apply_hvac_topology_to_zone_scope` upstream; CI now pins the branch commit `bdf14e8`, which must be replaced with the merged commit. Modifier object binding (`modify_existing_*`) waits for PR 14E. Quantity-versus-zone-count guards cannot run for whole-building scope before the model exists. +- Modifier object binding: upstream `apply_hvac_modifier_to_object_scope` runs one `modify_existing_*` measure on object names resolved at run time. `object_scope = all_matching_objects` takes every object the modifier and setting can change (efficiency metric picks the coil or VRF type, `boiler_*`/`chiller_*` property picks boilers or chillers, `plant_loop_type` picks Heating/Cooling/Condenser loops); `explicit_object_names` takes `object_names_json`. Other modifier arguments pass as `modifier_arguments_json`. It fails when nothing matches and rejects names containing commas, because the modifiers split target names on commas. `HvacTargetBinder#bind_modifier` emits this step: whole-building premises give `all_matching_objects`, explicit `object_names:` give `explicit_object_names`, other premises and plant-loop changes without a loop type return `missing_input`. +- Remaining: CI pins the unmerged gem branch commit `bdf14e8`; bump it to the commit that adds `apply_hvac_modifier_to_object_scope`. The upstream merge moves to the end of PR 14E. Quantity-versus-zone-count guards cannot run for whole-building scope before the model exists. - Explicit zone scope: upstream `apply_hvac_topology_to_zone_scope` now also takes `zone_scope = explicit_zone_names` with `zone_names_json` (a JSON array, so names may contain commas), and topology measures accept JSON `target_zone_names`. `HvacTargetBinder#bind` takes optional `zone_names:` and then emits that scope for any premises. No BOSS caller passes zone names yet: generated baseline zone names are not known when the OSW is written. ### PR 14D: Baseline HVAC Integration @@ -319,7 +320,7 @@ Use this roadmap as the tracker. Keep `Status` and `Delivered by` current when a - Status: Planned - Delivered by: - - Depends on: PR 14D. -- Scope: Map HVAC retrofit measures to topology `replace` steps or `modify_existing_*` steps through the PR 9 result contract. Order conditioning, then DOAS/ventilation, then modifiers. Keep existing economizer, DCV, and thermostat mappings from other gems. +- Scope: Map HVAC retrofit measures onto the steps `HvacTargetBinder` already produces (`bind` for topology `replace`, `bind_modifier` for `modify_existing_*`) through the PR 9 result contract. No new binding work belongs here. Order conditioning, then DOAS/ventilation, then modifiers. Keep existing economizer, DCV, and thermostat mappings from other gems. - Done when: One topology replacement and one modifier case run end to end, partial shared-system replacement is rejected, and mixed-source packages still write and run. - Avoid: Mapping "Replace boiler" or "Replace burner" to an efficiency edit, guessing values, or partial HVAC graphs. diff --git a/lib/BOSS/hvac_target_binder.rb b/lib/BOSS/hvac_target_binder.rb index 9d661b0..bd1cab7 100644 --- a/lib/BOSS/hvac_target_binder.rb +++ b/lib/BOSS/hvac_target_binder.rb @@ -15,8 +15,20 @@ module BOSS # have no BuildingSync IDs. Whole-building premises resolve to every model zone at run time # through buildingsync-measures-gem apply_hvac_topology_to_zone_scope. Other premises bind only # when the caller passes the exact model zone names; otherwise they return :missing_input. + # bind_modifier does the same for modify_existing_* measures through + # apply_hvac_modifier_to_object_scope, which resolves model object names at run time. class HvacTargetBinder BINDING_MEASURE = 'apply_hvac_topology_to_zone_scope' + MODIFIER_BINDING_MEASURE = 'apply_hvac_modifier_to_object_scope' + # Modifier measure => its target-names argument, which the binding measure fills. + MODIFIER_TARGETS = { + 'modify_existing_air_loop_controls' => 'target_air_loop_names', + 'modify_existing_heat_recovery' => 'target_heat_exchanger_names', + 'modify_existing_hvac_equipment_efficiencies' => 'target_object_names', + 'modify_existing_plant_equipment' => 'target_plant_equipment_names', + 'modify_existing_plant_loop_temperatures' => 'target_plant_loop_names' + }.freeze + PLANT_LOOP_TYPES = ['Heating', 'Cooling', 'Condenser'].freeze WHOLE_BUILDING_PREMISES = ['Building', 'Site', 'Facility'].freeze STANDARDS_TEMPLATES = ['90.1-2013', '90.1-2016', '90.1-2019'].freeze OPERATIONS = ['create', 'replace'].freeze @@ -53,6 +65,58 @@ def bind(result, operation:, standards_template:, zone_names: nil) Binding.new(status: :bound, step: step(result, operation, standards_template, nil), messages: []) end + # @param modifier_measure [String] one of MODIFIER_TARGETS keys + # @param modifier_arguments [Hash] the modifier's arguments other than its target-names argument + # @param premises [Array] BuildingSync premises ({ type:, id: }) the change applies to + # @param object_names [Array, nil] exact model object names; when given, the step uses + # object_scope explicit_object_names instead of all_matching_objects + # @param plant_loop_type [String, nil] Heating, Cooling, or Condenser; required for + # modify_existing_plant_loop_temperatures without object_names + # @return [Binding] status :bound with an OSW step spec, or :missing_input + def bind_modifier(modifier_measure:, modifier_arguments:, premises:, object_names: nil, plant_loop_type: nil) + target_key = MODIFIER_TARGETS[modifier_measure] + raise ArgumentError, "Unsupported modifier_measure '#{modifier_measure}'" if target_key.nil? + raise ArgumentError, 'modifier_arguments must be a Hash' if !modifier_arguments.is_a?(Hash) + if modifier_arguments.key?(target_key) || modifier_arguments.key?(target_key.to_sym) + raise ArgumentError, "modifier_arguments must not set #{target_key}" + end + if !plant_loop_type.nil? && !PLANT_LOOP_TYPES.include?(plant_loop_type) + raise ArgumentError, "Unsupported plant_loop_type '#{plant_loop_type}'" + end + if !object_names.nil? && (object_names.empty? || !object_names.all? { |name| name.is_a?(String) && !name.strip.empty? }) + raise ArgumentError, 'object_names must be a non-empty array of non-empty strings' + end + + if object_names.nil? + unbound = premises.reject { |premise| WHOLE_BUILDING_PREMISES.include?(premise[:type]) } + if premises.empty? || !unbound.empty? + refs = unbound.map { |premise| "#{premise[:type]} #{premise[:id]}" } + return Binding.new( + status: :missing_input, step: nil, + messages: ["#{modifier_measure} links #{refs.empty? ? 'no premises' : refs.join(', ')}; " \ + 'only whole-building premises can be bound to generated baseline objects.'] + ) + end + if modifier_measure == 'modify_existing_plant_loop_temperatures' && plant_loop_type.nil? + return Binding.new(status: :missing_input, step: nil, + messages: ["#{modifier_measure} needs a plant_loop_type to bind to all matching loops."]) + end + end + + scope = if object_names + { object_scope: 'explicit_object_names', object_names_json: JSON.generate(object_names.uniq) } + else + { object_scope: 'all_matching_objects' } + end + scope[:plant_loop_type] = plant_loop_type if plant_loop_type + step = { + measure_dir_name: MODIFIER_BINDING_MEASURE, + arguments: { modifier_measure: modifier_measure, **scope, + modifier_arguments_json: JSON.generate(modifier_arguments) } + } + Binding.new(status: :bound, step: step, messages: []) + end + private def step(result, operation, standards_template, zone_names) diff --git a/spec/tests/unit/hvac_target_binder_spec.rb b/spec/tests/unit/hvac_target_binder_spec.rb index 969cb09..22689f5 100644 --- a/spec/tests/unit/hvac_target_binder_spec.rb +++ b/spec/tests/unit/hvac_target_binder_spec.rb @@ -96,4 +96,80 @@ def match_result(premises, measure: 'hvac_ptac') topologies = doc.get_elements("measure/arguments/argument[name='topology_measure']/choices/choice/value").map(&:text) expect(topologies).to include('hvac_ptac', 'hvac_doas', 'hvac_vav_hw_reheat') end + + describe '#bind_modifier' do + let(:efficiency) { { efficiency_metric: 'dx_cooling_cop', efficiency_value: 4.0 } } + + it 'binds whole-building premises to all matching objects' do + binding = binder.bind_modifier(modifier_measure: 'modify_existing_hvac_equipment_efficiencies', + modifier_arguments: efficiency, premises: [{ type: 'Building', id: 'B-1' }]) + expect(binding.status).to eq(:bound) + expect(binding.step).to eq( + measure_dir_name: 'apply_hvac_modifier_to_object_scope', + arguments: { modifier_measure: 'modify_existing_hvac_equipment_efficiencies', object_scope: 'all_matching_objects', + modifier_arguments_json: '{"efficiency_metric":"dx_cooling_cop","efficiency_value":4.0}' } + ) + end + + it 'binds any premises to explicit object names' do + binding = binder.bind_modifier(modifier_measure: 'modify_existing_heat_recovery', + modifier_arguments: { effectiveness: 0.7 }, + premises: [{ type: 'ThermalZone', id: 'TZ-1' }], object_names: ['ERV 1', 'ERV 1']) + expect(binding.step[:arguments]).to include(object_scope: 'explicit_object_names', object_names_json: '["ERV 1"]') + end + + it 'returns missing input for non-whole-building premises or unscoped plant loops' do + zone = binder.bind_modifier(modifier_measure: 'modify_existing_heat_recovery', modifier_arguments: {}, + premises: [{ type: 'ThermalZone', id: 'TZ-1' }]) + expect(zone.status).to eq(:missing_input) + expect(zone.messages.first).to include('ThermalZone TZ-1') + loops = binder.bind_modifier(modifier_measure: 'modify_existing_plant_loop_temperatures', + modifier_arguments: { design_loop_exit_temperature_c: 60.0 }, + premises: [{ type: 'Building', id: 'B-1' }]) + expect(loops.status).to eq(:missing_input) + heating = binder.bind_modifier(modifier_measure: 'modify_existing_plant_loop_temperatures', + modifier_arguments: { design_loop_exit_temperature_c: 60.0 }, + premises: [{ type: 'Building', id: 'B-1' }], plant_loop_type: 'Heating') + expect(heating.step[:arguments]).to include(object_scope: 'all_matching_objects', plant_loop_type: 'Heating') + end + + it 'rejects unsupported modifiers, target-name arguments, and bad inputs' do + building = [{ type: 'Building', id: 'B-1' }] + expect { binder.bind_modifier(modifier_measure: 'hvac_ptac', modifier_arguments: {}, premises: building) } + .to raise_error(ArgumentError, /modifier_measure/) + expect do + binder.bind_modifier(modifier_measure: 'modify_existing_heat_recovery', + modifier_arguments: { 'target_heat_exchanger_names' => 'X' }, premises: building) + end.to raise_error(ArgumentError, /target_heat_exchanger_names/) + expect do + binder.bind_modifier(modifier_measure: 'modify_existing_heat_recovery', modifier_arguments: {}, + premises: building, object_names: ['']) + end.to raise_error(ArgumentError, /object_names/) + expect do + binder.bind_modifier(modifier_measure: 'modify_existing_plant_loop_temperatures', modifier_arguments: {}, + premises: building, plant_loop_type: 'Steam') + end.to raise_error(ArgumentError, /plant_loop_type/) + end + + it 'matches the modifier binding measure arguments in the configured measure source' do + dirs = BOSS::ExternalMeasureRepoManager.new.resolved_measure_directories(include_scenario_only: true) + xml_path = dirs.map { |dir| File.join(dir, described_class::MODIFIER_BINDING_MEASURE, 'measure.xml') } + .find { |p| File.file?(p) } + skip 'apply_hvac_modifier_to_object_scope is not in the configured measure source' if xml_path.nil? + + doc = REXML::Document.new(File.read(xml_path)) + names = doc.get_elements('measure/arguments/argument/name').map(&:text) + expect(names).to eq(['modifier_measure', 'object_scope', 'object_names_json', 'plant_loop_type', 'modifier_arguments_json']) + choices = ->(arg) { doc.get_elements("measure/arguments/argument[name='#{arg}']/choices/choice/value").map(&:text) } + expect(choices.call('modifier_measure')).to match_array(described_class::MODIFIER_TARGETS.keys) + expect(choices.call('object_scope')).to eq(['all_matching_objects', 'explicit_object_names']) + expect(choices.call('plant_loop_type')).to include(*described_class::PLANT_LOOP_TYPES) + + described_class::MODIFIER_TARGETS.each do |modifier, target_key| + modifier_xml = File.join(File.dirname(xml_path, 2), modifier, 'measure.xml') + modifier_args = REXML::Document.new(File.read(modifier_xml)).get_elements('measure/arguments/argument/name').map(&:text) + expect(modifier_args).to include(target_key) + end + end + end end From f7c5ec009af86c3f0dc8f448ed8fbb6be7dee975 Mon Sep 17 00:00:00 2001 From: JieXiong9119 <69597597+JieXiong9119@users.noreply.github.com> Date: Fri, 13 Nov 2026 11:28:03 -0700 Subject: [PATCH 4/4] update binder for gas backup --- .github/workflows/ci.yml | 2 +- docs/scenario_workflow_translation_plan.md | 5 +++-- lib/BOSS/hvac_target_binder.rb | 8 ++++---- spec/tests/unit/hvac_target_binder_spec.rb | 10 +++++++++- 4 files changed, 17 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 76c34ec..7c139b8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -29,7 +29,7 @@ jobs: uses: actions/checkout@v4 with: repository: BuildingSync/buildingsync-measures-gem - ref: bdf14e8e11e9859eb437faa5cd3d15cf18b57ba8 + ref: 30cdd344db06a8708b79946b1a8b904fe9c3d6c4 path: buildingsync-measures-gem - name: Setup run: | diff --git a/docs/scenario_workflow_translation_plan.md b/docs/scenario_workflow_translation_plan.md index ad548eb..d11dda3 100644 --- a/docs/scenario_workflow_translation_plan.md +++ b/docs/scenario_workflow_translation_plan.md @@ -290,7 +290,7 @@ Use this roadmap as the tracker. Keep `Status` and `Delivered by` current when a - Integrated outdoor air: an `OtherHVACSystem` with `Integration` `Integrated with central air distribution` or `Integrated with local air distribution` describes outdoor air through the linked deliveries' own air system. It does not consume those deliveries and returns the new status `integrated`; ERV, exhaust, and other not-mappable equipment still return `not_mappable`. Whether the planner may ignore `integrated` records is a PR 14D decision. - Upstream guide rules adopted (buildingsync-measures-gem `e1b2f33`): Packaged Rooftop AC and Warm Air Furnace require a gas, air-medium `Furnace` and accept `FurnaceType` `Warm air`, `Other`, or absent. Packaged Rooftop Heat Pump accepts `HeatPumpBackupSystemFuel` `Electricity` or `Natural gas` and returns it in `Result#measure_arguments` as `supplemental_heating_fuel` (`Electricity`/`NaturalGas`). An empty `FanBasedDistributionType` counts as absent. `CS/Quantity` is a guard on the VAV and VRF rows. From `5e775a6`: packaged and terminal DX rows read an omitted `DX/CondenserPlantIDs` as air-cooled (VRF still requires it). - L200 fixtures: `example-smalloffice-level2.xml` and `Reference-PrimarySchool-L200-Audit.xml` (copied from `../schema/docs/notebooks/bsync_examples/`) carry full Delivery/source/plant records. The L200 school now matches one Packaged Rooftop VAV with Hot Water Reheat and three Packaged Rooftop AC deliveries; VAV pods 2, 3, and other still return `conflicting_input` because they reference the `Boiler` plant defined in `VAV-Pod1` (resolving plants across `HVACSystem` records is open BOSS selector work). `example-smalloffice-level2.xml` now matches five Packaged Rooftop Heat Pump deliveries with `supplemental_heating_fuel` `NaturalGas`. -- Follow-up for PR 14C: `apply_hvac_topology_to_zone_scope` forwards only `operation`, `target_zone_names`, and `standards_template`. The binder and wrapper must forward `Result#measure_arguments` (for example `supplemental_heating_fuel`) before gas-backup heat pumps can run. +- Follow-up for PR 14C (done in PR 14C): the binder and wrapper forward `Result#measure_arguments` (for example `supplemental_heating_fuel`). ### PR 14C: Model Target Binding @@ -303,8 +303,9 @@ Use this roadmap as the tracker. Keep `Status` and `Delivered by` current when a - Findings: BOSS baseline zones come from `create_bar_from_building_type_ratios` and carry no BuildingSync IDs, and no v2.7.0 fixture links premises on HVAC deliveries. A probe workflow showed that a measure cannot change a later OSW step's arguments at run time. - Decision: bind whole-building premises only (`Building`, `Site`, `Facility`). `BOSS::HvacTargetBinder` (`lib/BOSS/hvac_target_binder.rb`) emits an `apply_hvac_topology_to_zone_scope` step with `zone_scope = all_model_zones`; zone, space, and section links return `missing_input`. The new upstream measure resolves every model zone by exact name at run time and runs the selected topology measure, so `replace` always gets the full zone list and scenario OSWs do not depend on a baseline run. Its Minitest suite (`apply_hvac_topology_to_zone_scope_test.rb`) covers create, full-scope replace of a shared air loop, topology safety checks, and an empty model. - Modifier object binding: upstream `apply_hvac_modifier_to_object_scope` runs one `modify_existing_*` measure on object names resolved at run time. `object_scope = all_matching_objects` takes every object the modifier and setting can change (efficiency metric picks the coil or VRF type, `boiler_*`/`chiller_*` property picks boilers or chillers, `plant_loop_type` picks Heating/Cooling/Condenser loops); `explicit_object_names` takes `object_names_json`. Other modifier arguments pass as `modifier_arguments_json`. It fails when nothing matches and rejects names containing commas, because the modifiers split target names on commas. `HvacTargetBinder#bind_modifier` emits this step: whole-building premises give `all_matching_objects`, explicit `object_names:` give `explicit_object_names`, other premises and plant-loop changes without a loop type return `missing_input`. -- Remaining: CI pins the unmerged gem branch commit `bdf14e8`; bump it to the commit that adds `apply_hvac_modifier_to_object_scope`. The upstream merge moves to the end of PR 14E. Quantity-versus-zone-count guards cannot run for whole-building scope before the model exists. +- Remaining: CI pins the unmerged gem branch commit `30cdd34`, which adds `apply_hvac_modifier_to_object_scope` and `topology_arguments_json`. The upstream merge moves to the end of PR 14E. Quantity-versus-zone-count guards cannot run for whole-building scope before the model exists. - Explicit zone scope: upstream `apply_hvac_topology_to_zone_scope` now also takes `zone_scope = explicit_zone_names` with `zone_names_json` (a JSON array, so names may contain commas), and topology measures accept JSON `target_zone_names`. `HvacTargetBinder#bind` takes optional `zone_names:` and then emits that scope for any premises. No BOSS caller passes zone names yet: generated baseline zone names are not known when the OSW is written. +- Data-derived topology arguments: upstream `apply_hvac_topology_to_zone_scope` takes an optional `topology_arguments_json` (a JSON object of string values) and passes it to the topology measure. It rejects keys the wrapper sets itself (`operation`, `target_zone_names`, `standards_template`) and arguments the topology measure does not define. `HvacTargetBinder#bind` writes non-empty `Result#measure_arguments` there, so a gas-backup packaged heat pump gets `{"supplemental_heating_fuel":"NaturalGas"}`. The CI pin must move to the gem commit that adds this argument. ### PR 14D: Baseline HVAC Integration diff --git a/lib/BOSS/hvac_target_binder.rb b/lib/BOSS/hvac_target_binder.rb index bd1cab7..75f77d6 100644 --- a/lib/BOSS/hvac_target_binder.rb +++ b/lib/BOSS/hvac_target_binder.rb @@ -121,10 +121,10 @@ def bind_modifier(modifier_measure:, modifier_arguments:, premises:, object_name def step(result, operation, standards_template, zone_names) scope = zone_names ? { zone_scope: 'explicit_zone_names', zone_names_json: JSON.generate(zone_names.uniq) } : { zone_scope: 'all_model_zones' } - { - measure_dir_name: BINDING_MEASURE, - arguments: { topology_measure: result.measure, operation: operation, **scope, standards_template: standards_template } - } + arguments = { topology_measure: result.measure, operation: operation, **scope, standards_template: standards_template } + extra = result.measure_arguments || {} + arguments[:topology_arguments_json] = JSON.generate(extra) if !extra.empty? + { measure_dir_name: BINDING_MEASURE, arguments: arguments } end end end diff --git a/spec/tests/unit/hvac_target_binder_spec.rb b/spec/tests/unit/hvac_target_binder_spec.rb index 22689f5..3c618e0 100644 --- a/spec/tests/unit/hvac_target_binder_spec.rb +++ b/spec/tests/unit/hvac_target_binder_spec.rb @@ -62,6 +62,13 @@ def match_result(premises, measure: 'hvac_ptac') end end + it 'forwards selector measure arguments as topology_arguments_json' do + result = match_result([{ type: 'Building', id: 'B-1' }], measure: 'hvac_packaged_rooftop_heat_pump') + result.measure_arguments = { 'supplemental_heating_fuel' => 'NaturalGas' } + binding = binder.bind(result, operation: 'create', standards_template: '90.1-2019') + expect(binding.step[:arguments][:topology_arguments_json]).to eq('{"supplemental_heating_fuel":"NaturalGas"}') + end + it 'returns missing input when no premises are linked' do binding = binder.bind(match_result([]), operation: 'create', standards_template: '90.1-2019') expect(binding.status).to eq(:missing_input) @@ -90,7 +97,8 @@ def match_result(premises, measure: 'hvac_ptac') doc = REXML::Document.new(File.read(xml_path)) names = doc.get_elements('measure/arguments/argument/name').map(&:text) - expect(names).to eq(['topology_measure', 'operation', 'zone_scope', 'zone_names_json', 'standards_template']) + expect(names).to eq(['topology_measure', 'operation', 'zone_scope', 'zone_names_json', 'standards_template', + 'topology_arguments_json']) scopes = doc.get_elements("measure/arguments/argument[name='zone_scope']/choices/choice/value").map(&:text) expect(scopes).to eq(['all_model_zones', 'explicit_zone_names']) topologies = doc.get_elements("measure/arguments/argument[name='topology_measure']/choices/choice/value").map(&:text)