Source code for energy_methods.reliability_algorithms

"""Competing risks, lifetime uncertainty, redundancy and repairable availability.

These algorithms complement ``failure_rates`` and ``pv_device_reliability``.
Inputs must be homogeneous, correctly censored observations or explicit scenario
assumptions. An anomaly score is not a failure count or calibrated probability.
"""

from __future__ import annotations

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

from energy_methods.failure_rates import fit_weibull_censored

REFERENCE_IDS = (
    "survival_competing_risks",
    "scipy_bootstrap_reference",
    "nist_reliability_series",
    "nist_reliability_parallel",
    "nasa_repairable_availability",
)


def _vector(value: ArrayLike, name: str) -> NDArray[np.float64]:
    array = np.asarray(value, dtype=float)
    if array.ndim != 1 or not array.size or not np.isfinite(array).all():
        raise ValueError(f"{name} must be a nonempty finite one-dimensional vector")
    return array


[docs] def aalen_johansen(times: ArrayLike, event_type: ArrayLike) -> pd.DataFrame: """First-event cumulative incidence with mutually exclusive verified causes. One row per device from commissioning: 0=censored, positive integer=cause. At each age, ``F_j += S(previous)*d_j/n``, then ``S *= (1-sum(d_j)/n)``. Tied events across devices precede censoring; no artificial jitter is used. Independent censoring is assumed, but independent latent failure causes are not required. No delayed entry, recurrent faults or interval censoring. Unknown causes must have their own positive code, not be treated as censored. Outputs point estimates, not confidence intervals or causal effects. """ age, cause = _vector(times, "times"), _vector(event_type, "event_type") if ( age.shape != cause.shape or np.any(age <= 0) or np.any(cause < 0) or np.any(cause != np.floor(cause)) ): raise ValueError("Positive ages must align with nonnegative integer cause codes") causes = np.unique(cause[cause > 0]) cumulative = dict.fromkeys((int(c) for c in causes), 0.0) survival = 1.0 records = [] for time in np.unique(age): risk = int((age >= time).sum()) current = cause[age == time] failures = int((current > 0).sum()) for c in cumulative: cumulative[c] += survival * int((current == c).sum()) / risk survival *= 1 - failures / risk records.append( dict( age=float(time), at_risk=risk, failures=failures, censored=int((current == 0).sum()), survival=survival, **{f"incidence_{c}": value for c, value in cumulative.items()}, ) ) return pd.DataFrame(records)
[docs] def bootstrap_weibull_survival( times: ArrayLike, failed: ArrayLike, evaluation_times: ArrayLike, *, resamples: int = 500, confidence: float = 0.95, seed: int = 0, allow_extrapolation: bool = False, ) -> pd.DataFrame: """Paired device bootstrap and percentile pointwise Weibull survival bounds. Resample (age, event) rows together and refit the right-censored MLE. This assumes iid devices and independent censoring; shared site/weather cohorts require a cluster bootstrap instead. It does not quantify model error. Raises if ANY resample is unidentified: silently dropping failed fits can bias intervals. Sparse cohorts should use KM/rate bounds instead. Tail extrapolation beyond observed follow-up requires explicit opt-in and remains an unvalidated model projection. Intervals are not simultaneous. """ age, events = _vector(times, "times"), _vector(failed, "failed") grid = _vector(evaluation_times, "evaluation_times") model = fit_weibull_censored(age, events) if ( isinstance(resamples, bool) or not isinstance(resamples, (int, np.integer)) or resamples < 100 or not np.isfinite(confidence) or not 0 < confidence < 1 or np.any(grid < 0) or np.any(np.diff(grid) <= 0) ): raise ValueError( "Need >=100 resamples, confidence in (0,1), and increasing nonnegative ages" ) if grid[-1] > age.max() and not allow_extrapolation: raise ValueError( "Evaluation exceeds observed follow-up; extrapolation needs explicit opt-in" ) rng = np.random.default_rng(seed) curves = np.empty((resamples, grid.size)) for i in range(resamples): index = rng.integers(0, age.size, size=age.size) try: fitted = fit_weibull_censored(age[index], events[index]) except ValueError as exc: raise ValueError( f"Unidentified bootstrap fit at resample {i + 1}; no interval reported" ) from exc curves[i] = np.exp(fitted.log_survival(grid)) tail = (1 - confidence) / 2 lower, upper = np.quantile(curves, [tail, 1 - tail], axis=0) result = pd.DataFrame( dict( age=grid, survival=np.exp(model.log_survival(grid)), lower=lower, upper=upper, extrapolated=grid > age.max(), ) ) result.attrs.update( shape=model.parameter1, scale=model.parameter2, resamples=int(resamples), confidence=confidence, seed=seed, method="paired_device_percentile_bootstrap", ) return result
[docs] def k_out_of_n_reliability(component_reliability: ArrayLike, required: int) -> float: """Poisson-binomial dynamic program for independent active components. At one common mission age, the system works if >= required components work. required=n gives series; required=1 gives active parallel redundancy. Probabilities must have matching horizons/definitions. Reusing this for steady availability requires independent component states. No standby, load sharing, common-cause events or proportional-capacity interpretation. Compose disjoint blocks only; shared components must not appear twice. """ probabilities = _vector(component_reliability, "component_reliability") if ( np.any((probabilities < 0) | (probabilities > 1)) or isinstance(required, bool) or not isinstance(required, (int, np.integer)) or not 1 <= required <= probabilities.size ): raise ValueError("Probabilities must be in [0,1], required an integer in [1,n]") distribution = np.array([1.0]) for p in probabilities: distribution = np.convolve(distribution, [1 - p, p]) return float(np.clip(distribution[required:].sum(), 0, 1))
[docs] def repairable_availability( failure_rate_per_hour: float, mean_restore_hours: float, interval_hours: ArrayLike, expected_power_kw: ArrayLike, *, initial_availability: float = 1.0, ) -> pd.DataFrame: """Exact two-state Markov interval availability and expected energy at risk. Constant up->down rate lambda and down->up rate mu=1/mean_restore_hours. Both use the SAME clock: this function uses calendar hours while the unit is in each state. Do not pass a daylight operating-hour rate unchanged. Restoration duration is exponential; include logistics in its mean only if this memoryless approximation is defensible. Initial state is explicit. Expected power is the nonnegative, piecewise-constant counterfactual output of the affected capacity when available, in kW. Down means zero output; partial derating and overlapping parent/child losses need another model. Assumes the counterfactual profile is independent of failures/restoration; weather-correlated damage, shared repair crews and ageing are excluded. Returns expectations, not confidence intervals or a stochastic trajectory. """ hours = _vector(interval_hours, "interval_hours") power = _vector(expected_power_kw, "expected_power_kw") if ( hours.shape != power.shape or np.any(hours <= 0) or np.any(power < 0) or not np.isfinite(failure_rate_per_hour) or failure_rate_per_hour < 0 or not np.isfinite(mean_restore_hours) or mean_restore_hours <= 0 or not np.isfinite(initial_availability) or not 0 <= initial_availability <= 1 ): raise ValueError("Require aligned positive hours, nonnegative power/rate and valid state") repair_rate = 1 / mean_restore_hours total_rate = failure_rate_per_hour + repair_rate if not np.isfinite(total_rate) or not np.isfinite(hours.sum()): raise ValueError("Rate or horizon exceeds numerical range") stationary_down = failure_rate_per_hour / total_rate down = 1 - initial_availability start = 0.0 rows = [] for duration, baseline in zip(hours, power, strict=True): z = total_rate * float(duration) if not np.isfinite(z): raise ValueError("Rate times duration exceeds numerical range") decay = np.exp(-z) # Stable 1 - (1-exp(-z))/z near zero avoids negative tiny downtime. complement = z / 2 - z**2 / 6 + z**3 / 24 - z**4 / 120 if z < 1e-4 else 1 + np.expm1(-z) / z mean_down = down * (1 - complement) + stationary_down * complement downtime = float(duration * mean_down) down = down * decay + stationary_down * (-np.expm1(-z)) rows.append( dict( start_hour=start, end_hour=start + duration, availability_end=float(1 - down), mean_availability=float(1 - mean_down), expected_downtime_hours=downtime, expected_failures=float(failure_rate_per_hour * (duration - downtime)), baseline_energy_kwh=float(baseline * duration), expected_energy_loss_kwh=float(baseline * downtime), ) ) start += float(duration) result = pd.DataFrame(rows) result.attrs.update( failure_rate_per_hour=failure_rate_per_hour, mean_restore_hours=mean_restore_hours, initial_availability=initial_availability, steady_availability=1 - stationary_down, ) return result