Skip to content
Open
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
39 changes: 33 additions & 6 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,10 @@ concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true

env:
# Pinned commit of the sibling checkout that config/external_measure_repos.yml loads via local_path.
BSYNC_MEASURES_REF: 789bd50ec0ba42559f85e5cac23fcbbf8f9bdfbe

jobs:
unit:
name: unit
Expand All @@ -25,17 +29,29 @@ jobs:
env:
LANG: C.UTF-8
LC_ALL: C.UTF-8
defaults:
run:
working-directory: BOSS
steps:
- name: Checkout Code
uses: actions/checkout@v4
with:
path: BOSS
# Not released as a gem; config/external_measure_repos.yml loads it from ../buildingsync-measures-gem.
- name: Checkout buildingsync-measures-gem
uses: actions/checkout@v4
with:
repository: BuildingSync/buildingsync-measures-gem
ref: ${{ env.BSYNC_MEASURES_REF }}
path: buildingsync-measures-gem
- name: Cache gems
uses: actions/cache@v4
with:
path: .bundle/install
key: gems-${{ runner.os }}-os3.10.0-${{ hashFiles('Gemfile.lock', '*.gemspec') }}
key: gems-${{ runner.os }}-os3.10.0-${{ hashFiles('BOSS/Gemfile.lock', 'BOSS/*.gemspec') }}
- name: Setup
run: |
git config --global --add safe.directory "$GITHUB_WORKSPACE"
git config --global --add safe.directory '*'
gem install bundler -v 2.4.10
bundle config set --local path "$GITHUB_WORKSPACE/.bundle/install"
bundle install
Expand Down Expand Up @@ -90,19 +106,30 @@ jobs:
LC_ALL: C.UTF-8
BOSS_SHARD: ${{ matrix.shard }}
BOSS_SHARDS: '4'
defaults:
run:
working-directory: BOSS
steps:
- name: Checkout Code
uses: actions/checkout@v4
with:
path: BOSS
- name: Checkout buildingsync-measures-gem
uses: actions/checkout@v4
with:
repository: BuildingSync/buildingsync-measures-gem
ref: ${{ env.BSYNC_MEASURES_REF }}
path: buildingsync-measures-gem
- name: Cache gems
uses: actions/cache@v4
with:
path: .bundle/install
key: gems-${{ runner.os }}-os3.10.0-${{ hashFiles('Gemfile.lock', '*.gemspec') }}
key: gems-${{ runner.os }}-os3.10.0-${{ hashFiles('BOSS/Gemfile.lock', 'BOSS/*.gemspec') }}
- name: Cache external measures
uses: actions/cache@v4
with:
path: vendor/external_measures
key: ext-measures-${{ hashFiles('config/external_measure_repos.yml') }}
path: BOSS/vendor/external_measures
key: ext-measures-${{ hashFiles('BOSS/config/external_measure_repos.yml') }}
- name: Setup
run: |
git config --global --add safe.directory '*'
Expand All @@ -117,4 +144,4 @@ jobs:
uses: actions/upload-artifact@v4
with:
name: integration-output-shard-${{ matrix.shard }}
path: spec/output
path: BOSS/spec/output
37 changes: 36 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ The shipped manifest lives at [config/external_measure_repos.yml](config/externa

- local measure roots: `lib/measures` (first in precedence)
- external repository: comstock (`measures` and `resources/measures`)
- local checkout: `buildingsync-measures-gem` (`lib/measures`), expected as a sibling of this repository (`../buildingsync-measures-gem`). It is marked `scenario_only` and is added to `measure_paths` only for baselines that use an HVAC topology. CI pins its commit via `BSYNC_MEASURES_REF` in [.github/workflows/ci.yml](.github/workflows/ci.yml).

Measure path precedence is:

Expand All @@ -46,6 +47,40 @@ Measure path precedence is:

The generated `in.osw` will include these paths in order under `measure_paths`.

### Baseline HVAC

When the facility's detailed (L200) `HVACSystems` exactly match a supported topology, the baseline sets `create_typical_building_from_model`'s `add_hvac` to `false` and adds `apply_hvac_topology_to_zone_scope` (operation `create`) and `apply_standard_hvac_sizing_and_efficiency` from buildingsync-measures-gem. Supported templates are DOE Ref Pre-1980, DOE Ref 1980-2004, and 90.1-2004 through 90.1-2019. HVAC systems referenced by measures as proposed (`AlternativeSystemReplacement` or `ModifiedSystem`) are excluded from the baseline.

Configurations that can produce a topology baseline:

| Configuration | Topology measure |
|---|---|
| Packaged Terminal Air Conditioner | `hvac_ptac` |
| Packaged Terminal Heat Pump | `hvac_pthp` |
| Four Pipe Fan Coil Unit | `hvac_four_pipe_fan_coil` |
| Packaged Rooftop Air Conditioner | `hvac_packaged_rooftop_ac` |
| Packaged Rooftop Heat Pump | `hvac_packaged_rooftop_heat_pump` |
| Packaged Rooftop VAV with Hot Water Reheat | `hvac_packaged_rooftop_vav_hw_reheat` |
| VAV with Hot Water Reheat | `hvac_vav_hw_reheat` |
| Warm Air Furnace | `hvac_warm_air_furnace` |
| VRF Terminal Unit | `hvac_vrf` |

A Ventilation Only (`hvac_ventilation_only`) or Dedicated Outdoor Air System (`hvac_doas`) configuration can be added on top, but only alongside PTAC, PTHP, four-pipe fan coil, or VRF.

Recognized but not yet mapped (always fall back): Packaged Rooftop VAV with Electric Reheat, VAV with Electric Reheat, Water Loop Heat Pump, Ground Source Heat Pump, Chilled Beam, and hydronic radiant systems.

BOSS also falls back when:

- any selected `HVACSystem` does not match a supported configuration;
- there is not exactly one conditioning configuration, or there is more than one ventilation configuration;
- ventilation is paired with a conditioning type that does not allow it;
- the template is not supported;
- a system's premises are scoped to specific zones rather than the whole building (the baseline binds topologies to all model zones only).

On fallback, BOSS uses the `system_type` mapping below with `add_hvac` set to `true`, and logs a warning explaining why.

Integration simulations currently cover the packaged rooftop heat pump; the other configurations are covered by unit specs.

## OpenStudio Compatibility Version

| OpenStudio Version | BuildingSync Version | BOSS Version |
Expand Down Expand Up @@ -96,7 +131,7 @@ The table below maps in detail the BuildingSync XML data to measure inputs. Note
| | template | get_standard_template | either `.../Building/YearOfLastMajorRemodel` or `.../Building/YearOfConstruction` |
| | system_type | get_principal_HVAC_system_type | at least one mappable entry of `.../Systems/HVACSystems/HVACSystem/PrincipalHVACSystemType` |
| | add_swh | | Hard Coded to to true |
| | add_hvac | | Hard Coded to to true |
| | add_hvac | | `true` for fallback baselines; `false` when an HVAC topology is applied (see [Baseline HVAC](#baseline-hvac)) |
| [SetLightingLoadsByLPD] | | | |
| | lpd | get_total_installed_power | `/InstalledPower` in ALL instances of `.../Systems/LightingSystems/LightingSystem` |
| [set_electric_equipment_loads_by_epd] | | | |
Expand Down
13 changes: 13 additions & 0 deletions config/external_measure_repos.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,12 @@ local_measure_roots:
# - name: local checkout folder name under vendor/external_measures
# - url: git repository URL
# - ref: pinned tag/branch/commit to checkout
# - local_path (instead of url/ref): existing local checkout, relative to this file.
# BOSS uses it in place and never runs Git against it; a missing path is an error.
# - measure_roots: one or more paths inside the repo that contain measure directories
# - scenario_only (optional, default false): when true, measure roots are added only to
# workflows that opt in (baseline/in.osw with a detailed HVAC topology); fallback
# baselines omit them, so they do not require this checkout
#

# The below measures are needed for the BOSS L200 workflow.
Expand All @@ -25,3 +30,11 @@ repos:
measure_roots:
- measures
- resources/measures

# BuildingSync HVAC topology measures. Not released as a gem, so BOSS
# loads the sibling checkout ../buildingsync-measures-gem (CI pins its commit).
- name: buildingsync-measures-gem
local_path: ../../buildingsync-measures-gem
measure_roots:
- lib/measures
scenario_only: true
148 changes: 148 additions & 0 deletions lib/BOSS/baseline_hvac_planner.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,148 @@
# 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
# @param operation [String] binder operation for the conditioning step; ventilation is always created
# @param include_system_ids [Array<String>, nil] when given, only these HVACSystems are planned
# @param exclude_system_ids [Array<String>] HVACSystems left out, such as proposed scenario systems
# @return [Plan] :topology with ordered OSW steps, or :fallback with the reasons
def plan(hvac_systems, standards_template, operation: 'create', include_system_ids: nil, exclude_system_ids: [])
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).select do |result|
(include_system_ids.nil? || include_system_ids.include?(result.hvac_system_id)) &&
!exclude_system_ids.include?(result.hvac_system_id)
end
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.map { |result| [result, @binder.bind(result, operation:, standards_template:)] } +
ventilation.map { |result| [result, @binder.bind(result, operation: 'create', standards_template:)] }
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

# @return [Array<String>] HVACSystem IDs that measures name as alternatives or modified systems
def self.proposed_system_ids(hvac_systems)
return [] if hvac_systems.nil?

system_ids = _system_ids(hvac_systems)
refs = REXML::XPath.match(
hvac_systems.document,
"//*[local-name()='Measure']/*[local-name()='TypeOfMeasure']//" \
"*[local-name()='AlternativeSystemReplacement' or local-name()='ModifiedSystem']/@IDref"
).map(&:value)
refs.uniq & system_ids
end

def self._system_ids(hvac_systems)
REXML::XPath.match(hvac_systems, "*[local-name()='HVACSystem']/@ID").map(&:value)
end

# @return [Array<Hash>] premises, or one Building premise when Section links cover the building
def self.normalize_premises(premises, document)
building_id = covered_building_id(premises, document)
building_id ? [{ type: 'Building', id: building_id }] : premises
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 self.covered_building_id(premises, document)
return nil if premises.empty? || !premises.all? { |premise| premise[:type] == 'Section' }

buildings = REXML::XPath.match(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

private

def merge(members, hvac_systems)
merged = members.first.dup
merged.premises = self.class.normalize_premises(members.flat_map { |member| member.premises || [] }.uniq,
hvac_systems.document)
merged
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
Loading
Loading