Source code for energy_methods.failure_rates

"""Failure counts, exposure, demand probability and censored lifetime models.

Rates are per declared exposure unit, never percentages. Gamma uses shape/rate
for uncertainty in a rate; a Gamma *lifetime* distribution instead uses a scale.
No function silently converts a demand probability to an hourly rate.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Literal

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

REFERENCE_IDS = (
    "nist_failure_rate_estimation",
    "inl_2021_component_reliability",
    "klise_2018_pv_failures",
    "scipy_nbinom_reference",
)


def _positive(value: float, name: str, *, zero: bool = False) -> None:
    if not np.isfinite(value) or value < 0 or (value == 0 and not zero):
        raise ValueError(f"{name} must be finite and {'nonnegative' if zero else 'positive'}")


def _count(value: int, name: str) -> None:
    _positive(value, name, zero=True)
    if isinstance(value, bool) or int(value) != value:
        raise ValueError(f"{name} must be an integer count")


[docs] @dataclass(frozen=True) class RateEstimate: """MLE and central exact Poisson confidence interval, in 1/exposure-unit. With zero failures the central interval has a one-sided confidence level of (1+confidence)/2. Use ``zero_failure_upper_bound`` for a specified one-sided confidence level. Infinity for MTBF does not establish immunity. """ failures: int exposure: float rate: float lower: float upper: float confidence: float @property def mtbf(self) -> float: """Inverse rate, in the input exposure unit; assumes a constant rate.""" return 1 / self.rate if self.rate else float("inf")
[docs] def estimate_rate(failures: int, exposure: float, *, confidence: float = 0.95) -> RateEstimate: """Estimate k/T, using Garwood bounds for independent fixed-exposure counts. Exposure is SUMMED at-risk device time (including censored survivors), not calendar duration, MW or the number of recorded failures alone. The interval assumes homogeneous Poisson counts; heterogeneity, clustering, ageing and reporting bias can make it overconfident. """ _count(failures, "failures") _positive(exposure, "exposure") if not 0 < confidence < 1: raise ValueError("confidence must be in (0, 1)") tail = (1 - confidence) / 2 lower = float(stats.chi2.ppf(tail, 2 * failures) / (2 * exposure)) if failures else 0.0 upper = float(stats.chi2.ppf(1 - tail, 2 * (failures + 1)) / (2 * exposure)) return RateEstimate(failures, exposure, failures / exposure, lower, upper, confidence)
[docs] def zero_failure_upper_bound(exposure: float, confidence: float = 0.95) -> float: """One-sided rate bound -log(1-confidence)/T when no failures were observed.""" _positive(exposure, "exposure") if not 0 < confidence < 1: raise ValueError("confidence must be in (0, 1)") return float(-np.log1p(-confidence) / exposure)
[docs] @dataclass(frozen=True) class GammaRate: """Uncertain constant rate: Gamma(shape, RATE), with rate in exposure units. Used for industry priors or posterior uncertainty, not lifetime density. Updates require comparable populations, failure definitions and exposure units, and new data independent of the data already used in the prior. """ shape: float rate: float def __post_init__(self) -> None: _positive(self.shape, "shape") _positive(self.rate, "rate") @property def mean(self) -> float: return self.shape / self.rate
[docs] def interval(self, confidence: float = 0.95) -> tuple[float, float]: if not 0 < confidence < 1: raise ValueError("confidence must be in (0, 1)") q = (1 - confidence) / 2 bounds = stats.gamma.ppf([q, 1 - q], self.shape, scale=1 / self.rate) return float(bounds[0]), float(bounds[1])
[docs] def update(self, failures: int, exposure: float) -> GammaRate: _count(failures, "failures") _positive(exposure, "exposure") return GammaRate(self.shape + failures, self.rate + exposure)
[docs] def probability_at_least_one(self, exposure: float) -> float: """Posterior predictive 1-(rate/(rate+T))**shape, integrating uncertainty.""" _positive(exposure, "exposure", zero=True) return float(-np.expm1(-self.shape * np.log1p(exposure / self.rate)))
[docs] def expected_failures(self, exposure: float) -> float: _positive(exposure, "exposure", zero=True) return self.mean * exposure
[docs] def predictive_count_interval( self, exposure: float, confidence: float = 0.95 ) -> tuple[int, int]: """Equal-tail Gamma-Poisson predictive bounds, including event noise. Negative-binomial n=shape, p=rate/(rate+exposure). For a fleet, sum exposure first: the uncertain common rate is shared. Discrete interval coverage can exceed the nominal level. This is not a rate interval. """ _positive(exposure, "exposure", zero=True) if not 0 < confidence < 1: raise ValueError("confidence must be in (0, 1)") if exposure == 0: return 0, 0 tail = (1 - confidence) / 2 bounds = stats.nbinom.ppf([tail, 1 - tail], self.shape, 1 / (1 + exposure / self.rate)) if not np.isfinite(bounds).all(): raise ValueError("Predictive quantile exceeds numerical range") return int(bounds[0]), int(bounds[1])
[docs] def predictive_log_probability(self, failures: int, exposure: float) -> float: """Log predictive probability of a future count for out-of-time scoring.""" _count(failures, "failures") _positive(exposure, "exposure", zero=True) if exposure == 0: return 0.0 if failures == 0 else float("-inf") return float(stats.nbinom.logpmf(failures, self.shape, 1 / (1 + exposure / self.rate)))
[docs] @dataclass(frozen=True) class BetaDemand: """Beta uncertainty in a per-demand failure probability, not a time rate.""" alpha: float beta: float def __post_init__(self) -> None: _positive(self.alpha, "alpha") _positive(self.beta, "beta") @property def mean(self) -> float: return self.alpha / (self.alpha + self.beta)
[docs] def interval(self, confidence: float = 0.95) -> tuple[float, float]: if not 0 < confidence < 1: raise ValueError("confidence must be in (0, 1)") q = (1 - confidence) / 2 bounds = stats.beta.ppf([q, 1 - q], self.alpha, self.beta) return float(bounds[0]), float(bounds[1])
[docs] def update(self, failures: int, demands: int) -> BetaDemand: _count(failures, "failures") _count(demands, "demands") if demands == 0 or failures > demands: raise ValueError("Require positive demands and failures <= demands") return BetaDemand(self.alpha + failures, self.beta + demands - failures)
[docs] def probability_at_least_one(self, demands: int) -> float: """Beta-binomial predictive probability, for conditionally iid demands.""" _count(demands, "demands") log_zero = special.betaln(self.alpha, self.beta + demands) - special.betaln( self.alpha, self.beta ) return float(np.clip(-np.expm1(log_zero), 0, 1))
[docs] @dataclass(frozen=True) class LifetimeModel: """Time-to-event model with explicit parameter conventions and time units. Weibull: (shape, scale); gamma: (shape, SCALE); exponential: (rate, unused); lognormal_log: (underlying-normal mean, standard deviation). Normal is explicitly conditioned on lifetime >= 0, an implementation adaptation. Fits to recurring fault intervals are not component lifetimes. """ kind: Literal["weibull", "gamma", "exponential", "lognormal_log", "normal_positive"] parameter1: float parameter2: float = 1.0 def __post_init__(self) -> None: if self.kind not in {"weibull", "gamma", "exponential", "lognormal_log", "normal_positive"}: raise ValueError("Unsupported lifetime distribution") if not np.isfinite(self.parameter1): raise ValueError("parameter1 must be finite") if self.kind not in {"lognormal_log", "normal_positive"}: _positive(self.parameter1, "parameter1") _positive(self.parameter2, "parameter2")
[docs] def log_survival(self, time: ArrayLike) -> NDArray[np.float64]: """Log S(t), with t measured in the model's documented time unit.""" t = np.asarray(time, dtype=float) if not np.isfinite(t).all() or np.any(t < 0): raise ValueError("time must be finite and nonnegative") p, q = self.parameter1, self.parameter2 with np.errstate(over="ignore"): if self.kind == "weibull": return -np.power(t / q, p) if self.kind == "exponential": return -p * t if self.kind == "gamma": return np.asarray(stats.gamma.logsf(t, p, scale=q)) if self.kind == "lognormal_log": return np.asarray(stats.lognorm.logsf(t, q, scale=np.exp(p))) return np.asarray(stats.norm.logsf(t, p, q) - stats.norm.logsf(0, p, q))
[docs] def conditional_failure(self, age: float, horizon: float) -> float: """1-S(age+horizon)/S(age); not an expected renewal failure count.""" _positive(age, "age", zero=True) _positive(horizon, "horizon", zero=True) if horizon == 0: return 0.0 logs = self.log_survival([age, age + horizon]) if not np.isfinite(logs[0]): raise ValueError("Survival at the conditioning age is numerically zero") return float(np.clip(-np.expm1(logs[1] - logs[0]), 0, 1))
[docs] def fit_weibull_censored(times: ArrayLike, failed: ArrayLike) -> LifetimeModel: """Two-parameter Weibull MLE with independent right censoring. One row per device, observed from age zero. ``failed`` is 0 or 1. Include survivors; no delayed entry, interval censoring or recurrent-event fitting. Raises for unidentified fits rather than assigning an arbitrary lifetime. """ t, e = np.asarray(times, dtype=float), np.asarray(failed, dtype=float) if ( t.ndim != 1 or t.shape != e.shape or len(t) < 3 or not np.isfinite(t).all() or not np.isfinite(e).all() or np.any(t <= 0) or not np.isin(e, [0, 1]).all() ): raise ValueError("Need aligned positive finite times and binary failure flags") if e.sum() < 2 or np.ptp(t[e == 1]) == 0: raise ValueError("At least two distinct observed failure times are required") # Normalize time for numerical stability and profile out the scale. log_t = np.log(t / np.median(t)) failures = float(e.sum()) def profile(log_shape: float) -> float: k = float(np.exp(log_shape)) log_scale = (special.logsumexp(k * log_t) - np.log(failures)) / k return float( -( failures * np.log(k) - failures * k * log_scale + (k - 1) * (e * log_t).sum() - failures ) ) bounds = (-5.0, 5.0) result = optimize.minimize_scalar(profile, bounds=bounds, method="bounded") if not result.success or min(result.x - bounds[0], bounds[1] - result.x) < 1e-3: raise ValueError("Weibull shape is unidentified within numerical bounds") shape = float(np.exp(result.x)) scale = float( np.median(t) * np.exp((special.logsumexp(shape * log_t) - np.log(failures)) / shape) ) return LifetimeModel("weibull", shape, scale)