Source code for energy_methods.dispatch_review

"""Daily dispatch schedule reconciliation; no technical-loss or monetary inference."""

from __future__ import annotations

from dataclasses import dataclass
from datetime import date, timedelta
from math import fsum

from energy_methods.operations import _number


[docs] @dataclass(frozen=True) class DailyScheduleRecord: day: str scheduled_mwh: float | None actual_mwh: float | None def __post_init__(self) -> None: if date.fromisoformat(self.day).isoformat() != self.day: raise ValueError("day must be YYYY-MM-DD") for name in ("scheduled_mwh", "actual_mwh"): value = getattr(self, name) if value is not None: _number(value, name, minimum=0)
[docs] @dataclass(frozen=True) class ScheduleReview: calendar_days: int comparable_days: int missing_dates: tuple[str, ...] coverage_fraction: float scheduled_mwh: float actual_mwh: float shortfall_mwh: float above_schedule_mwh: float net_deviation_mwh: float net_deviation_percent: float | None zero_actual_with_schedule_dates: tuple[str, ...] revenue_impact: None = None recoverable_energy_mwh: None = None
[docs] def review_dispatch_schedule( records: tuple[DailyScheduleRecord, ...], *, start: date, end: date, ) -> ScheduleReview: """Reconcile a declared date window, detecting edge and internal missing days. Shortfall = sum(max(schedule - actual, 0)); excess is reported separately. Net deviation = actual - schedule. Neither quantity identifies resource, grid, forecasting or equipment causes. A zero schedule and zero actual can coexist with a severe known outage: absence of a shortfall is not health. """ if not 0 <= (end - start).days <= 3660: raise ValueError("Review window must contain 1..3661 days") by_day = {} for row in records: day = date.fromisoformat(row.day) if day < start or day > end or day in by_day: raise ValueError("Duplicate or out-of-window daily record") by_day[day] = row window = [start + timedelta(days=i) for i in range((end - start).days + 1)] valid = [r for r in records if r.scheduled_mwh is not None and r.actual_mwh is not None] missing = tuple( d.isoformat() for d in window if d not in by_day or by_day[d].scheduled_mwh is None or by_day[d].actual_mwh is None ) pairs = [ (r.scheduled_mwh, r.actual_mwh) for r in valid if r.scheduled_mwh is not None and r.actual_mwh is not None ] scheduled, actual = fsum(s for s, _ in pairs), fsum(a for _, a in pairs) return ScheduleReview( len(window), len(valid), missing, len(valid) / len(window), scheduled, actual, fsum(max(s - a, 0) for s, a in pairs), fsum(max(a - s, 0) for s, a in pairs), actual - scheduled, 100 * (actual / scheduled - 1) if scheduled else None, tuple( sorted( r.day for r in valid if r.actual_mwh == 0 and r.scheduled_mwh is not None and r.scheduled_mwh > 0 ) ), )