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
12 changes: 12 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,21 @@ 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: c7efd329ae30b345d238de5c4dcddeceb8ba0298
path: buildingsync-measures-gem
- name: Setup
run: |
git config --global --add safe.directory "$GITHUB_WORKSPACE"
Expand Down
9 changes: 5 additions & 4 deletions config/external_measure_repos.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ 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
# scenario workflows (scenarios/<id>/in.osw), never to baseline/in.osw
Expand All @@ -28,11 +30,10 @@ repos:
- measures
- resources/measures

# BuildingSync measures used by scenario mappings (modify_envelope_insulation).
# Pinned to a commit on develop.
# BuildingSync measures used by scenario mappings. Not released as a gem, so BOSS
# loads the sibling checkout ../buildingsync-measures-gem (CI pins its commit).
- name: buildingsync-measures-gem
url: https://github.com/BuildingSync/buildingsync-measures-gem.git
ref: c40c2ed65952a1c3bfe82bf1daa542ce5e1ee8d6
local_path: ../../buildingsync-measures-gem
measure_roots:
- lib/measures
scenario_only: true
63 changes: 57 additions & 6 deletions docs/scenario_workflow_translation_plan.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Scenario Workflow Translation Plan

This plan tracks the work needed for BOSS to translate BuildingSync package scenarios into OpenStudio workflows. Roadmap PRs land on the `scenario-workflow` integration branch. Merge `scenario-workflow` into `develop` once the feature is usable end to end (after PR 15). Future PRs should stay small and follow the roadmap below.
This plan tracks the work needed for BOSS to translate BuildingSync package scenarios into OpenStudio workflows. Roadmap PRs land on the `scenario-workflow` integration branch. Merge `scenario-workflow` into `develop` once the feature is usable end to end (after PR 14A-14E and PR 15-18). Future PRs should stay small and follow the roadmap below.

## Goal

Expand All @@ -14,6 +14,7 @@ The first scenario release should:
- Write `baseline/in.osw` plus one scenario OSW for each package scenario with at least one mapped measure.
- Run baseline and scenario OSWs through `OpenStudio::Extension::Runner`.
- Warn about skipped or unmapped measures without failing the whole translation.
- Build baseline HVAC and map HVAC retrofits with the split `buildingsync-measures-gem` HVAC measures when BuildingSync data supports an exact match (PR 14A-14E). Otherwise keep the existing baseline HVAC path and warn.

## Out Of Scope For The First Release

Expand Down Expand Up @@ -111,6 +112,12 @@ Measure source order for new mappings:
2. OpenStudio measure gems declared in `BOSS.gemspec`.
3. If neither has an applicable measure, add one to `buildingsync-measures-gem` instead of BOSS.

`buildingsync-measures-gem` is one measure source among several. ComStock, `openstudio-common-measures`, `openstudio-ee`, `openstudio-model-articulation`, and `openstudio-standards` stay supported. Pick the measure that fits the BuildingSync semantics; do not move existing mappings to `buildingsync-measures-gem` unless the new measure is verified as a better fit.

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

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.

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 @@ -255,12 +262,56 @@ Use this roadmap as the tracker. Keep `Status` and `Delivered by` current when a

### PR 14: Generalized Runner

- Status: In Progress
- Delivered by: `scenario-workflow-14-generalized-runner` branch
- Status: Done
- Delivered by: PR #23, merged into `scenario-workflow`
- Scope: Run `baseline/in.osw` and the `:written` scenario OSWs from a `write_baseline_and_scenario_osws` result while keeping `run_baseline_osw` intact. The writer result, not a `scenarios/**/in.osw` scan, selects scenarios, because the writer does not remove stale OSWs.
- Done when: Tests or smoke runs show the correct OSW list and baseline-only compatibility.
- Avoid: Running skipped, stale, or missing OSWs, or removing baseline-only behavior.

### PR 14A: Local Measure Source Support

- Status: Planned
- Delivered by: -
- Scope: Let a repo entry in `config/external_measure_repos.yml` point to a local checkout (`local_path`, relative to the manifest) instead of a Git URL. Use it for `buildingsync-measures-gem` (`../../buildingsync-measures-gem`, root `lib/measures`). Keep ComStock and gem-provided measures unchanged.
- Done when: Local sources resolve independent of CWD, BOSS runs no Git commands against them, a missing local source fails with an actionable error, and mixed-source scenario OSWs resolve every step. CI checks out `buildingsync-measures-gem` as a sibling at a recorded commit.
- Avoid: Silent fallback to `vendor/external_measures/buildingsync-measures-gem`, changing measure path precedence, or treating `buildingsync-measures-gem` as the only source.

### PR 14B: HVAC Selection Contract

