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
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ jobs:
uses: actions/checkout@v4
with:
repository: BuildingSync/buildingsync-measures-gem
ref: c7efd329ae30b345d238de5c4dcddeceb8ba0298
ref: 30cdd344db06a8708b79946b1a8b904fe9c3d6c4
path: buildingsync-measures-gem
- name: Setup
run: |
Expand Down
12 changes: 9 additions & 3 deletions docs/scenario_workflow_translation_plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -290,16 +290,22 @@ 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

- 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.
- 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 `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

Expand All @@ -315,7 +321,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.

Expand Down
130 changes: 130 additions & 0 deletions lib/BOSS/hvac_target_binder.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
# 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'

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. 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

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
# @param zone_names [Array<String>, 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:, 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?
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: 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<Hash>] BuildingSync premises ({ type:, id: }) the change applies to
# @param object_names [Array<String>, 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)
scope = zone_names ? { zone_scope: 'explicit_zone_names', zone_names_json: JSON.generate(zone_names.uniq) } : { zone_scope: 'all_model_zones' }
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
Loading
Loading