Model/domain/modelling/scoring/overlay_applicator.py

"""The Overlay Applicator — folds an ordered set of Simulation Overlays onto
a baseline EpcPropertyData and returns a new one for the calculator.

Sequential fold: overlays are applied in order and a later overlay wins on a
field it shares with an earlier one. The baseline is never mutated; the
returned EpcPropertyData is throwaway (handed to the calculator for scoring,
then discarded). See ADR-0016.
"""

import copy
from dataclasses import fields
from typing import Optional, Sequence

from datatypes.epc.domain.epc_property_data import (
    EpcPropertyData,
    SapVentilation,
    SapWindow,
    WindowTransmissionDetails,
)
from domain.modelling.simulation import (
    EpcSimulation,
    HeatingOverlay,
    LightingOverlay,
    VentilationOverlay,
    WindowOverlay,
)


def apply_simulations(
    baseline: EpcPropertyData, simulations: Sequence[EpcSimulation]
) -> EpcPropertyData:
    """Return a copy of ``baseline`` with every Simulation Overlay's non-``None``
    fields written onto the building part it targets, applied in order. A
    whole-dwelling ``ventilation`` overlay folds onto ``sap_ventilation``
    (creating one if the baseline lodged none)."""
    result: EpcPropertyData = copy.deepcopy(baseline)
    parts_by_id = {part.identifier: part for part in result.sap_building_parts}

    for simulation in simulations:
        for identifier, overlay in simulation.building_parts.items():
            part = parts_by_id[identifier]
            for overlay_field in fields(overlay):
                value = getattr(overlay, overlay_field.name)
                if value is not None:
                    setattr(part, overlay_field.name, value)
        for index, window_overlay in simulation.windows.items():
            _fold_window(result.sap_windows[index], window_overlay)
        if simulation.ventilation is not None:
            result.sap_ventilation = _fold_ventilation(
                result.sap_ventilation, simulation.ventilation
            )
        if simulation.lighting is not None:
            _fold_lighting(result, simulation.lighting)
        if simulation.heating is not None:
            _fold_heating(result, simulation.heating)

    return result


# `HeatingOverlay` fields grouped by the object they target — the deepest fold,
# spanning the primary `MainHeatingDetail`, `sap_heating`, the top-level
# `EpcPropertyData`, and `sap_energy_source` (ADR-0024).
_MAIN_HEATING_FIELDS: tuple[str, ...] = (
    "main_fuel_type",
    "heat_emitter_type",
    "main_heating_control",
    "sap_main_heating_code",
    "main_heating_index_number",
    "main_heating_category",
)
_SAP_HEATING_FIELDS: tuple[str, ...] = (
    "water_heating_code",
    "water_heating_fuel",
    "cylinder_size",
    "cylinder_insulation_type",
    "cylinder_insulation_thickness_mm",
)
_ENERGY_SOURCE_FIELDS: tuple[str, ...] = ("meter_type", "mains_gas")


def _fold_heating(epc: EpcPropertyData, overlay: HeatingOverlay) -> None:
    """Write a `HeatingOverlay`'s non-``None`` fields onto the (copied) dwelling,
    routing each to its home: the primary ``main_heating_details[0]``, the
    ``sap_heating`` hot-water fields, the top-level ``has_hot_water_cylinder``,
    and the ``sap_energy_source`` meter/mains-gas fields. The bundle targets the
    primary system only (index 0)."""
    main = epc.sap_heating.main_heating_details[0]
    for field_name in _MAIN_HEATING_FIELDS:
        value = getattr(overlay, field_name)
        if value is not None:
            setattr(main, field_name, value)
    for field_name in _SAP_HEATING_FIELDS:
        value = getattr(overlay, field_name)
        if value is not None:
            setattr(epc.sap_heating, field_name, value)
    if overlay.has_hot_water_cylinder is not None:
        epc.has_hot_water_cylinder = overlay.has_hot_water_cylinder
    for field_name in _ENERGY_SOURCE_FIELDS:
        value = getattr(overlay, field_name)
        if value is not None:
            setattr(epc.sap_energy_source, field_name, value)


def _fold_lighting(epc: EpcPropertyData, overlay: LightingOverlay) -> None:
    """Write a `LightingOverlay`'s non-``None`` bulb counts onto the (copied)
    dwelling's top-level fields by name — the four counts live directly on
    `EpcPropertyData`, so the fold writes onto it, not a nested object."""
    for overlay_field in fields(overlay):
        value = getattr(overlay, overlay_field.name)
        if value is not None:
            setattr(epc, overlay_field.name, value)


def _fold_window(window: SapWindow, overlay: WindowOverlay) -> None:
    """Write a `WindowOverlay`'s non-``None`` fields onto a (copied) window:
    ``glazing_type`` flat on the window, ``u_value`` / ``solar_transmittance``
    into its `WindowTransmissionDetails` (where the cascade reads them), starting
    a fresh one when the window lodged none."""
    if overlay.glazing_type is not None:
        window.glazing_type = overlay.glazing_type
    if overlay.u_value is None and overlay.solar_transmittance is None:
        return
    details: Optional[WindowTransmissionDetails] = window.window_transmission_details
    if details is None:
        # data_source 1 = manufacturer-lodged (the case the cascade's per-window
        # U path keys on); both values must be present to start fresh.
        window.window_transmission_details = WindowTransmissionDetails(
            u_value=overlay.u_value if overlay.u_value is not None else 0.0,
            data_source=1,
            solar_transmittance=(
                overlay.solar_transmittance
                if overlay.solar_transmittance is not None
                else 0.0
            ),
        )
        return
    if overlay.u_value is not None:
        details.u_value = overlay.u_value
    if overlay.solar_transmittance is not None:
        details.solar_transmittance = overlay.solar_transmittance


def _fold_ventilation(
    baseline: Optional[SapVentilation], overlay: VentilationOverlay
) -> SapVentilation:
    """Write the overlay's non-``None`` fields onto a (copied) ``SapVentilation``,
    starting a fresh one when the baseline lodged none."""
    folded: SapVentilation = (
        copy.deepcopy(baseline) if baseline is not None else SapVentilation()
    )
    for overlay_field in fields(overlay):
        value = getattr(overlay, overlay_field.name)
        if value is not None:
            setattr(folded, overlay_field.name, value)
    return folded