- Status: Planned
- Delivered by: -
- Depends on: Can run in parallel with PR 14A.
- Scope: Read detailed HVAC data (sources, deliveries, plants, condensers, other HVAC systems, linked premises) and select topologies with the upstream guide's predicates. Shared by baseline and scenario workflows. Keep `get_principal_HVAC_system_type` for the existing baseline path.
- Done when: Table-driven tests cover exact matches and separate results for missing input, conflicting input, mapping gaps, and configurations with no gem measure.
- Avoid: Inferring topology from `MeasureName` or principal label alone, or dropping HVAC constituents silently.

### PR 14C: Model Target Binding

- Status: Planned
- 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.

### PR 14D: Baseline HVAC Integration

- Status: Planned
- 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).
- 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`.

### PR 14E: Scenario HVAC Mappings

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

### PR 15: CLI Command

- Status: Planned
Expand Down Expand Up @@ -352,7 +403,7 @@ Use this section for stable facts future PRs need. Keep entries short and tied t
- Delivered by: PR #10, merged into `scenario-workflow` via PR #5
- Handoff: `lib/BOSS/scenario_measure_map.json` maps 12 `building_151.xml` category/name pairs to OSW-shaped steps with `measure_dir_name` and an argument hash that includes `__SKIP__`. Source strings match reader output exactly.
- Handoff: Roof and wall absolute insulation targets use `buildingsync-measures-gem` `modify_envelope_insulation` with SI R-values (R-30 IP = 5.28, R-25 IP = 4.40 m²K/W). Other mappings use `openstudio-ee` or `openstudio-common-measures`. Relative mappings such as air sealing, ceiling insulation by percentage, and thermal bypasses stay on relative measures.
- Deferred: Daylight controls, package unit replacement, burner replacement, and boiler replacement. The `buildingsync-measures-gem` split HVAC measures (`modify_existing_hvac_equipment_efficiencies`, `modify_existing_plant_equipment`, `hvac_packaged_rooftop_*`) need exact model object or zone names. Map them in a follow-up after `buildingsync-measures-gem` PR #3 merges and exact target names can be supplied; PR 8 only adds the conditional-argument engine they may use.
- Deferred: Daylight controls, package unit replacement, burner replacement, and boiler replacement. The `buildingsync-measures-gem` split HVAC measures (`modify_existing_hvac_equipment_efficiencies`, `modify_existing_plant_equipment`, `hvac_packaged_rooftop_*`) need exact model object or zone names. Map them in a follow-up after `buildingsync-measures-gem` PR #3 merges and exact target names can be supplied; PR 8 only adds the conditional-argument engine they may use. Update: upstream PR #3 merged (`c7efd32`); this work is now PR 14A-14E.
- Verification: JSON parse passed; every mapped measure directory and argument was checked against installed `BOSS.gemspec` gems and `buildingsync-measures-gem` `develop`.
- Verification: `C:\Ruby32-x64\bin\ruby.exe -S bundle exec rspec spec/tests/unit/scenario_measure_map_spec.rb`.
- Follow-up: PR 6 adds `BOSS::ScenarioMeasureMapper`. PR 12 must put `buildingsync-measures-gem` on OSW `measure_paths`.
Expand Down Expand Up @@ -458,8 +509,8 @@ Use this section for stable facts future PRs need. Keep entries short and tied t

### PR 14: Generalized Runner

- Status: In Progress
- Delivered by: `scenario-workflow-14-generalized-runner` branch
- Status: Done
- Delivered by: PR #23, merged into `scenario-workflow`
- Handoff: `BOSS::Boss.run_baseline_and_scenario_osws(write_result)` takes the symbol-keyed result of `write_baseline_and_scenario_osws`. It submits the baseline first, then every `status: :written` scenario `osw_path` in result order, deduplicated, in one `Runner#run_osws` call. It returns the runner's failure-message array; runner exceptions propagate.
- Handoff: Skipped scenarios never run, even if an older `in.osw` exists. Scenario OSWs on disk but absent from the result are ignored; no directory is scanned. A `:written` entry whose path is missing, blank, or not a file is skipped with a `BOSS.BOSS_logger` warning.
- Handoff: A malformed result raises `ArgumentError`; a missing baseline file logs an OpenStudio error and raises `StandardError`. Neither builds a runner. The input is not mutated.
Expand Down
27 changes: 26 additions & 1 deletion lib/BOSS/external_measure_repo_manager.rb
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,11 @@ def resolved_measure_directories(include_scenario_only: false)
next if repo_entry['scenario_only'] && !include_scenario_only

repo_root = repo_checkout_dir(repo_entry)
if local_repo?(repo_entry) && !Dir.exist?(repo_root)
raise StandardError, "Local measure repository '#{repo_entry['name']}' not found at #{repo_root}. " \
"Check out the repository there or update local_path in #{@manifest_path}."
end

