mirror of
https://github.com/Hestia-Homes/Model.git
synced 2026-06-08 11:17:27 +00:00
7e79c30af1
`PlanMeasure` grows optional `kwh_savings` (delivered energy) and `energy_cost_savings` (£) — its slice of the telescoping bill cascade, signed so positive is a saving and `None` until billing runs. `RecommendationRow` declares the matching live `recommendation.kwh_savings` / `energy_cost_savings` columns and maps them in `from_domain` (None → NULL). The vestigial `recommendation.energy_savings` stays undeclared (legacy = 0). No FE migration — the columns already exist on the live table (ADR-0014 / 0017). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
125 lines
5.1 KiB
Python
125 lines
5.1 KiB
Python
"""Plan and Plan Measure — the Modelling stage's persisted output (ADR-0017).
|
||
|
||
A **Plan** is the per-Property output of one Scenario's modelling run: the
|
||
selected **Optimised Package** (its **Plan Measures**) plus the Property's
|
||
post-retrofit figures. It is single-phase — multi-phase is deferred
|
||
(ADR-0005) — so the headline figures are flat on the Plan.
|
||
|
||
A **Plan Measure** is the *output* counterpart of a Recommendation's candidate
|
||
Option: the one Option the Optimiser kept, frozen with its installed **Cost**
|
||
and its final-package (role-3) attributed **impact**. See CONTEXT.md.
|
||
"""
|
||
|
||
from dataclasses import dataclass
|
||
from typing import Optional
|
||
|
||
from datatypes.epc.domain.epc import Epc
|
||
from domain.billing.bill import Bill
|
||
from domain.modelling.scoring.package_scorer import Score
|
||
from domain.modelling.recommendation import Cost
|
||
from domain.modelling.scoring.scoring import MeasureImpact
|
||
|
||
|
||
def _total_consumption_kwh(bill: Bill) -> float:
|
||
"""A Bill's total delivered energy (kWh) — the sum of its section kWh
|
||
(standing charges and the SEG credit are £, not energy)."""
|
||
return sum((section.kwh for section in bill.sections.values()), 0.0)
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class PlanMeasure:
|
||
"""One selected Measure Option as it lands in a Plan: the measure, its
|
||
installed Cost, and its role-3 (final-package cascade) attributed impact.
|
||
|
||
`kwh_savings` (delivered energy) and `energy_cost_savings` (£) are this
|
||
measure's slice of the telescoping bill cascade — its marginal Bill delta
|
||
over the running package state. They can be negative (e.g. ventilation
|
||
increases energy) and telescope exactly to the Plan totals; `None` until
|
||
billing has run (persisted as NULL — ADR-0014 amendment). They are distinct
|
||
from `impact.energy_savings_kwh_per_yr`, which is *primary* energy."""
|
||
|
||
measure_type: str
|
||
description: str
|
||
cost: Cost
|
||
impact: MeasureImpact
|
||
kwh_savings: Optional[float] = None
|
||
energy_cost_savings: Optional[float] = None
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class Plan:
|
||
"""A Property's Plan for one Scenario: the selected Plan Measures and the
|
||
baseline / post-retrofit whole-package Scores. The persisted headline
|
||
figures are derived from these (cost aggregates, CO₂ saving, post band).
|
||
|
||
`baseline_bill` / `post_bill` are the Bills derived (at one Fuel Rates
|
||
snapshot) for the unmodified and post-package end-states; the energy/bill
|
||
headline figures derive from them, and are `None` until billing has run
|
||
(persisted as NULL — ADR-0014 amendment)."""
|
||
|
||
measures: tuple[PlanMeasure, ...]
|
||
baseline: Score
|
||
post_retrofit: Score
|
||
baseline_bill: Optional[Bill] = None
|
||
post_bill: Optional[Bill] = None
|
||
|
||
@property
|
||
def cost_of_works(self) -> float:
|
||
"""Sum of the Plan Measures' fully-loaded Costs."""
|
||
return sum((measure.cost.total for measure in self.measures), 0.0)
|
||
|
||
@property
|
||
def contingency_cost(self) -> float:
|
||
"""Sum of each Plan Measure's contingency (its Cost total × its
|
||
per-Measure-Type contingency rate)."""
|
||
return sum(
|
||
(
|
||
measure.cost.total * measure.cost.contingency_rate
|
||
for measure in self.measures
|
||
),
|
||
0.0,
|
||
)
|
||
|
||
@property
|
||
def post_sap_continuous(self) -> float:
|
||
"""The whole-package re-score's un-rounded SAP rating."""
|
||
return self.post_retrofit.sap_continuous
|
||
|
||
@property
|
||
def post_epc_rating(self) -> Epc:
|
||
"""The post-retrofit EPC band, from the rounded SAP rating."""
|
||
return Epc.from_sap_score(round(self.post_retrofit.sap_continuous))
|
||
|
||
@property
|
||
def co2_savings_kg_per_yr(self) -> float:
|
||
"""Whole-package CO₂ reduction (kg/yr) vs the baseline re-score. The
|
||
persistence mapper converts to tonnes for the live column contract."""
|
||
return self.baseline.co2_kg_per_yr - self.post_retrofit.co2_kg_per_yr
|
||
|
||
@property
|
||
def post_energy_bill(self) -> Optional[float]:
|
||
"""The post-package annual energy bill (£), or None if not billed."""
|
||
return None if self.post_bill is None else self.post_bill.total_gbp
|
||
|
||
@property
|
||
def energy_bill_savings(self) -> Optional[float]:
|
||
"""Annual bill reduction (£) vs the baseline bill, both at the same Fuel
|
||
Rates snapshot. None unless both bills were derived."""
|
||
if self.baseline_bill is None or self.post_bill is None:
|
||
return None
|
||
return self.baseline_bill.total_gbp - self.post_bill.total_gbp
|
||
|
||
@property
|
||
def post_energy_consumption(self) -> Optional[float]:
|
||
"""The post-package total delivered energy (kWh), or None if not billed."""
|
||
return None if self.post_bill is None else _total_consumption_kwh(self.post_bill)
|
||
|
||
@property
|
||
def energy_consumption_savings(self) -> Optional[float]:
|
||
"""Annual delivered-energy reduction (kWh) vs the baseline. None unless
|
||
both bills were derived."""
|
||
if self.baseline_bill is None or self.post_bill is None:
|
||
return None
|
||
return _total_consumption_kwh(self.baseline_bill) - _total_consumption_kwh(
|
||
self.post_bill
|
||
)
|