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
)
),
)