Source code for energy_methods.degradation_uncertainty

"""Explicit physical-rate conventions for the 2021 PV uncertainty study.

The paper omits A_N and C_N for Table 5 and mixes rate/dose unit descriptions.
No universal calibration or implicit conversion to a lifetime coefficient is
provided. Every calibrated rate must declare its scale to fractional year^-1.
"""

from __future__ import annotations

from dataclasses import dataclass

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

from energy_methods.degradation import (
    BOLTZMANN_EV_K,
    DegradationParameters,
    _evaluate_degradation_rates,
)

REFERENCE_IDS = ("ascencio_vasquez_2021_thesis", "kaaya_2021_uncertainties")


def _scale(value: float) -> None:
    if not np.isfinite(value) or value <= 0:
        raise ValueError("rate_scale_to_year_inverse must be finite and positive")


[docs] @dataclass(frozen=True, slots=True) class PhysicalRate: """Native calibrated numerical rate and explicit fractional/year conversion. ``mechanisms`` holds raw hydrolysis, photo and thermal values when available. The multiplicative total is not a sum and its components are not shares. """ raw_rate: NDArray[np.float64] annual_fractional_rate: NDArray[np.float64] rate_scale_to_year_inverse: float mechanisms: tuple[NDArray[np.float64], ...] = ()
[docs] @dataclass(frozen=True, slots=True, kw_only=True) class StressRateParameters: """Equation 1 coefficients, including mandatory calibration and unit scale. beta0 carries the calibration's units. beta1 is activation energy in eV; beta2, beta3, beta4 are nonnegative powers of daily temperature range, daytime UV irradiance (W/m²) and daily RH (percent), respectively. """ beta0: float beta1: float beta2: float beta3: float beta4: float rate_scale_to_year_inverse: float calibration_source: str def __post_init__(self) -> None: coefficients = [self.beta0, self.beta1, self.beta2, self.beta3, self.beta4] if not np.isfinite(coefficients).all() or min(coefficients) < 0: raise ValueError("Stress-rate coefficients must be finite and nonnegative") _scale(self.rate_scale_to_year_inverse) if not isinstance(self.calibration_source, str) or not self.calibration_source.strip(): raise ValueError("calibration_source is required")
[docs] def stress_rate( *, daily_maximum_temperature_c: ArrayLike, daily_temperature_range_c: ArrayLike, daily_daytime_uv_w_m2: ArrayLike, daily_relative_humidity_percent: ArrayLike, parameters: StressRateParameters, ) -> PhysicalRate: """Equation 1 (Bala), evaluated on daily inputs, without hidden aggregation. Annual integrated UV dose is NOT a substitute for daytime irradiance. Missing input masks the paired result; infinities and invalid finite values fail. The caller must declare any subsequent daily/annual aggregation. """ maximum, delta, uv, rh = np.broadcast_arrays( *[ np.asarray(v, dtype=float) for v in ( daily_maximum_temperature_c, daily_temperature_range_c, daily_daytime_uv_w_m2, daily_relative_humidity_percent, ) ] ) values = (maximum, delta, uv, rh) if any(np.isinf(v).any() for v in values): raise ValueError("Stress inputs cannot contain infinity") if np.any(maximum <= -273.15) or np.any(delta < 0) or np.any(uv < 0): raise ValueError("Invalid temperature, range or UV irradiance") if np.any((rh < 0) | (rh > 100)): raise ValueError("RH must be between 0 and 100 percent") missing = np.logical_or.reduce([np.isnan(v) for v in values]) maximum, delta, uv, rh = [np.where(missing, np.nan, v) for v in values] p = parameters try: with np.errstate(over="raise", invalid="raise", divide="raise"): raw = ( p.beta0 * np.exp(-p.beta1 / (BOLTZMANN_EV_K * (maximum + 273.15))) * delta**p.beta2 * uv**p.beta3 * rh**p.beta4 ) annual = raw * p.rate_scale_to_year_inverse except FloatingPointError as error: raise ValueError("Stress-rate overflow; check calibration and units") from error return PhysicalRate(np.asarray(raw), np.asarray(annual), p.rate_scale_to_year_inverse)
[docs] def combined_rate_2021( *, module_temperature_mean_c: ArrayLike, module_temperature_upper_c: ArrayLike, module_temperature_lower_c: ArrayLike, relative_humidity_percent: ArrayLike, uv_dose_kwh_m2: ArrayLike, cycles_per_year: ArrayLike, parameters: DegradationParameters, rate_scale_to_year_inverse: float, ) -> PhysicalRate: """Equations 3-6, retaining the printed (273 + delta T)**theta term. Reuses the mapping kernel's input validation and Arrhenius equations, but does NOT change the existing 2019 mapping API. The 273 offset is a printed empirical expression, not a physical conversion of a temperature difference. Celsius-to-kelvin in Arrhenius terms uses 273.15. A_N, cycles/year and unit conversion are mandatory; Table 5 alone is not an executable calibration. A scale of 0.01 means native numerical %/year, 1 means fractional/year. Neither is inferred from the supplied parameters. """ _scale(rate_scale_to_year_inverse) rates = _evaluate_degradation_rates( module_temperature_mean_c=module_temperature_mean_c, module_temperature_upper_c=module_temperature_upper_c, module_temperature_lower_c=module_temperature_lower_c, relative_humidity_percent=relative_humidity_percent, uv_dose_kwh_m2=uv_dose_kwh_m2, cycles_per_year=cycles_per_year, parameters=parameters, thermal_range_offset=273.0, ) try: with np.errstate(over="raise", invalid="raise"): annual = rates.total * rate_scale_to_year_inverse except FloatingPointError as error: raise ValueError("Rate conversion overflow") from error return PhysicalRate( rates.total, annual, rate_scale_to_year_inverse, (rates.hydrolysis, rates.photodegradation, rates.thermomechanical), )