Source code for energy_methods.pv_reliability

"""Power-versus-age models and variation metrics from Kaaya et al. (2021).

These are deterministic extrapolations, not survival probabilities or warranties.
The stretched-exponential coefficient has units year**(-beta); coefficients
from different curve families are not interchangeable annual loss percentages.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Literal

import numpy as np
from numpy.typing import ArrayLike, NDArray
from scipy.optimize import least_squares

REFERENCE_IDS = ("ascencio_vasquez_2021_thesis", "kaaya_2021_uncertainties")
ReliabilityKind = Literal["linear", "exponential", "stretched_exponential", "wear_out"]
KINDS: tuple[ReliabilityKind, ...] = ("linear", "exponential", "stretched_exponential", "wear_out")


def _finite(value: ArrayLike, name: str) -> NDArray[np.float64]:
    result = np.asarray(value, dtype=float)
    if not result.size or not np.isfinite(result).all():
        raise ValueError(f"{name} must be nonempty and finite")
    return result


def _paired(measured: ArrayLike, predicted: ArrayLike) -> tuple[NDArray, NDArray]:
    m, p = _finite(measured, "measured"), _finite(predicted, "predicted")
    if m.shape != p.shape:
        raise ValueError("Measured and predicted shapes must match; align observations first")
    return m, p


[docs] def normalized_rmse(measured: ArrayLike, predicted: ArrayLike) -> float: """Equation 19, percent: RMSE/mean, or RMSE/range for exactly zero mean. The paper concerns positive quantities. Negative means are rejected rather than producing negative errors. A constant zero reference is defined only for an exact match (zero error); otherwise its normalization is undefined. """ m, p = _paired(measured, predicted) mean = float(m.mean()) if mean < 0: raise ValueError("Equation 19 requires a nonnegative measured mean") scale = mean if mean != 0 else float(np.ptp(m)) rmse = float(np.sqrt(np.mean((p - m) ** 2))) if scale == 0: if rmse == 0: return 0.0 raise ValueError("NRMSE normalization is undefined for an all-zero reference") return 100 * rmse / scale
[docs] def relative_difference(measured: ArrayLike, predicted: ArrayLike) -> NDArray[np.float64]: """Equation 20: 100*abs(p-m)/max(abs(p),abs(m)); (0,0) is defined as 0. This symmetric difference is not percentage error relative to the reference. Equal shapes are required; no implicit broadcasting or missing-value removal. """ m, p = _paired(measured, predicted) scale = np.maximum(np.abs(m), np.abs(p)) return 100 * np.divide(np.abs(p - m), scale, out=np.zeros_like(scale), where=scale > 0)
[docs] @dataclass(frozen=True, slots=True) class ReliabilityCurve: """Table 2 curve with time in years and power normalized to initial power. ``k`` is fractional, never a numerical percent. ``beta`` belongs to the stretched exponential (Pan); ``gamma`` and ``mu`` to wear-out (Kaaya). Gamma and k are inseparable through their ratio and cannot both be fitted. """ kind: ReliabilityKind k: float beta: float = 1.0 gamma: float = 1.0 mu: float = 1.0 def __post_init__(self) -> None: if self.kind not in KINDS: raise ValueError(f"Unknown reliability kind: {self.kind}") if not np.isfinite([self.k, self.beta, self.gamma, self.mu]).all(): raise ValueError("Curve parameters must be finite") if self.k < 0 or min(self.beta, self.gamma, self.mu) <= 0: raise ValueError("k must be nonnegative and shape parameters positive") @property def k_units(self) -> str: """Dimensional coefficient units, with gamma treated as dimensionless.""" return "year**(-beta)" if self.kind == "stretched_exponential" else "year**(-1)"
[docs] def power(self, age_years: ArrayLike) -> NDArray[np.float64]: """Evaluate Table 2; linear predictions are not clipped below zero.""" t = _finite(age_years, "age_years") if np.any(t < 0): raise ValueError("Age must be nonnegative") if self.k == 0: return np.ones_like(t) with np.errstate(over="ignore", under="ignore"): if self.kind == "linear": return 1 - self.k * t if self.kind == "exponential": return np.exp(-self.k * t) if self.kind == "stretched_exponential": return np.exp(-self.k * t**self.beta) # The analytic limit at t=0 is one, without divide-by-zero warnings. ratio = np.divide(self.gamma, self.k * t, out=np.full_like(t, np.inf), where=t > 0) return -np.expm1(-(ratio**self.mu))
[docs] def failure_time(self, retained_power: float = 0.8) -> float: """Analytic crossing time, years, for a retained-power threshold in (0,1).""" if not np.isfinite(retained_power) or not 0 < retained_power < 1: raise ValueError("retained_power must lie strictly between zero and one") if self.k == 0: return float("inf") if self.kind == "linear": return (1 - retained_power) / self.k if self.kind == "exponential": return -float(np.log(retained_power)) / self.k if self.kind == "stretched_exponential": return float((-np.log(retained_power) / self.k) ** (1 / self.beta)) return float(self.gamma / (self.k * (-np.log1p(-retained_power)) ** (1 / self.mu)))
[docs] @dataclass(frozen=True, slots=True) class ReliabilityFit: """Calibration result; residual error is not a prediction confidence interval.""" curve: ReliabilityCurve nrmse_percent: float observations: int calibration_end_year: float jacobian_condition: float
[docs] def fit_reliability( age_years: ArrayLike, normalized_power: ArrayLike, *, kind: ReliabilityKind, gamma: float = 1.0, ) -> ReliabilityFit: """Fit Table 2 with bounded, deterministic multistart least squares. Fit k and (for nonlinear families) beta or mu. Wear-out gamma is FIXED to the caller's value to avoid the exact k/gamma degeneracy. Ages must be distinct, increasing, measured from a declared origin. The normalization must be supplied; no hidden intercept, temperature correction or filtering. Shape bounds [0.05, 10] and k bounds [1e-10, 10] are numerical choices. Report the family and shape alongside k; do not rank lifetimes by fit alone. """ t, y = _paired(age_years, normalized_power) if t.ndim != 1 or len(t) < 4 or np.any(t < 0) or np.any(np.diff(t) <= 0): raise ValueError("At least four increasing, distinct, nonnegative ages are required") if np.any(y <= 0) or np.any(y > 1.5): raise ValueError("Normalized power must be positive and at most 1.5") if np.ptp(y) <= 1e-12: raise ValueError("A flat series cannot identify a degradation curve and its lifetime") ReliabilityCurve(kind, 0.01, gamma=gamma) nonlinear = kind in {"stretched_exponential", "wear_out"} def curve_for(log_parameters: NDArray) -> ReliabilityCurve: values = np.exp(log_parameters) return ReliabilityCurve( kind, float(values[0]), gamma=gamma, beta=float(values[1]) if kind == "stretched_exponential" else 1, mu=float(values[1]) if kind == "wear_out" else 1, ) lower = np.log([1e-10, 0.05] if nonlinear else [1e-10]) upper = np.log([10, 10] if nonlinear else [10]) fits = [ least_squares( lambda x: curve_for(x).power(t) - y, np.log([k, shape] if nonlinear else [k]), bounds=(lower, upper), ftol=1e-12, xtol=1e-12, gtol=1e-12, max_nfev=3000, ) for k in (0.001, 0.01, 0.1) for shape in ((0.3, 1.0, 2.0) if nonlinear else (1.0,)) ] successful = [fit for fit in fits if fit.success] if not successful: raise ValueError("Reliability calibration did not converge") best = min(successful, key=lambda fit: fit.cost) curve = curve_for(best.x) return ReliabilityFit( curve, normalized_rmse(y, curve.power(t)), len(t), float(t[-1]), float(np.linalg.cond(best.jac)), )