Source code for energy_methods.status

"""IEC-informed observable operating screens; all operating causes unconfirmed.

Implements the recovered ASVA 2.0 decision order. Numerical thresholds are ASVA
engineering rules, not IEC requirements. IEC TS 63019:2019 information categories
must not be confused with confirmed plant availability or fault attribution.

The main thesis and IEC standard are credited in energy_methods.references.
The IEC citation is context and does not imply conformity.
"""

from __future__ import annotations

from dataclasses import dataclass
from enum import IntEnum

import numpy as np
import pandas as pd
from numpy.typing import ArrayLike, NDArray

from energy_methods._arrays import BoolArray, FloatArray, IntArray, aligned, epoch_ns, utc_index

REFERENCE_IDS = ("ascencio_vasquez_2021_thesis", "iec_2019_availability")


[docs] class OperatingState(IntEnum): MISSING_GENERATION = 0 INVALID_GENERATION = 1 NIGHT_NO_GENERATION = 2 LOW_RESOURCE_NO_GENERATION = 3 GENERATION_AT_LOW_RESOURCE = 4 NO_GENERATION_WITH_RESOURCE = 5 REFERENCE_UNAVAILABLE = 6 GENERATION_BELOW_EXPECTED = 7 GENERATION_MODEL_CONSISTENT = 8 GENERATION_ABOVE_EXPECTED = 9
STATE_KEYS = tuple(state.name.lower() for state in OperatingState) IEC_ASSIGNED_CATEGORY = "INFORMATION UNAVAILABLE" IEC_ASSIGNED_CLAUSE = "5.18"
[docs] @dataclass(frozen=True, slots=True) class StatusConfig: generation_epsilon_mwh: float = 1e-5 minimum_solar_elevation_deg: float = 5.0 minimum_ghi_wm2: float = 100.0 minimum_effective_poa_wm2: float = 100.0 night_maximum_solar_elevation_deg: float = 0.0 night_maximum_ghi_wm2: float = 1.0 model_relative_tolerance: float = 0.2 model_absolute_tolerance_fraction_of_training_scale: float = 0.05 minimum_expected_fraction_of_training_scale: float = 0.05 near_zero_ratio: float = 0.05 persistent_screening_run_minimum_hours: int = 2 def __post_init__(self) -> None: numbers = [ self.generation_epsilon_mwh, self.minimum_ghi_wm2, self.minimum_effective_poa_wm2, self.night_maximum_ghi_wm2, self.model_relative_tolerance, self.model_absolute_tolerance_fraction_of_training_scale, self.minimum_expected_fraction_of_training_scale, self.near_zero_ratio, ] if not np.isfinite(numbers).all() or min(numbers) < 0: raise ValueError("Screening thresholds must be finite and nonnegative") if ( not -90 <= self.night_maximum_solar_elevation_deg <= self.minimum_solar_elevation_deg <= 90 ): raise ValueError("Solar elevation thresholds must be finite and ordered") if self.persistent_screening_run_minimum_hours < 2: raise ValueError("Persistence requires at least two consecutive hours")
[docs] @dataclass(frozen=True, slots=True) class StatusResult: codes: NDArray[np.uint8] labels: NDArray[np.str_] envelope_lower_mwh: FloatArray envelope_upper_mwh: FloatArray band_state: NDArray[np.uint8] model_band_disagree: BoolArray near_zero: BoolArray persistent: BoolArray run_hours: IntArray assigned_iec_category: str = IEC_ASSIGNED_CATEGORY confirmed_cause: bool = False
def _optional_array(values: ArrayLike | None, n: int, name: str) -> FloatArray: result = np.full(n, np.nan) if values is None else np.asarray(values, dtype=np.float64) if result.shape != (n,): raise ValueError(f"{name} must match the observation length") return result DEFAULT_CONFIG = StatusConfig()
[docs] def classify_status( actual_mwh: ArrayLike, expected_mwh: ArrayLike, ghi_wm2: ArrayLike, solar_elevation_deg: ArrayLike, *, poa_wm2: ArrayLike | None = None, training_scale_mwh: float | None = None, weather_supported: ArrayLike | None = None, band_lower_mwh: ArrayLike | None = None, band_upper_mwh: ArrayLike | None = None, timestamps: pd.DatetimeIndex | None = None, config: StatusConfig = DEFAULT_CONFIG, ) -> StatusResult: """Screen one site/reference in chronological order without filtering its energy. Pass timestamps to break persistence at missing elapsed hours. If omitted, rows are explicitly assumed to be consecutive one-hour intervals. Training scale is accepted-training Q95 (including zeros), not nameplate capacity. """ actual, expected, ghi, elevation = aligned( actual_mwh, expected_mwh, ghi_wm2, solar_elevation_deg, ) n = len(actual) poa = _optional_array(poa_wm2, n, "poa_wm2") lower_band = _optional_array(band_lower_mwh, n, "band_lower_mwh") upper_band = _optional_array(band_upper_mwh, n, "band_upper_mwh") support = ( np.zeros(n, dtype=np.bool_) if weather_supported is None else np.asarray( weather_supported, ) ) if support.dtype != np.bool_ or support.shape != (n,): raise ValueError("weather_supported must be an aligned boolean array") utc = None if timestamps is None else utc_index(timestamps) if utc is not None and len(utc) != n: raise ValueError("Timestamps must match the observations") result = np.full(n, OperatingState.REFERENCE_UNAVAILABLE, dtype=np.uint8) valid = np.isfinite(actual) & (actual >= 0) result[np.isnan(actual)] = OperatingState.MISSING_GENERATION result[np.isinf(actual) | (np.isfinite(actual) & (actual < 0))] = ( OperatingState.INVALID_GENERATION ) resource_known = np.isfinite(ghi) & (ghi >= 0) & np.isfinite(elevation) resource_known &= np.abs(elevation) <= 90 remaining = valid & resource_known trace = actual <= config.generation_epsilon_mwh night = remaining & (elevation <= config.night_maximum_solar_elevation_deg) night &= ghi <= config.night_maximum_ghi_wm2 result[night & trace] = OperatingState.NIGHT_NO_GENERATION result[night & ~trace] = OperatingState.GENERATION_AT_LOW_RESOURCE remaining &= ~night resource = (ghi >= config.minimum_ghi_wm2) & (elevation > config.minimum_solar_elevation_deg) resource &= ~np.isfinite(poa) | (poa >= config.minimum_effective_poa_wm2) result[remaining & ~resource & trace] = OperatingState.LOW_RESOURCE_NO_GENERATION result[remaining & ~resource & ~trace] = OperatingState.GENERATION_AT_LOW_RESOURCE remaining &= resource # Zero output is observable with resource even without a usable expected model. result[remaining & trace] = OperatingState.NO_GENERATION_WITH_RESOURCE remaining &= ~trace scale_valid = training_scale_mwh is not None and np.isfinite(training_scale_mwh) scale = float(training_scale_mwh) if scale_valid and training_scale_mwh is not None else np.nan width = np.full(n, np.nan) if scale >= 0: width = np.maximum( config.model_relative_tolerance * expected, config.model_absolute_tolerance_fraction_of_training_scale * scale, ) usable = remaining & np.isfinite(expected) & (expected >= 0) & support usable &= expected >= config.minimum_expected_fraction_of_training_scale * scale result[usable] = OperatingState.GENERATION_MODEL_CONSISTENT result[usable & (actual < expected - width)] = OperatingState.GENERATION_BELOW_EXPECTED result[usable & (actual > expected + width)] = OperatingState.GENERATION_ABOVE_EXPECTED envelope_valid = np.isfinite(expected) & (expected >= 0) & np.isfinite(width) lower_envelope = np.where(envelope_valid, expected - width, np.nan) upper_envelope = np.where(envelope_valid, expected + width, np.nan) band = np.zeros(n, dtype=np.uint8) band[~np.isfinite(actual)] = 4 band_valid = np.isfinite(actual) & np.isfinite(lower_band) & np.isfinite(upper_band) band_valid &= lower_band <= upper_band band[band_valid] = 2 band[band_valid & (actual < lower_band)] = 1 band[band_valid & (actual > upper_band)] = 3 disagree = ((result == 7) & (band == 3)) | ((result == 9) & (band == 1)) disagree |= (result == 8) & np.isin(band, (1, 3)) ratio = np.full(n, np.nan) np.divide(actual, expected, out=ratio, where=np.isfinite(expected) & (expected > 0)) near_zero = (result == 7) & (actual > config.generation_epsilon_mwh) near_zero &= ratio < config.near_zero_ratio persistent, runs = np.zeros(n, dtype=np.bool_), np.ones(n, dtype=np.int64) if n: boundaries = result[1:] != result[:-1] if utc is not None: boundaries |= np.diff(epoch_ns(utc)) != 3_600_000_000_000 starts = np.concatenate(([0], np.flatnonzero(boundaries) + 1)) ends = np.concatenate((starts[1:], [n])) lengths = ends - starts runs = np.repeat(lengths, lengths).astype(np.int64) persistent = np.isin(result, (5, 7)) & ( runs >= config.persistent_screening_run_minimum_hours ) labels = np.asarray(STATE_KEYS, dtype=np.str_)[result] return StatusResult( result, labels, lower_envelope, upper_envelope, band, disagree, near_zero, persistent, runs )