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
66 changes: 66 additions & 0 deletions docs/hvac_mapping_gaps.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# HVAC Mapping Gaps Found In BOSS

Gaps between BuildingSync audit data and the `buildingsync-measures-gem` [HVAC Mapping and Migration Guide](https://github.com/BuildingSync/buildingsync-measures-gem/blob/develop/docs/HVAC_MAPPING_AND_MIGRATION.md), found while running `BOSS::HvacTopologySelector` on BOSS fixtures. To be moved to `buildingsync-measures-gem`. Rows the guide already lists as mapping gaps or not mappable (fan-powered VAV with electric reheat, water-loop and ground-source heat pumps, chilled beam, radiant, ERV/HRV, exhaust, natural ventilation) are not repeated here.

Fixture paths are under `spec/files/v2.7.0/`.

Status: gaps 1-7 were resolved upstream in buildingsync-measures-gem `e1b2f33` and gap 8 in `5e775a6`; all are adopted in `BOSS::HvacTopologySelector`.

## Measure Gaps

### 1. Packaged unitary heat pump with gas backup

- Data: `example-smalloffice-level2.xml`, all five deliveries. `HeatPumpType = Packaged Unitary`, `HeatPumpBackupSystemFuel = Natural gas`, single-zone CAV delivery.
- Guide: the Packaged Rooftop Heat Pump row requires `HeatPumpBackupSystemFuel = Electricity`. No row covers gas backup, so the delivery identifies no configuration.
- Measure: `hvac_packaged_rooftop_heat_pump` creates electric supplemental heat only.
- Ask: add a gas-supplemental option to the measure and a guide row, or list gas-backup packaged heat pumps as not mappable.

### 2. Packaged rooftop AC with `FurnaceType = Other`

- Data: `Reference-PrimarySchool-L200-Audit.xml`, PSZAC deliveries. Gas furnace (`PrimaryFuel = Natural gas`, `HeatingMedium = Air`) with `FurnaceType = Other`, packaged RTU DX, single-zone CAV.
- Guide: the Packaged Rooftop Air Conditioner and Warm Air Furnace rows require `FurnaceType = Warm air`.
- Ask: decide whether `Other` (or absent) `FurnaceType` with gas fuel and air medium may match, or list it explicitly as missing input.

## Guide Rule Gaps

### 3. Empty `FanBased/FanBasedDistributionType`

- Data: `Reference-PrimarySchool-L200-Audit.xml`, every delivery. `FanBased` holds an empty `<FanBasedDistributionType/>` next to `AirSideEconomizer` data. The element is optional in the schema.
- Guide: packaged rooftop, VAV, and PTAC/PTHP rows require `absent(A/FanBased/FanBasedDistributionType)` (or `Z/...`). An empty element fails that check, so economizer data blocks the match.
- Ask: treat an empty `FanBasedDistributionType` as absent, or require "no child elements" instead of "absent".

### 4. `CS/Quantity = 1` as a required predicate

- Data: `Reference-PrimarySchool-L200-Audit.xml`, VAV pods. The DX cooling sources omit `Quantity`.
- Guide: Packaged Rooftop VAV with Hot Water Reheat (and VAV with Hot Water Reheat, VRF) list `CS/Quantity = 1` under required cooling predicates, while other `Quantity` checks are guards that pass when absent.
- Ask: make `CS/Quantity` a guard (pass when absent), or confirm it must be supplied.

### 5. Integrated outdoor-air records

- Data: `Reference-PrimarySchool-L200-Audit.xml`. Per-zone `OtherHVACSystem` records with `VentilationType = Supply only` and `Integration = Integrated with central air distribution`, several linked to one VAV delivery, plus integrated records on PSZAC deliveries.
- Guide: only Stand-alone ventilation is defined. The guide does not say whether integrated records consume the linked delivery, so multiple records on one delivery read as a conflict, and an integrated record on a conditioned delivery reads as a conditioned DOAS.
- BOSS behavior: records with `Integration` `Integrated with central air distribution` or `Integrated with local air distribution` do not consume deliveries; they return `integrated`, and the linked deliveries are selected as conditioning deliveries.
- Ask: add this rule to the guide. `DemandControlVentilation` and `VentilationRate` on these records may later feed a modifier mapping.

### 6. `VentilationType None` or untyped ventilation on conditioned deliveries

- Data: ASHRAE L1/L2 exports (`Chula_Vista_ASHRAE_L*`, `Demo_ASHRAE_L2_Example_Building.xml`, `Example_ASHRAE_L2_Report_-_with_Energy_Use_Data*.xml`, `Example_HOMES_Template_Building.xml`, NYC files). `OtherHVACSystem` with only `MechanicalVentilation` (`VentilationType None` or none, optional `DemandControlVentilation`) links conditioned deliveries.
- Guide: the Explicitly no HVAC row covers only unconditioned deliveries; other cases are undefined.
- BOSS behavior: such records consume deliveries only when all linked deliveries are explicitly unconditioned. Otherwise the deliveries are selected as conditioning deliveries, and the record returns `no_hvac` (`None`) or `missing_input` (no type).
- Ask: add this rule to the guide.

### 7. Premises linked only on `HVACSystem`

- Data: every v2.7.0 fixture with detailed records links `LinkedPremises` on `HVACSystem`, not on `Delivery` or `OtherHVACSystem`.
- Guide: `zones(D)` and `zones(O)` come from the record's own links.
- BOSS behavior: a record without its own links inherits the parent `HVACSystem` links.
- Ask: add the fallback to the guide.

## Resolved Later

### 8. DX cooling source without a condenser plant

- Data: `example-smalloffice-level2.xml`, all five DX sources (`DXSystemType = Packaged/unitary heat pump`) omit `CondenserPlantIDs`.
- Guide: packaged and PTAC/PTHP/VRF rows require the DX condenser to resolve to an `AirCooled` condenser plant, so these deliveries identify no configuration.
- Ask: decide whether a packaged or terminal DX source without a condenser reference may be treated as air-cooled, or confirm it stays missing input.
- Resolution: packaged and terminal DX rows (PTAC, PTHP, packaged rooftop AC/HP/VAV) read an omitted `DX/CondenserPlantIDs` as air-cooled; a supplied reference must still resolve to a non-evaporative `AirCooled` condenser. VRF still requires the reference.
9 changes: 8 additions & 1 deletion docs/scenario_workflow_translation_plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -278,12 +278,19 @@ Use this roadmap as the tracker. Keep `Status` and `Delivered by` current when a

### PR 14B: HVAC Selection Contract

- Status: Planned
- Status: In progress
- 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.
- Implementation: `BOSS::HvacTopologySelector` (`lib/BOSS/hvac_topology_selector.rb`) returns one result per conditioning `Delivery` and per `OtherHVACSystem`, with status `match`, `mapping_gap`, `not_mappable`, `missing_input`, `conflicting_input`, or `no_hvac`, the `LinkedPremises` references, and a `group_key` (delivery, cooling source, plant tuple, or other-system ID). Family-only `PrincipalHVACSystemType` data returns `missing_input`.
- Deferred to later steps: guards comparing `Quantity` with zone counts and the premises-containment checks need the model crosswalk (PR 14C). Group-member consistency, zone-overlap checks, plant-binding limits, call ordering, and scenario `@Status` record selection belong to call construction (PR 14D/14E). `DuctSystems` checks are not implemented yet.
- Fixture follow-ups (found in PR 14D): a `Delivery` or `OtherHVACSystem` without its own `LinkedPremises` inherits the parent `HVACSystem` links (BuildingSync fixtures link premises only there; the upstream guide reads the record's own links). An `OtherHVACSystem` whose only content is `MechanicalVentilation` with `VentilationType` `None` or no type names no ventilation equipment; it owns its linked deliveries only when all of them are explicitly unconditioned. Otherwise those deliveries are selected as conditioning deliveries, and the record returns `no_hvac` (`None`, configuration "No separate ventilation equipment") or `missing_input` (no type). Fixture effect: ASHRAE-L2-style deliveries are now selected but return `conflicting_input`, because their `SourceHeatingPlantID` points to a plant in a different `HVACSystem` (cross-system plant references are not resolved yet). Whether the baseline planner may ignore `no_hvac` records is a PR 14D decision.
- 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.

### PR 14C: Model Target Binding

Expand Down
Loading
Loading