mirror of
https://github.com/Hestia-Homes/Model.git
synced 2026-06-30 13:10:47 +00:00
6 commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Khalim Conn-Kowlessar
|
39ae2cf0c2 |
fix(water-heating): split whc-903 immersion HW CO2/PE on off-peak tariffs
SAP 10.2 Table 12d/12e: electric water heating on a 7-/10-hour tariff bills CO2/PE at the high-rate code (32/34) and low-rate code (31/33), kWh-weighted by the Table 13 high-rate fraction. The cost path already applied this split; the CO2/PE factors did not — they used the flat annual Table 12 figure (0.136 CO2 / 1.501 PE) for ALL dual-rate electric HW. That flat-annual behaviour (slice S0380.163) was validated only against HW-from-main "low-rate cost" certs (100% low, no high-rate split). It is NOT how Elmhurst bills a whc-903 ELECTRIC IMMERSION: the hand-built case-50 worksheet (000565 + dual immersion, 7-hour) splits HW CO2/PE into "high rate cost" (CO2 0.1475 / PE 1.5514) + "low rate cost" (CO2 0.1238 / PE 1.4429) weighted by the Table 13 fraction 0.1009. So flat-0.136 for immersion HW was a spec gap on our side, not an Elmhurst divergence. Fix: `_electric_immersion_hw_high_rate_fraction` threads the Table 13 fraction (scoped to whc-903, 7-/10-hour, cylinder data present) into the HW CO2 + PE factor helpers, which then blend the Table 12d/12e high/low codes. The flat rule is unchanged for HW-from-main and 18-/24-hour (no Table 12d split), so the S0380.163 41-variant cases and the existing pin are untouched. Case 50: rating CO2 2413.48 -> 2397.1237 = Elmhurst EXACT; demand CO2 2007.1384 EXACT; demand PE +111 -> +32.5 residual (within corpus PE noise). Corpus unchanged 73.3% / MAE 0.774 / CO2 0.08 / PE 3.4 (62 whc-903 off-peak certs; aggregate gauges hold). SAP unaffected (cost-based). Pin: test_whc903_immersion_hw_co2_pe_factors_split_high_low_on_off_peak; doc updated in SAP_CALCULATOR.md §8.1. pyright strict gate not run locally (pyright not installed in this container). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> |
||
|
Khalim Conn-Kowlessar
|
1382c8c886 |
docs: add AGENT_GUIDE.md — fresh-start onboarding for the SAP calculator
A single durable doc so agents can pick up the calculator without reading historical handovers: (1) the accuracy bar for the two input paths (site-notes 1e-4 vs worksheet; API 1e-4 when a worksheet exists, ±0.5 register fallback otherwise; cross-mapper parity); (2) the per-line-walk debugging loop incl. comparing site-notes vs API; (3) the tools & pipeline (Summary PDF → extractor → from_elmhurst_site_notes → cert_to_inputs → calculate_sap_from_inputs → SapResult, plus the API from_api_response front-end, section helpers, and where the test vectors live). Pointer added from SAP_CALCULATOR.md; HANDOVER_* flagged as point-in-time notes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> |
||
|
Khalim Conn-Kowlessar
|
8e86de2257 |
S0380.182: community-heating CHP+boilers CO2/PE credit (§12b/13b) — closes CH2/CH4 CO2+PE
SAP 10.2 worksheet block 12b (CO2) / 13b (PE) for community heating
"CHP and boilers" (SAP code 302). Per unit of network heat fuel
H = (307)+(310) the effective generation factor is:
chp×100/(362)×f_fuel − chp×(361)/(362)×f_disp + (1−chp)×100/(367)×f_fuel
(363)/(463) CHP fuel = chp_frac × 100/heat_eff × f_fuel
(364)/(464) less credit = −chp_frac × elec_eff/heat_eff × f_disp
(368)/(468) boiler fuel = (1−chp_frac) × 100/boiler_eff × f_fuel
f_fuel = Table 12 heat-network fuel factor (the CHP unit and the back-up
boilers burn the same community fuel — verified vs CH2 gas / CH4 oil /
CH6 coal worksheets (363)/(368)); f_disp = Table 12f (PDF p.196) credit
for the CHP-generated electricity. RdSAP 10 §C (p.58) defaults: heat eff
50% (362), electrical eff 25% (361), boiler eff 80% (367); CHP heat frac
0.35 per-cert via community_heating_chp_fraction.
New `_heat_network_code_302_effective_factor` + Table 12f flexible
constants (0.420 CO2 / 2.369 PE) + RdSAP §C efficiency constants, wired
into all four factor helpers (main + HW, CO2 + PE) ahead of the existing
single-fuel / 1-over-heat-source-eff path. The worksheet (368)/(468)
boiler emissions DISPLAY rounded/mis-aligned in the PDF, but the
(373)/(473)/(386)/(486) totals reconcile only with the boiler at the
full Table 12 factor — verified EXACT.
Two spec citations applied:
- Table 12f flexible-operation default for RdSAP community CHP is an
Elmhurst engine choice (Table 12f notes make "standard" the default);
mirrored per [[feedback-software-no-special-handling]] and documented
in SAP_CALCULATOR.md §8.3.
- Table 12 heat-network oil/biodiesel CO2 (codes 53/56) corrected
0.298 → 0.335 per Table 12 (p.189) "assumes 'gas oil'"; the code-302
oil cascade (CH4) was the first to exercise it. PE 1.180 was already
correct. No other variant uses these codes (no regression).
Closures (CO2 + PE only — the CHP credit does not touch cost/SAP):
CH2 (CHP/Gas) CO2 −1411.49→+0.0000, PE +1331.23→+0.0000 EXACT
CH4 (CHP/Oil) CO2 −4378.24→−0.0000, PE +319.81→−0.0000 EXACT
CH6 (CHP/Coal) CO2/PE re-pinned (+2411.54 / +5023.48) — its worksheet
lodges a manual DLF=1.0 the Summary doesn't carry, so
cascade DLF=1.45 over-scales H; same root as the CH6
SAP −7.49 / cost +£172 (separate DLF front).
CH2/CH4 are now CO2+PE-exact but still carry the heat-network cost/SAP
residual (+0.5277 SAP / −£12.16 cost, exposed by S0380.175 — cost-side,
untouched here). CH3 unchanged (code 304 community-HP COP front).
Corpus state: 37 variants EXACT on all four metrics (incl. CH1);
remaining residuals are CH2/CH4 cost+SAP, CH3 CO2+PE (HP COP), CH6
all-metric (DLF quirk). 2223 pass + 1 skip + 0 fail (tolerances 1e-4 all
metrics per S0380.181); pyright net-zero 43→43.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
||
|
Khalim Conn-Kowlessar
|
302db131c6 |
Slice S0380.164: Elmhurst-mirror §12.4.4 summer-immersion CO2/PE double-count
SAP 10.2 §12.4.4 (PDF p.36-37): "With open fire back boilers or closed
room heaters with boilers, an alternative system (electric immersion)
may be provided for heating water in summer. In that case water
heating is provided by the boiler for months October to May and by the
alternative system for months June to September."
The spec-literal CO2 / PE formula multiplies summer immersion fuel by
the Table 12d / 12e monthly cascade (per Table 12 footnotes (s) and
(t): "monthly factors in Table 12d/12e should be used in the SAP
worksheet"). The BRE-approved Elmhurst engine adds an extra
`summer_fuel × Table 12 annual electric` term ON TOP of the monthly
cascade for dual-rate tariffs — same Elmhurst-mirror shape as S0380.163
(§8.1) but additive rather than substitutive. Cost is computed
cleanly per spec — the double-count quirk only affects the (264) HW
CO2 and (278) HW PE factor lines.
Worksheet evidence (heating-systems corpus property 001431,
`solid fuel 2` — Table 4a code 158 closed-room-heater + back boiler,
65 % winter η + 100 % summer η, anthracite, 18-hour off-peak tariff):
(62)m heat 303.12 .. 168.95 .. 175.91 .. 300.40 kWh
winter fuel (W) = 2205.80 / 0.65 = 3393.51 kWh anthracite
summer fuel (S) = 684.55 / 1.00 = 684.55 kWh immersion
total fuel = (219) = 4078.06 kWh
(264) HW CO2 = 4078.06 × 0.3710 = 1513.15 kg/yr
= W × 0.395 + S × (0.116 monthly_summer + 0.136 annual)
= 1340.43 + 79.61 + 93.10 = 1513.14 ✓ within rounding
(278) HW PE = 4078.06 × 1.3771 = 5616.04 kWh/yr
= W × 1.064 + S × (1.429 monthly_summer + 1.501 annual)
= 3610.69 + 977.84 + 1027.51 = 5616.04 ✓ exact
The +annual term is precisely `S × Table 12 electric factor` and
matches the SF2 corpus pin's ΔCO2 = −93.10 and ΔPE = −1027.51 exactly.
Per [[feedback-software-no-special-handling]] mirror the engine.
Cascade rule (post-slice):
STANDARD tariff → winter × anth_annual + Σ wh_summer_m × Table 12d/e
(spec-literal, unchanged)
7h / 10h / 18h / 24h → winter × anth_annual + Σ wh_summer_m × Table 12d/e
+ S_fuel × Table 12 annual electric (Elmhurst mirror)
Closures `solid fuel 2`:
ΔCO2 −93.10 → +0.0000 EXACT
ΔPE −1027.51 → +0.0000 EXACT
ΔSAP and Δcost remain EXACT (cascade cost path was already correct).
The 41-variant heating-systems corpus is now closed on its 25-variant
cascade-OK tier: all 25 SAP / cost / CO2 / PE EXACT (|Δ| < 1e-3) vs
the Elmhurst worksheet. Only `pcdb 1` carries a sub-tolerance gap
(−0.011 SAP / +5.7 PE — PCDB Eq D1 cascade gap on PCDF index 716, a
separate small slice).
⚠ Single-cert evidence
SF2 is the only §12.4.4 fixture in the corpus (`solid fuel 1` =
code 156 is an empty folder; no other variant exercises a back-boiler
combo with summer immersion). Per the handover ≥2-cert rule for new
§8 divergence rows, this slice was admitted under an explicit
exception: the divergence shares its shape with §8.1 (S0380.163's
Table 12 annual mirror for dual-rate HW), and the math matches the
worksheet to within rounding. The new §8.2 row is tagged with a
"⚠ Single-cert evidence" subsection so future agents know to revisit
if a second §12.4.4 cert worksheet ever diverges from this rule.
Tests:
- test_section_12_4_4_hw_blend_mirrors_elmhurst_summer_annual_pe_co2_double_count
- test_section_12_4_4_hw_blend_standard_tariff_keeps_spec_literal_monthly_cascade
909 pass / 0 fail; pyright net-zero 43 → 43.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
||
|
Khalim Conn-Kowlessar
|
9896644c4c |
Slice S0380.163: Elmhurst-mirror HW PE/CO2 factor on dual-rate tariffs
SAP 10.2 Table 12 footnote (t) (PDF p.189): "PE factors for grid
electricity vary by month. The average figure given in this table is
therefore not used directly. Instead the monthly factors given in
Table 12e should be used in the SAP worksheet." Footnote (s) says the
same for CO2 / Table 12d. Read literally, monthly factors apply to
every electric end-use including dual-rate HW.
The BRE-approved Elmhurst rdSAP engine doesn't follow that reading
for HW. The 41-variant heating-systems corpus controlled-variable
fixture lodges worksheet (278) "Water heating (low-rate cost)" with
factor **1.5010 PE / 0.136 CO2** (Table 12 annual flat) across every
dual-rate tariff cert, while applying the monthly Table 12e/12d
cascade to lighting (1.5338 winter-weighted) and secondary heating
(1.5715) on the same certs. It's an engine implementation choice,
not a documented spec exception.
Per [[feedback-software-no-special-handling]] the calculator
contract is bit-faithful replication of the engine, not literal
compliance with the spec text. This slice flips cascade
`_hot_water_primary_factor` + `_hot_water_co2_factor_kg_per_kwh` to
accept a `tariff: Tariff` parameter:
- STANDARD tariff → Table 12e/12d monthly cascade weighted
by HW demand seasonality (unchanged from
S0380.71 / .72, matches cohort-1 ASHP
standard-tariff worksheet)
- 7-hour / 10-hour /
18-hour / 24-hour → Table 12 annual flat (1.501 / 0.136)
matching the Elmhurst worksheet (278)
"Water heating (low-rate cost)" row
Per-line walk on electric 3 (18-hour tariff, electric immersion HW,
2384.116 kWh annual):
worksheet (278) factor = 1.5010
cascade pre-slice = 1.5214 delta = +0.0204
(1.5214 - 1.5010) × 2384.116 = +48.66 kWh/yr PE — EXACT match
the corpus residual pin.
Same shape for CO2: worksheet 0.1360, cascade pre-slice 0.1410,
delta +0.0050 × 2384.116 = +11.95 kg/yr.
Closures across the 18-variant deferred lighting-PE cohort
(electric 1/2/3/5/6/7/8/9 + solid fuel 4/5/6/7/8/9/10/11 + ashp +
gshp):
ΔCO2 +6.31 / +11.95 → ±0.0000 EXACT
ΔPE +25.51 / +48.66 → ±0.0000 EXACT
ΔSAP_c / Δcost unchanged at ±0.0000 EXACT (already closed
pre-slice by S0380.156..162).
All 25 cascade-OK variants in the heating-systems corpus now
SAP / cost / CO2 / PE EXACT vs worksheet on all 4 metrics, with
solid fuel 2 as the only remaining open residual (separate
S0380.154 summer-immersion-blend CO2/PE artifact — deferred).
Documented in
`domain/sap10_calculator/docs/SAP_CALCULATOR.md §8.1
"HW PE/CO2 factors on dual-rate tariffs use Table 12 annual"` —
the master doc now carries a new §8 "Elmhurst-mirrored spec
divergences" section for cases like this. Validation tally
refreshed from stale "930/930" to current "941/941".
No regressions on the 6 Elmhurst U985 fixtures (gas combi
STANDARD tariff — unaffected) or the cohort-1 ASHP certs
(STANDARD tariff — unaffected). The dual-rate gate fires only
on the 4 off-peak tariffs.
Verbatim spec quote retained for reference (SAP 10.2 Table 12
footnote (t), PDF p.189):
"PE factors for grid electricity vary by month. The average
figure given in this table is therefore not used directly.
Instead the monthly factors given in Table 12e should be used
in the SAP worksheet."
Tests: 907 pass (+1), 0 fail. Pyright net-zero (43 → 43).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
||
|
Khalim Conn-Kowlessar
|
a7b08a4e8f |
refactor: move docs/sap-spec/ contents into domain/sap10_calculator/
Locality of reference — SAP-specific docs, specs, and runtime data
now live alongside the calculator that consumes them, mirroring the
prior packages→domain layout moves.
Move targets:
- Narrative MDs → domain/sap10_calculator/docs/
NEXT_AGENT_PROMPT.md, HANDOVER_NEXT.md, SAP_CALCULATOR.md
- Spec PDFs → domain/sap10_calculator/docs/specs/
RdSAP 10 Specification 10-06-2025.pdf
PCDF_Spec_Rev-06b_12_May_2021.pdf
sap-10-2-full-specification-2025-03-14.pdf
sap-10-3-full-specification-2026-01-13.pdf
- PCDB runtime data → domain/sap10_calculator/tables/pcdb/data/
pcdb10.dat (8.3MB) + 7× pcdb_table_*.jsonl (18MB total)
Path code rewrites (load-bearing):
- tables/pcdb/__init__.py: replaced parents[4]/'docs'/'sap-spec' with
Path(__file__).resolve().parent/'data' for Table 105 JSONL loading.
- tables/pcdb/postcode_weather.py: same rebase for the pcdb10.dat path
read by _postcode_climate_table().
- tables/pcdb/etl.py __main__: same rebase for the manual ETL invocation
(source + output_dir both now point inside the package).
- tests/test_pcdb_etl.py: _PCDB_DAT_PATH now derives from
parents[1]/'tables'/'pcdb'/'data' (was parents[3]/'docs'/'sap-spec').
Citation rewrites:
- 12 .py docstrings and 4 .md docs (ADRs + READMEs + narrative docs)
had `docs/sap-spec/<file>` strings rewritten to their new locations.
- Two cases where the catch-all sed misfired (an ADR-0009 line about a
PCDB extract; the pcdb __init__.py docstring about ETL output) were
hand-corrected to point at tables/pcdb/data/ rather than docs/specs/.
docs/sap-spec/ is now empty (will be removed in a follow-up sweep or
left as a vestigial empty dir for future repurposing). ADRs 0009 and
0010 remain at docs/adr/ — they're part of the chronological
cross-cutting decision log, not calculator-specific narrative.
Verified:
- Calculator's 1e-4 production gate
(test_api_001479_full_chain_sap_matches_worksheet_pdf_exactly) GREEN.
- Wider sweep (domain/sap10_calculator/ + domain/sap10_ml/): 1654
passed / 20 failed — exact pre-move baseline. All 20 failures
pre-existing (10 hand-built skeleton + 4 cohort chain + 6 cohort
diff).
- Pyright net-zero on the 4 touched runtime/test files (0 errors)
and unchanged on heat_transmission.py (13) / cert_to_inputs.py (35) /
mapper.py (33).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
Renamed from docs/sap-spec/SAP_CALCULATOR.md (Browse further)