Source code for energy_methods.pv_stress_weather

"""POA-based temperature, UV and humidity models, 2021 study Eqs. 7-17.

All arrays must be finite. Filter night and missing observations explicitly
before calibration; these functions do not align timestamps or impute weather.
"""

from __future__ import annotations

from typing import Literal

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

from energy_methods.degradation_weather import faiman_from_ghi
from energy_methods.pv_reliability import _finite

REFERENCE_IDS = ("ascencio_vasquez_2021_thesis", "kaaya_2021_uncertainties")


def _weather(temperature: ArrayLike, poa: ArrayLike) -> tuple[NDArray, NDArray]:
    t, g = np.broadcast_arrays(_finite(temperature, "temperature"), _finite(poa, "poa"))
    if np.any(t <= -273.15) or np.any(g < 0):
        raise ValueError("Invalid temperature or negative POA irradiance")
    return t, g


[docs] def ross_temperature( ambient_temperature_c: ArrayLike, poa_w_m2: ArrayLike, *, coefficient: float ) -> NDArray[np.float64]: """Equation 7, module °C; coefficient in °C m²/W is explicit.""" t, g = _weather(ambient_temperature_c, poa_w_m2) if not np.isfinite(coefficient) or coefficient < 0: raise ValueError("Ross coefficient must be finite and nonnegative") return t + coefficient * g
[docs] def faiman_temperature( ambient_temperature_c: ArrayLike, poa_w_m2: ArrayLike, wind_speed_ms: ArrayLike, *, u0: float, u1: float, ) -> NDArray[np.float64]: """Equation 8, module °C using POA and wind at the calibration's height. Reuse the existing algebra with unity wind-height scaling. No GHI-to-POA substitution, wind-height conversion or site-independent coefficient fit. """ t, g = _weather(ambient_temperature_c, poa_w_m2) wind = _finite(wind_speed_ms, "wind speed") return faiman_from_ghi(t, g, wind, u0=u0, u1=u1, module_height_m=10)
[docs] def linear_uv(poa_w_m2: ArrayLike, *, slope: float, intercept: float = 0) -> NDArray: """Equation 9, UV W/m². Outputs outside [0, POA] fail rather than clip.""" g = _finite(poa_w_m2, "POA") if not np.isfinite([slope, intercept]).all(): raise ValueError("UV coefficients must be finite") return _check_uv(g, slope * g + intercept)
def _check_uv(poa: NDArray, uv: NDArray) -> NDArray: if np.any(poa < 0) or not np.isfinite(uv).all() or np.any((uv < 0) | (uv > poa)): raise ValueError("UV model is outside its physical domain: require 0 <= UV <= POA") return uv
[docs] def wald_uv( poa_w_m2: ArrayLike, clearness_index: ArrayLike, *, a: float = 7.210, b: float = 2.365 ) -> NDArray: """Equations 10-14, UV 280-400 nm in W/m²; kt clamped to [0.1, 0.7]. The default is original Wald. Modified coefficients use ``a - b*kt``; negative b in Table 9 is retained, not silently sign-corrected. """ g, kt = np.broadcast_arrays(_finite(poa_w_m2, "POA"), _finite(clearness_index, "kt")) if not np.isfinite([a, b]).all() or np.any(kt < 0): raise ValueError("Invalid UV coefficients or negative clearness index") kt = np.clip(kt, 0.1, 0.7) return _check_uv(g, g * ((a - b * kt) * 0.01 + (1.897 - 0.860 * kt) * 0.001))
[docs] def airmass_uv(poa_w_m2: ArrayLike, air_mass: ArrayLike, *, coefficients: ArrayLike) -> NDArray: """Equation 15: POA times a fourth-degree polynomial in air mass. Five coefficients ordered m0..m4 are required. Air mass must be >=1; extrapolation producing a UV fraction outside [0,1] fails. """ g, am = np.broadcast_arrays(_finite(poa_w_m2, "POA"), _finite(air_mass, "air mass")) c = _finite(coefficients, "coefficients") if c.shape != (5,) or np.any(am < 1): raise ValueError("Five coefficients and air mass >= 1 are required") return _check_uv(g, g * np.polynomial.polynomial.polyval(am, c))
[docs] def buck_vapour_pressure(temperature_c: ArrayLike) -> NDArray: """Equation 17 saturation vapour pressure, kPa, with ice/water branches. Values 0.61115/0.61121 are kPa despite the nomenclature's Pa label. The documented operating domain here is -80..60 °C; no extrapolation. """ t = _finite(temperature_c, "temperature") if np.any((t < -80) | (t > 60)): raise ValueError("Buck temperature must be within -80 to 60 degrees C") ice = 0.61115 * np.exp((23.036 - t / 333.70) * t / (279.82 + t)) water = 0.61121 * np.exp((18.678 - t / 234.84) * t / (257.14 + t)) return np.where(t < 0, ice, water)
[docs] def buck_relative_humidity(ambient_temperature_c: ArrayLike, dewpoint_c: ArrayLike) -> NDArray: """Equation 16, percent; reject dewpoint above ambient instead of clipping.""" ambient, dewpoint = np.broadcast_arrays( _finite(ambient_temperature_c, "ambient"), _finite(dewpoint_c, "dewpoint") ) if np.any(dewpoint > ambient): raise ValueError("Dewpoint cannot exceed ambient temperature") return 100 * buck_vapour_pressure(dewpoint) / buck_vapour_pressure(ambient)
[docs] def fit_temperature_model( ambient_temperature_c: ArrayLike, poa_w_m2: ArrayLike, measured_module_c: ArrayLike, *, model: Literal["ross", "faiman"], wind_speed_ms: ArrayLike | None = None, ) -> dict[str, float]: """Least-squares coefficients on a declared calibration interval only. Equal one-dimensional shapes, positive POA, and an identifiable design are required. Evaluate errors on another year; do not mix train and test records. """ t, g, measured = [ _finite(v, name) for v, name in ( (ambient_temperature_c, "ambient"), (poa_w_m2, "POA"), (measured_module_c, "module temperature"), ) ] if t.ndim != 1 or t.shape != g.shape or t.shape != measured.shape or t.size < 3: raise ValueError("Calibration requires matching vectors with at least three observations") _weather(t, g) if np.any(g <= 0) or np.any(measured <= -273.15): raise ValueError("Calibration requires positive POA and physical module temperatures") if model == "ross": coefficient = float(np.dot(g, measured - t) / np.dot(g, g)) if coefficient < 0: raise ValueError("Calibration produces a negative Ross coefficient") return {"coefficient": coefficient} if model != "faiman" or wind_speed_ms is None: raise ValueError("Choose ross or faiman; faiman requires wind speed") wind = _finite(wind_speed_ms, "wind") if wind.shape != t.shape or np.any(wind < 0) or np.ptp(wind) == 0: raise ValueError("Faiman requires matching, nonnegative, varying wind speed") result = least_squares( lambda p: faiman_temperature(t, g, wind, u0=p[0], u1=p[1]) - measured, [25.0, 6.0], bounds=([1e-6, 0], [np.inf, np.inf]), ftol=1e-12, gtol=1e-12, xtol=1e-12, ) if not result.success or np.linalg.matrix_rank(result.jac) < 2: raise ValueError("Faiman calibration failed or is not identifiable") return {"u0": float(result.x[0]), "u1": float(result.x[1])}