Envelope U-value film convention: OSut path (with films, code-literal) vs BTAP path (construction-only) disagree by ~4% on the same Table 3.2.2.2 values

[phylroy]

Authorship note: this analysis and report were written by Claude (Anthropic's AI assistant) during the NECB compliance-gem validation effort in this repository, and submitted from the repository owner's account at their direction.

Two construction paths coexist in the NECB code and disagree by ~4% on what a Table 3.2.2.2 U-value means:

• OSut path (add_construction_sets → TBD.genConstruction, used by the NECB2020 prototypes): uo is the "desired Uo factor (with air film resistance)" — the table value is treated as overall transmittance including films (wall film 0.150, roof 0.140 m²·K/W). A generated NECB2020 archetype wall carries construction-only conductance 0.276 for the 0.265 table value.
• BTAP path (apply_standard_construction_properties → customize_opaque_construction → setConductance): the table value is applied as construction-only conductance (films excluded) — the same wall comes out at 0.265, ~4% more insulation than the OSut path.

The NECB 1.4.1.2 definition supports the OSut reading: overall thermal transmittance "reflects the capacity of all elements to transfer heat through the thickness of the assembly, as well as, for instance, through air films on both faces of above-ground components."

Same code, same table, two different buildings depending on which API a caller reaches — and the BTAP path is the over-stringent, non-code-literal one. Suggest aligning customize_opaque_construction/apply_standard_construction_properties to subtract film resistances (or at minimum documenting the convention on both APIs).

Verification detail: the film arithmetic reproduces generated archetype values exactly — 1/(1/0.265 − 0.150) = 0.276 (wall), 1/(1/0.156 − 0.140) = 0.159 (roof), and archetype SimpleGlazing windows correctly carry the table value verbatim (1.9/2.69 — NFRC U-factors already include films).

🤖 Generated with Claude Code

[brgix]

Not arguing against the actual claims made here on the current BTAP Path outcomes - haven't yet checked. However, some of the AI observations may be dealing with the following issues/fixes. The initial AI-observed differences may be (unintentionally, in part) addressed once the following changes are merged with nrcan branch.

There is a workaround/fix in the works (branch nrcan_468b) to a known OpenStudio SDK/API issue, dealing with insulated interzone constructions (e.g. insulated attic floor). This is also related to upcoming BTAP changes discussed here. The fix involves:

• OSut gem workaround issue & PR fix - re-released in April 2026.
• follow-up integration with the TBD gem - re-released in April 2026.
• relying on the above, a new NECB function that returns a construction's air film resistances (surface area-weighted).
• relying on the above, a new BTAP function that sets (as a construction's AdditionalProperty, "btap_film") surface area-weighted air film resistances for each insulated construction.

AdditionalProperties "btap_film" (in addition to "btap_uo", "btap_ut", "btap_type") also provide support for post-simulation BTAP processes (like costing, embodied carbon estimates).

In a nutshell: Once these fixes are finally merged with nrcan branch, these AI-observations may need to be re-assessed.

[phylroy]

Authorship note: this comment, like the issue body, was written by Claude (Anthropic's AI assistant) and submitted from @phylroy's account for access reasons.

A second instance of the same two-paths divergence, this time on Table 3.2.3.1 (ground floors) rather than the film convention:

The printed NECB 2020/2025 table is zone-conditional for floors in contact with the ground: "0.757 for 1.2 m" in zones 4–7B (a perimeter strip per Sentence 3.2.3.3.(3) — the slab field carries no prescriptive maximum) vs "0.379 for full area" in zone 8. The two legacy construction paths each implement a different simplification, and they disagree with each other:

• the OSut archetype path models the slab bare in zones 4–7B with no perimeter strip at all (under-insulated vs 3.2.3.3.(3)); zone 8 full-area is correct (U 0.403 construction-only = 0.379 with the interior film stripped);
• the BTAP apply_standard_construction_properties path applies the 0.757 strip value over the full slab area in zones 4–7B (over-insulated — there is no full-area requirement below zone 8).

The strip is not a rounding error: on the NECB2020 Warehouse archetype (4,598 m² slab, Toronto, January week, Kiva foundations) the measured opaque-conduction difference between "bare slab" and "bare slab + code strip" is ~6.7 GJ/wk — the 1.2 m strip recovers roughly 70% of what full-slab insulation would, because with 2D ground heat transfer the perimeter dominates. Full-area application over-counts by the remaining ~3 GJ/wk.

A faithful implementation is straightforward where Kiva foundations are used: leave the slab construction alone in zones 4–7B and set the Foundation:Kiva interior horizontal insulation fields (material R sized so the strip assembly meets the 0.757 overall U, width 1.2 m); keep the full-area retarget only at zone 8.

Found during fixed-point validation of NECB2020 archetypes (end-use isolation → heat-balance decomposition → object diff over Foundation surfaces); table text verified against the printed 2020 and 2025 editions (identical).

[brgix]

This is correct. Continuous slab-on-grade insulation is only required for NECB Climate Zone 8. The revised BTAP approach (what the AI agent refers to as the "OSut archetype path") correctly removed continuous insulation from slab-on-grade layered constructions - good! Yet as BTAP already relied on KIVA, it was (incorrectly) presumed that perimeter insulation was added later in BTAP. This oversight was identified a few weeks later (Spring 2026). There is a planned fix to introduce perimeter insulation (via BTAP's use of KIVA). Costing takeoffs also need adjustments. This should be completed by the end of the summer.