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: 30cdd344db06a8708b79946b1a8b904fe9c3d6c4
ref: 789bd50ec0ba42559f85e5cac23fcbbf8f9bdfbe
path: buildingsync-measures-gem
- name: Setup
run: |
Expand Down
19 changes: 15 additions & 4 deletions docs/scenario_workflow_translation_plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,9 +116,9 @@ Measure source order for new mappings:

`buildingsync-measures-gem` is not released as a gem. BOSS loads it from a local sibling checkout (`../buildingsync-measures-gem`) configured in `config/external_measure_repos.yml`. Other sources keep their current install path.

HVAC mappings follow the upstream [HVAC Mapping and Migration Guide](https://github.com/BuildingSync/buildingsync-measures-gem/blob/develop/docs/HVAC_MAPPING_AND_MIGRATION.md): 17 topology measures (`operation` create/replace, comma-separated `target_zone_names`, `standards_template` 90.1-2013/2016/2019) plus 5 `modify_existing_*` modifiers that take exact OpenStudio object names. Do not map to the deprecated `modify_hvac`. A principal HVAC label alone is family evidence, not an exact match. Do not invent model object or zone names from BuildingSync IDs.
HVAC mappings follow the upstream [HVAC Mapping and Migration Guide](https://github.com/BuildingSync/buildingsync-measures-gem/blob/develop/docs/HVAC_MAPPING_AND_MIGRATION.md): 17 topology measures (`operation` create/replace, comma-separated `target_zone_names`, `standards_template` DOE Ref Pre-1980, DOE Ref 1980-2004, or 90.1-2004 through 90.1-2019) plus 5 `modify_existing_*` modifiers that take exact OpenStudio object names. Do not map to the deprecated `modify_hvac`. A principal HVAC label alone is family evidence, not an exact match. Do not invent model object or zone names from BuildingSync IDs.

Verify every measure directory and argument against the source BOSS will load: the `BOSS.gemspec` gem versions, or the merged `buildingsync-measures-gem` ref. Do not map to measures that exist only on an unmerged branch.
Verify every measure directory and argument against the source BOSS will load: the `BOSS.gemspec` gem versions, or the `buildingsync-measures-gem` commit pinned in CI. During PR 14A-14E, CI may pin an unmerged `buildingsync-measures-gem` branch commit; the upstream merge and CI ref bump are the last step of PR 14E. Outside that series, do not map to measures that exist only on an unmerged branch.

Keep relative-change mappings (for example "reduce by percentage") on relative measures. Do not swap them for absolute-target measures unless the measure skips models that already meet the target.

Expand Down Expand Up @@ -309,12 +309,22 @@ Use this roadmap as the tracker. Keep `Status` and `Delivered by` current when a

### PR 14D: Baseline HVAC Integration

- Status: Planned
- Status: Done
- Delivered by: -
- Depends on: PR 14A-14C.
- Scope: For exact-match files, run `create_typical_building_from_model` with `add_hvac: false`, then the split topology `create` steps. `add_hvac: false` also skips standards sizing and HVAC efficiency steps, so this PR must account for them. Otherwise keep the current baseline and warn (missing or family-only HVAC data, or templates other than 90.1-2013/2016/2019).
- Scope: For exact-match files, run `create_typical_building_from_model` with `add_hvac: false`, then the split topology `create` steps. `add_hvac: false` also skips standards sizing and HVAC efficiency steps, so this PR must account for them. Otherwise keep the current baseline and warn (missing or family-only HVAC data, or templates the split measures do not accept, such as DEER).
- Done when: Exact-match baselines simulate with the expected HVAC; fallback files keep their current steps and log why; baseline-only and scenario-writer baselines match.
- Avoid: Mapping DOE Ref, older 90.1, or DEER templates to 90.1-2019, or adding HVAC on top of `add_hvac: true`.
- Findings: with `add_hvac: false`, openstudio-standards 0.8.2 `create_typical_building_from_model` skips PRM sizing parameters, the sizing run, multizone VAV outdoor-air sizing, prototype HVAC assumptions, the HVAC efficiency standard, and NIST infiltration schedules; its night-cycle thermostat change then finds no managers. Topology measures do none of these. No existing measure runs this tail alone.
- Decision: `BOSS::BaselineHvacPlanner` (`lib/BOSS/baseline_hvac_planner.rb`) plans topology HVAC only when every selector result is `:match`, binds to whole-building premises, the template is in `HvacTargetBinder::STANDARDS_TEMPLATES` (DOE Ref Pre-1980, DOE Ref 1980-2004, 90.1-2004 through 90.1-2019), and there is exactly one conditioning configuration plus at most one ventilation configuration (ventilation only with zone-equipment topologies, since DOAS `create` rejects air-loop zones). Steps go right after `create_typical_building_from_model`: conditioning, then ventilation, then the new upstream measure `apply_standard_hvac_sizing_and_efficiency`, which mirrors the skipped tail. Otherwise `build_baseline_osw` keeps `add_hvac: true` and logs each reason. When topology steps are used, the baseline adds the scenario-only `buildingsync-measures-gem` measure path. Baseline-only and scenario writers share `build_baseline_osw`.
- Current fixture effect: `example-smalloffice-level2` (and its 2012 copy) plan topology HVAC; every other v2.7.0 fixture falls back. Files with no standard or a DEER template fail the template gate. The first HVAC reason for the rest is: family-only `PrincipalHVACSystemType` data (L100 files, `building_151_level1`, `example-smalloffice-level1`, `all_measures_applied_example`, BETTER); HVACSystems the selector sees without Delivery/OtherHVACSystem records (most ASHRAE-L2-style, Chula Vista, NYC, San Francisco, HOMES, Golden Test File, ASHRAE 211 Export); heat/energy-recovery ventilation (`not_mappable`: BuildingEQ, `Example_ASHRAE_L2_Report`); and detailed data that matches no known configuration (`Reference-PrimarySchool-L200-Audit`, `Example_NYC_Energy_Efficiency_Report_Property_2`). The gaps behind these are listed in `docs/hvac_mapping_gaps.md`.
- Follow-up: delivery premises inheritance and `None`/untyped ventilation handling landed in 14B and did not unlock a fixture.
- Configuration merging: the planner treats results with the same measure and `measure_arguments` as one configuration, whatever their group keys. Its premises count as whole-building (one `apply_hvac_topology_to_zone_scope` step with `all_model_zones`) when every link is a `Section` of the single `Building` and the links include its `Whole building` section or every other non-empty section. Partial section coverage still returns `missing_input`.
- First topology fixture: `example-smalloffice-level2` (built 2000, `DOE Ref 1980-2004`) plans one Packaged Rooftop Heat Pump step with `{"supplemental_heating_fuel":"NaturalGas"}`, then the sizing step. The test-only copy `spec/files/v2.7.0/example-smalloffice-level2-built-2012.xml` sets `YearOfConstruction` and `YearOfLastMajorRemodel` to 2012 and covers the same plan at `90.1-2013`.
- Older templates: the gem branch widened `standards_template` on every topology measure, the wrapper, and the sizing measure to DOE Ref Pre-1980, DOE Ref 1980-2004, and 90.1-2004 through 90.1-2019, and its shared topology test creates each measure's system at every older template. BOSS's reader never emits `90.1-2004` (2004-2006 maps to `90.1-2007`); changing that year mapping is out of scope.
- Remaining: `apply_standard_hvac_sizing_and_efficiency` is on the gem branch; CI now pins `789bd50`, which also adds older-template support. Its Minitest covers arguments and input checks only, and the BOSS integration spec below exercises the sizing path. The upstream merge moves to the end of PR 14E.
- Manual baseline run (OpenStudio 3.10.0, San Francisco TMY3): `boss write_baseline_osw` on the 2012 copy wrote the topology steps, and every step succeeded. The model has 9 single-zone PSZ-HP air loops with gas backup coils, 90.1-2013 efficiencies (14 SEER / 8.0 HSPF), 25.5 h heating and 25 h cooling setpoints not met, and EnergyPlus had 0 severe errors. The run log also shows one `Step already started` OSRunner error, apparently from the sizing step, which still succeeds; the cause is not investigated.
- Integration check: `spec/tests/integration/write_and_run_osws_spec.rb` writes and runs the baseline for `example-smalloffice-level2` (`DOE Ref 1980-2004`) and its 2012 copy (`90.1-2013`). Each asserts `add_hvac: false`, a successful topology step that reports PSZ-HP loops with NaturalGas supplemental heat at the expected template, and a successful sizing step (about 1.5 minutes each locally).

### PR 14E: Scenario HVAC Mappings

Expand All @@ -324,6 +334,7 @@ Use this roadmap as the tracker. Keep `Status` and `Delivered by` current when a
- 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.
- Series close: merge the `buildingsync-measures-gem` branch upstream (`apply_hvac_topology_to_zone_scope`, `apply_standard_hvac_sizing_and_efficiency`, and any 14E measures), replace the CI branch-commit pin with the merged commit, and rerun the unit and integration suites.

### PR 15: CLI Command

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

module BOSS
# Decides whether the baseline builds HVAC from split topology measures or keeps
# create_typical_building_from_model HVAC.
#
# Every binder step resolves to all model zones, so a topology plan allows one
# conditioning configuration plus, for zone-equipment configurations only, one
# ventilation configuration (DOAS create rejects zones already on an air loop).
# Results with the same measure and measure arguments are one configuration. Its
# Section links count as whole-building when they cover the building's sections.
class BaselineHvacPlanner
SIZING_MEASURE = 'apply_standard_hvac_sizing_and_efficiency'
VENTILATION_MEASURES = HvacTopologySelector::VENTILATION_MEASURES.values.map(&:last).freeze
ZONE_EQUIPMENT_MEASURES = ['hvac_ptac', 'hvac_pthp', 'hvac_four_pipe_fan_coil', 'hvac_vrf'].freeze

Plan = Struct.new(:status, :steps, :messages, keyword_init: true) do
def topology? = status == :topology
end

def initialize(selector: HvacTopologySelector.new, binder: HvacTargetBinder.new)
@selector = selector
@binder = binder
end

# @param hvac_systems [REXML::Element, nil] the facility HVACSystems element
# @param standards_template [String] baseline create_typical template
# @return [Plan] :topology with ordered OSW steps, or :fallback with the reasons
def plan(hvac_systems, standards_template)
return fallback(['No HVACSystems in the facility.']) if hvac_systems.nil?

if !HvacTargetBinder::STANDARDS_TEMPLATES.include?(standards_template)
return fallback(["Template '#{standards_template}' is not supported by the split HVAC measures " \
"(#{HvacTargetBinder::STANDARDS_TEMPLATES.join(', ')})."])
end

results = @selector.select(hvac_systems)
return fallback(['No HVACSystem records.']) if results.empty?

unmatched = results.reject { |result| result.status == :match }
return fallback(unmatched.map { |result| describe(result, result.status, result.messages) }) if !unmatched.empty?

groups = results.group_by { |result| [result.measure, result.measure_arguments || {}] }.values
.map { |members| merge(members, hvac_systems) }
ventilation, conditioning = groups.partition { |result| VENTILATION_MEASURES.include?(result.measure) }
problems = []
if conditioning.length != 1
problems << "Expected one conditioning configuration, found #{conditioning.length}; " \
'zone-level binding is not supported.'
end
problems << "Expected at most one ventilation configuration, found #{ventilation.length}." if ventilation.length > 1
if !ventilation.empty? && conditioning.length == 1 && !ZONE_EQUIPMENT_MEASURES.include?(conditioning.first.measure)
problems << "#{ventilation.first.configuration} cannot be added to zones served by " \
"#{conditioning.first.configuration} air loops."
end
return fallback(problems) if !problems.empty?

bindings = (conditioning + ventilation).map do |result|
[result, @binder.bind(result, operation: 'create', standards_template:)]
end
unbound = bindings.reject { |_, binding| binding.status == :bound }
return fallback(unbound.map { |result, binding| describe(result, binding.status, binding.messages) }) if !unbound.empty?

sizing_step = { measure_dir_name: SIZING_MEASURE, arguments: { standards_template: } }
Plan.new(status: :topology, steps: bindings.map { |_, binding| binding.step } + [sizing_step], messages: [])
end

private

def merge(members, hvac_systems)
merged = members.first.dup
merged.premises = members.flat_map { |member| member.premises || [] }.uniq
building_id = covered_building_id(merged.premises, hvac_systems)
merged.premises = [{ type: 'Building', id: building_id }] if building_id
merged
end

# @return [String, nil] the building ID when every premise is a Section of the one
# building and they include its 'Whole building' section or all of its other
# non-empty sections
def covered_building_id(premises, hvac_systems)
return nil if premises.empty? || !premises.all? { |premise| premise[:type] == 'Section' }

buildings = REXML::XPath.match(hvac_systems.document, "//*[local-name()='Building'][@ID]")
return nil if buildings.length != 1

sections = REXML::XPath.match(buildings.first, "*[local-name()='Sections']/*[local-name()='Section'][@ID]")
section_ids = sections.map { |section| section.attributes['ID'] }
linked = premises.map { |premise| premise[:id] }
return nil if !(linked - section_ids).empty?

whole, parts = sections.partition do |section|
REXML::XPath.first(section, "*[local-name()='SectionType']")&.text == 'Whole building'
end
whole_linked = whole.any? { |section| linked.include?(section.attributes['ID']) }
parts_linked = !parts.empty? && parts.all? do |section|
section.elements.empty? || linked.include?(section.attributes['ID'])
end
whole_linked || parts_linked ? buildings.first.attributes['ID'] : nil
end

def fallback(messages)
Plan.new(status: :fallback, steps: [], messages:)
end

def describe(result, status, messages)
label = result.configuration || result.hvac_system_id || 'HVACSystem'
"#{label} (#{status}): #{messages.join(' ')}"
end
end
end
15 changes: 13 additions & 2 deletions lib/BOSS/boss.rb
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
require 'BOSS/osw_arg_populator'
require 'BOSS/external_measure_repo_manager'
require 'BOSS/scenario_measure_mapper'
require 'BOSS/baseline_hvac_planner'

require 'openstudio/common_measures'
require 'openstudio/model_articulation'
Expand Down Expand Up @@ -201,7 +202,16 @@ def build_baseline_osw(bsync_reader)
OSWArgPopulator::populate_change_building_location_args(baseline_osw, bsync_reader)

OSWArgPopulator::populate_create_bar_from_building_type_ratios_args(baseline_osw, bsync_reader)
OSWArgPopulator::populate_create_typical_building_from_model_args(baseline_osw, bsync_reader)
hvac_plan = BaselineHvacPlanner.new.plan(bsync_reader.get_hvac_systems_xml, bsync_reader.get_standard_template)
OSWArgPopulator::populate_create_typical_building_from_model_args(baseline_osw, bsync_reader,
add_hvac: !hvac_plan.topology?)
if hvac_plan.topology?
hvac_plan.steps.each { |step| OSWArgPopulator.append_step(baseline_osw, step) }
else
hvac_plan.messages.each do |message|
BOSS.BOSS_logger.warn("BOSS.Boss: Keeping create_typical_building_from_model HVAC: #{message}")
end
end

OSWArgPopulator::populate_set_lighting_loads_by_LPD_args(baseline_osw, bsync_reader)
OSWArgPopulator::populate_set_electric_equipment_loads_by_epd_args(baseline_osw, bsync_reader)
Expand All @@ -215,7 +225,8 @@ def build_baseline_osw(bsync_reader)
# Force ordering: local BOSS measures, extension-discovered (gems), then external repos.
manager = ExternalMeasureRepoManager.new
local_measure_dirs = manager.local_measure_directories
external_measure_dirs = manager.resolved_measure_directories
# Topology HVAC steps need buildingsync-measures-gem, which is otherwise scenario-only.
external_measure_dirs = manager.resolved_measure_directories(include_scenario_only: hvac_plan.topology?)
discovered_measure_dirs = baseline_osw[:measure_paths] || []

discovered_nonlocal_nonexternal = discovered_measure_dirs.reject do |path|
Expand Down
5 changes: 5 additions & 0 deletions lib/BOSS/buildingsync_reader/buildingsync_reader.rb
Original file line number Diff line number Diff line change
Expand Up @@ -399,6 +399,11 @@ def get_aspect_ratio
return aspect_ratio.to_f
end

# @return [REXML::Element, nil] the facility HVACSystems element
def get_hvac_systems_xml
@facility_xml.elements["#{@ns}Systems/#{@ns}HVACSystems"]
end

# get principal hvac system type
# @return [String]
def get_principal_HVAC_system_type
Expand Down
3 changes: 2 additions & 1 deletion lib/BOSS/hvac_target_binder.rb
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,8 @@ class HvacTargetBinder
}.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
STANDARDS_TEMPLATES = ['DOE Ref Pre-1980', 'DOE Ref 1980-2004', '90.1-2004', '90.1-2007', '90.1-2010',
'90.1-2013', '90.1-2016', '90.1-2019'].freeze
OPERATIONS = ['create', 'replace'].freeze

Binding = Struct.new(:status, :step, :messages, keyword_init: true)
Expand Down
6 changes: 3 additions & 3 deletions lib/BOSS/osw_arg_populator.rb
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ def self.populate_create_bar_from_building_type_ratios_args(osw, bsync_reader)
BOSS.BOSS_logger.info("")
end

def self.populate_create_typical_building_from_model_args(osw, bsync_reader)
def self.populate_create_typical_building_from_model_args(osw, bsync_reader, add_hvac: true)
BOSS.BOSS_logger.info("+++++ populating measure create_typical_building_from_model +++++++++++++++")
set_measure_argument = step_argument_setter(osw, "create_typical_building_from_model")

Expand Down Expand Up @@ -183,8 +183,8 @@ def self.populate_create_typical_building_from_model_args(osw, bsync_reader)
# add_thermostat
# add_hvac
BOSS.BOSS_logger.info("|\t- setting arg 'add_hvac'...")
BOSS.BOSS_logger.info("|\t defaults to 'true'")
set_measure_argument.call("add_hvac", true)
BOSS.BOSS_logger.info("|\t set to '#{add_hvac}'")
set_measure_argument.call("add_hvac", add_hvac)
# add_refrigeration
# modify_wkdy_op_hrs
# wkdy_op_hrs_start_time
Expand Down
Loading
Loading