From bf0514e5aee393a374ed80b072f951895706b33d Mon Sep 17 00:00:00 2001 From: JieXiong9119 <69597597+JieXiong9119@users.noreply.github.com> Date: Thu, 12 Nov 2026 13:29:51 -0700 Subject: [PATCH] update plan for hvac mapping updates, add local buildingsync-measure-gem --- .github/workflows/ci.yml | 12 ++++ config/external_measure_repos.yml | 9 +-- docs/scenario_workflow_translation_plan.md | 63 +++++++++++++++++-- lib/BOSS/external_measure_repo_manager.rb | 27 +++++++- .../external_measure_repo_manager_spec.rb | 59 +++++++++++++++++ 5 files changed, 159 insertions(+), 11 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d69b87f..356f64c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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" diff --git a/config/external_measure_repos.yml b/config/external_measure_repos.yml index d73f26e..caaa938 100644 --- a/config/external_measure_repos.yml +++ b/config/external_measure_repos.yml @@ -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//in.osw), never to baseline/in.osw @@ -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 diff --git a/docs/scenario_workflow_translation_plan.md b/docs/scenario_workflow_translation_plan.md index b1a2f6e..13495ea 100644 --- a/docs/scenario_workflow_translation_plan.md +++ b/docs/scenario_workflow_translation_plan.md @@ -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 @@ -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 @@ -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. @@ -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 @@ -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`. @@ -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. diff --git a/lib/BOSS/external_measure_repo_manager.rb b/lib/BOSS/external_measure_repo_manager.rb index db12220..640f7f0 100644 --- a/lib/BOSS/external_measure_repo_manager.rb +++ b/lib/BOSS/external_measure_repo_manager.rb @@ -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) @@ -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}" @@ -129,6 +134,10 @@ 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 @@ -136,7 +145,17 @@ def validate_repo_entry(repo) 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'] @@ -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 diff --git a/spec/tests/unit/external_measure_repo_manager_spec.rb b/spec/tests/unit/external_measure_repo_manager_spec.rb index f4ff0ce..1df4e57 100644 --- a/spec/tests/unit/external_measure_repo_manager_spec.rb +++ b/spec/tests/unit/external_measure_repo_manager_spec.rb @@ -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