Source code for energy_methods.curtailment_screen

"""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