Source code for energy_methods.degradation

"""Climate-driven PV degradation: thesis Eqs. 3.14-3.17 and Section 6.4.

Calibration is mandatory and module-specific. Rates use the numerical percent
per year convention of the 2019 mapping paper, not fractional loss per year.
These are climate degradation indicators, not observed performance loss rates.
"""

from __future__ import annotations

from dataclasses import asdict, dataclass

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

REFERENCE_IDS = (
    "ascencio_vasquez_2021_thesis",
    "ascencio_vasquez_2019_degradation_mapping",
    "kaaya_2019_degradation",
)
BOLTZMANN_EV_K = 8.62e-5  # Publication value, deliberately retained for reproducibility.


[docs] @dataclass(frozen=True, slots=True, kw_only=True) class DegradationParameters: """One calibration, including its numerical normalization and provenance. Activation energies are in eV; n, x and theta are positive exponents. Prefactors and a_n must be fitted together using RH in percent, UV dose in kWh/m²/year, temperatures in kelvin, cycles/year, and rates in %/year. No generic c-Si calibration or normalization is silently substituted. """ a_h: float a_p: float a_tm: float e_h: float e_p: float e_tm: float n: float x: float theta: float a_n: float calibration_id: str calibration_source: str def __post_init__(self) -> None: for name in ("a_h", "a_p", "a_tm", "e_h", "e_p", "e_tm", "n", "x", "theta", "a_n"): value = getattr(self, name) if isinstance(value, bool) or not isinstance(value, (int, float)): raise ValueError(f"{name} must be a finite number") if not np.isfinite(value) or value < 0: raise ValueError(f"{name} must be finite and nonnegative") if name in {"n", "x", "theta", "a_n"} and value == 0: raise ValueError(f"{name} must be positive") for name in ("calibration_id", "calibration_source"): value = getattr(self, name) if not isinstance(value, str) or not value.strip(): raise ValueError(f"{name} is required")
[docs] def to_dict(self) -> dict[str, object]: """Return a portable, JSON-serializable calibration record.""" return asdict(self)
[docs] @dataclass(frozen=True, slots=True) class DegradationRates: """Nonnegative mechanism and combined rates, all in %/year; NaN is missing.""" hydrolysis: NDArray[np.float64] photodegradation: NDArray[np.float64] thermomechanical: NDArray[np.float64] total: NDArray[np.float64]
[docs] def degradation_rates( *, 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, ) -> DegradationRates: """Evaluate the 2019 mapping model in numerical %/year. Inputs are annual stresses: temperatures in degrees C, RH in percent, UV dose in kWh/m²/year and cycles/year. No offset is applied to the thermal temperature difference. Missing values propagate jointly; invalid values and negative totals fail. The 2021 paper's printed variant is exposed in ``degradation_uncertainty.combined_rate_2021`` instead. """ return _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, )
def _evaluate_degradation_rates( *, 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, thermal_range_offset: float = 0.0, ) -> DegradationRates: """Evaluate Eqs. 3.14-3.17 on broadcastable annual climate stresses. Temperature inputs are °C (converted to K only inside Arrhenius terms). RH is 0-100 percent, UV is annual integrated dose in kWh/m², and cycling frequency is cycles/year. Upper/lower temperatures must bound the mean. Their aggregation and RH's effective/ambient interpretation must match the calibration; this function does not infer either from weather. Missing any input makes all four outputs NaN at that position. Invalid finite values, infinities, overflow and negative combined rates raise. The total is A_N * product(1 + k_i) - 1 exactly as printed, including the subtraction OUTSIDE the normalization. It is not the sum of mechanisms. """ mean, upper, lower, rh, uv, cycles = np.broadcast_arrays( *[ np.asarray(value, dtype=float) for value in ( module_temperature_mean_c, module_temperature_upper_c, module_temperature_lower_c, relative_humidity_percent, uv_dose_kwh_m2, cycles_per_year, ) ] ) inputs = (mean, upper, lower, rh, uv, cycles) if any(np.isinf(value).any() for value in inputs): raise ValueError("Climate stresses cannot contain infinity") if any(np.any(value <= -273.15) for value in (mean, upper, lower)): raise ValueError("Module temperatures must be above absolute zero") if np.any((lower > mean) | (mean > upper)): raise ValueError("Lower <= mean <= upper module temperature is required") if np.any((rh < 0) | (rh > 100)): raise ValueError("Relative humidity must be in percent between 0 and 100") if np.any(uv < 0) or np.any(cycles < 0): raise ValueError("UV dose and cycles per year must be nonnegative") missing = np.logical_or.reduce([np.isnan(value) for value in inputs]) # Mask all inputs together: a missing cell must not cause incidental overflow. mean, upper, lower, rh, uv, cycles = [np.where(missing, np.nan, v) for v in inputs] p = parameters try: with np.errstate(over="raise", invalid="raise", divide="raise"): humidity = rh**p.n hydrolysis = p.a_h * humidity * np.exp(-p.e_h / (BOLTZMANN_EV_K * (mean + 273.15))) photo = ( p.a_p * uv**p.x * (1 + humidity) * np.exp(-p.e_p / (BOLTZMANN_EV_K * (mean + 273.15))) ) thermal = ( p.a_tm * (thermal_range_offset + upper - lower) ** p.theta * cycles * np.exp(-p.e_tm / (BOLTZMANN_EV_K * (upper + 273.15))) ) # log1p/expm1 retain tiny rates when A_N == 1. total = np.expm1( np.log(p.a_n) + np.log1p(hydrolysis) + np.log1p(photo) + np.log1p(thermal) ) except FloatingPointError as error: raise ValueError("Degradation calculation overflow; check calibration and units") from error if np.any(total < 0): raise ValueError("Calibration a_n produces negative total degradation; do not clip it") return DegradationRates( *(np.asarray(value, dtype=float) for value in (hydrolysis, photo, thermal, total)) )