"""Reconcile reported curtailed *potential* energy and screen recovery ceilings.
The method operates on published GWh aggregates. It neither infers ONS
restriction causes nor simulates battery operation or recoverable electricity.
"""
from __future__ import annotations
import math
from collections.abc import Sequence
from dataclasses import dataclass
[docs]
@dataclass(frozen=True)
class MonthlyCurtailment:
"""A reported calendar-month curtailment estimate in GWh, not metered output."""
month: int
wind_gwh: float
solar_gwh: float
estimated_subset_gwh: float
[docs]
@dataclass(frozen=True)
class CurtailmentAudit:
"""Same-window comparisons and one-decimal rounding reconciliation."""
reported_wind_gwh: float
reported_solar_gwh: float
reported_total_gwh: float
monthly_reconstructed_total_gwh: float
reconciliation_difference_gwh: float
reconciliation_tolerance_gwh: float
estimated_subset_gwh: float
estimated_subset_pct: float
wind_share_pct: float
wind_yoy_pct: float
solar_yoy_pct: float
total_yoy_pct: float
[docs]
def audit_curtailment(
months: Sequence[MonthlyCurtailment],
*,
reported_wind_gwh: float,
reported_solar_gwh: float,
reported_estimated_subset_gwh: float,
prior_wind_gwh: float,
prior_solar_gwh: float,
display_precision_gwh: float = 0.1,
) -> CurtailmentAudit:
"""Audit independently rounded month rows against a same-window YTD report.
``estimated_subset_gwh`` is already within the wind + solar totals and
MUST NOT be added again. The precision bound models display rounding only,
not errors in ONS reference-generation estimation. November may be partial.
"""
if not months:
raise ValueError("At least one calendar month is required")
if [row.month for row in months] != list(range(1, len(months) + 1)):
raise ValueError("Months must be consecutive, unique, starting in January")
values = (
reported_wind_gwh,
reported_solar_gwh,
reported_estimated_subset_gwh,
prior_wind_gwh,
prior_solar_gwh,
display_precision_gwh,
)
if any(not math.isfinite(x) or x < 0 for x in values) or display_precision_gwh == 0:
raise ValueError("Totals must be finite/nonnegative and precision positive")
if prior_wind_gwh <= 0 or prior_solar_gwh <= 0:
raise ValueError("Prior-window wind and solar totals must both be positive")
if reported_estimated_subset_gwh > reported_wind_gwh + reported_solar_gwh:
raise ValueError("Estimated subset cannot exceed reported curtailed energy")
for row in months:
if any(
not math.isfinite(x) or x < 0
for x in (row.wind_gwh, row.solar_gwh, row.estimated_subset_gwh)
):
raise ValueError("Monthly estimates must be finite and nonnegative")
if row.estimated_subset_gwh > row.wind_gwh + row.solar_gwh:
raise ValueError("Estimated subset cannot exceed a month total")
def check_component(reconstructed: float, published: float, name: str) -> None:
tolerance = (len(months) + 1) * display_precision_gwh / 2
if abs(reconstructed - published) > tolerance + 1e-8:
raise ValueError(f"{name} published and month totals disagree beyond rounding")
wind = sum(row.wind_gwh for row in months)
solar = sum(row.solar_gwh for row in months)
estimated = sum(row.estimated_subset_gwh for row in months)
check_component(wind, reported_wind_gwh, "Wind")
check_component(solar, reported_solar_gwh, "Solar")
check_component(estimated, reported_estimated_subset_gwh, "Estimated subset")
total = reported_wind_gwh + reported_solar_gwh
prior = prior_wind_gwh + prior_solar_gwh
return CurtailmentAudit(
reported_wind_gwh=reported_wind_gwh,
reported_solar_gwh=reported_solar_gwh,
reported_total_gwh=total,
monthly_reconstructed_total_gwh=wind + solar,
reconciliation_difference_gwh=(wind + solar) - total,
reconciliation_tolerance_gwh=(len(months) + 1) * display_precision_gwh,
estimated_subset_gwh=reported_estimated_subset_gwh,
estimated_subset_pct=100 * reported_estimated_subset_gwh / total if total else 0,
wind_share_pct=100 * reported_wind_gwh / total if total else 0,
wind_yoy_pct=100 * (reported_wind_gwh / prior_wind_gwh - 1),
solar_yoy_pct=100 * (reported_solar_gwh / prior_solar_gwh - 1),
total_yoy_pct=100 * (total / prior - 1),
)
[docs]
def hypothetical_deliverable_ceiling_gwh(
curtailed_potential_gwh: float,
*,
accessible_fraction: float,
round_trip_efficiency: float,
) -> float:
"""Physical energy ceiling for a hypothetical recovered fraction, NOT a forecast.
It assumes the stated fraction of foregone generation could be captured and
delivered with the stated round-trip efficiency. It ignores time matching,
network topology, charging power, battery energy size, prices and ownership.
Even the 100% case is generally unattainable; reported curtailment cannot be
treated as battery availability or an investable revenue opportunity.
"""
if not math.isfinite(curtailed_potential_gwh) or curtailed_potential_gwh < 0:
raise ValueError("Curtailed potential must be finite and nonnegative")
if not math.isfinite(accessible_fraction) or not 0 <= accessible_fraction <= 1:
raise ValueError("Accessible fraction must be within [0, 1]")
if not math.isfinite(round_trip_efficiency) or not 0 < round_trip_efficiency <= 1:
raise ValueError("Round-trip efficiency must be within (0, 1]")
return curtailed_potential_gwh * accessible_fraction * round_trip_efficiency