if !Dir.exist?(repo_root)
message = "Repository '#{repo_entry['name']}' is not installed at #{repo_root}. Run rake measures:install_external."
if defined?(OpenStudio) && OpenStudio.respond_to?(:logFree)
Expand Down Expand Up @@ -114,7 +119,7 @@ def validate_repo_entry(repo)
raise StandardError, "Each repo entry in #{@manifest_path} must be a map"
end

required = %w[name url ref measure_roots]
required = repo.key?('local_path') ? %w[name local_path measure_roots] : %w[name url ref measure_roots]
missing = required.select { |key| repo[key].nil? || repo[key].to_s.empty? }
if !missing.empty?
raise StandardError, "Repo entry is missing required keys #{missing.join(', ')} in #{@manifest_path}"
Expand All @@ -129,14 +134,28 @@ def validate_repo_entry(repo)
raise StandardError, "Repo '#{repo['name']}' must define a non-empty measure_roots array"
end

if repo.key?('local_path') && (repo.key?('url') || repo.key?('ref'))
raise StandardError, "Repo '#{repo['name']}' must use either local_path or url/ref, not both"
end

if repo.key?('scenario_only') && ![true, false].include?(repo['scenario_only'])
raise StandardError, "Repo '#{repo['name']}' scenario_only must be true or false"
end

repo
end

# Local checkouts are used in place; BOSS never runs Git against them.
def install_repo(repo_entry)
if local_repo?(repo_entry)
repo_dir = repo_checkout_dir(repo_entry)
if !Dir.exist?(repo_dir)
raise StandardError, "Local measure repository '#{repo_entry['name']}' not found at #{repo_dir}. " \
"Check out the repository there or update local_path in #{@manifest_path}."
end
return
end

repo_dir = repo_checkout_dir(repo_entry)
measure_roots = repo_entry['measure_roots']

Expand All @@ -153,7 +172,13 @@ def install_repo(repo_entry)
run_git(%W[-C #{repo_dir} checkout --force FETCH_HEAD])
end

def local_repo?(repo_entry)
repo_entry.key?('local_path')
end

def repo_checkout_dir(repo_entry)
return File.expand_path(repo_entry['local_path'], File.dirname(File.expand_path(@manifest_path))) if local_repo?(repo_entry)

File.join(@install_dir, repo_entry['name'])
end

Expand Down
59 changes: 59 additions & 0 deletions spec/tests/unit/external_measure_repo_manager_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -355,5 +355,64 @@ def manager_for(manifest_path, install_dir)
expect { manager_for(path, dir).configured? }.to raise_error(StandardError, /must be a map/)
end
end

it 'raises when a repo entry sets both local_path and url' do
Dir.mktmpdir do |dir|
yaml = <<~YAML
repos:
- name: my_repo
local_path: ../my_repo
url: https://example.com/repo.git
measure_roots: [lib/measures]
YAML
path = write_manifest(dir, yaml)
expect { manager_for(path, dir).configured? }.to raise_error(StandardError, /either local_path or url/)
end
end
end

# ---------------------------------------------------------------------------
describe 'local_path repos' do
def local_manifest(dir, scenario_only: false)
config_dir = File.join(dir, 'config')
FileUtils.mkdir_p(config_dir)
yaml = <<~YAML
repos:
- name: sibling
local_path: ../sibling
scenario_only: #{scenario_only}
measure_roots: [lib/measures]
YAML
write_manifest(config_dir, yaml)
end

it 'resolves measure roots relative to the manifest without running git' do
Dir.mktmpdir do |dir|
mroot = File.join(dir, 'sibling', 'lib', 'measures')
FileUtils.mkdir_p(mroot)
mgr = manager_for(local_manifest(dir), File.join(dir, 'vendor'))
expect(mgr).not_to receive(:run_git)

mgr.install_all
expect(mgr.resolved_measure_directories).to eq([File.expand_path(mroot)])
end
end

it 'raises an actionable error when the local checkout is missing' do
Dir.mktmpdir do |dir|
mgr = manager_for(local_manifest(dir), File.join(dir, 'vendor'))
expect(mgr).not_to receive(:run_git)

expect { mgr.install_all }.to raise_error(StandardError, /Local measure repository 'sibling' not found/)
expect { mgr.resolved_measure_directories }.to raise_error(StandardError, /local_path/)
end
end

it 'skips a missing scenario-only local checkout for baseline resolution' do
Dir.mktmpdir do |dir|
mgr = manager_for(local_manifest(dir, scenario_only: true), File.join(dir, 'vendor'))
expect(mgr.resolved_measure_directories).to eq([])
end
end
end
end
Loading