Source code for energy_methods.pvcz

"""Karin, Jones and Jain (2019) PVCZ thresholds and Arrhenius stress.

Table I: ten temperature zones by five specific-humidity zones. This is a
stressor classification, not a predicted degradation rate or lifetime.
"""

from __future__ import annotations

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

from energy_methods.climate_zones import ClimateProvenance, ClimateZones

REFERENCE_IDS = ("ascencio_vasquez_2021_thesis", "karin_2019_pvcz")
TEMPERATURE_THRESHOLDS_C = (14.0, 19.0, 24.0, 29.0, 34.0, 39.0, 44.0, 49.0, 54.0)
HUMIDITY_THRESHOLDS_G_KG = (3.0, 4.1, 5.9, 10.5)
ZONE_CODES = ("", *(f"T{t}:H{h}" for h in range(1, 6) for t in range(1, 11)))


def _interval_label(value: int, edges: tuple[float, ...], unit: str) -> str:
    if value == 1:
        return f"<{edges[0]:g} {unit}"
    if value == len(edges) + 1:
        return f"≥{edges[-1]:g} {unit}"
    return f"{edges[value - 2]:g}-<{edges[value - 1]:g} {unit}"


ZONE_LABELS = (
    "Unclassified",
    *(
        f"Module stress {_interval_label(t, TEMPERATURE_THRESHOLDS_C, '°C')}; "
        f"humidity {_interval_label(h, HUMIDITY_THRESHOLDS_G_KG, 'g/kg')}"
        for h in range(1, 6)
        for t in range(1, 11)
    ),
)


[docs] def equivalent_temperature( temperature_c: ArrayLike, *, activation_energy_ev: float = 1.1, duration_hours: ArrayLike = 1.0 ) -> NDArray[np.float64]: """Arrhenius-equivalent °C over the last axis, weighted by interval duration. Supply module temperatures including nights. Any missing interval makes its result missing; there is no gap filling. A time series with explicit missing rows is required to represent gaps. Duration cannot reveal omitted rows. """ temperature = np.asarray(temperature_c, dtype=float) if temperature.ndim < 1 or temperature.shape[-1] == 0: raise ValueError("A nonempty time axis is required") dt = np.broadcast_to(np.asarray(duration_hours, dtype=float), temperature.shape) if ( not np.isfinite(activation_energy_ev) or activation_energy_ev <= 0 or np.isinf(temperature).any() or np.any(temperature <= -273.15) or not np.isfinite(dt).all() or np.any(dt <= 0) ): raise ValueError("Positive activation energy/durations and physical temperatures required") a = activation_energy_ev / 8.617333262145e-5 # Boltzmann constant in eV/K mean_log = logsumexp(-a / (temperature + 273.15) + np.log(dt), axis=-1) mean_log -= np.log(np.sum(dt, axis=-1)) return np.asarray(-a / mean_log - 273.15)
[docs] def classify_pvcz( equivalent_temperature_c: ArrayLike, specific_humidity_g_kg: ArrayLike, *, provenance: ClimateProvenance, ) -> ClimateZones: """Apply fixed published boundaries; equality enters the warmer/wetter class. Humidity is specific humidity (g/kg), never relative humidity (%). Positive IDs are the upstream zero-based PVCZ ID + 1, leaving zero for missing inputs. Use the reference 1.1 eV equivalent temperature for the published scheme. """ t, h = np.broadcast_arrays( np.asarray(equivalent_temperature_c, dtype=float), np.asarray(specific_humidity_g_kg, dtype=float), ) if ( np.isinf(t).any() or np.isinf(h).any() or np.any(t <= -273.15) or np.any((h < 0) | (h > 1000)) ): raise ValueError("Physical temperature and specific humidity in g/kg required") good = np.isfinite(t) & np.isfinite(h) ids = np.where( good, np.searchsorted(TEMPERATURE_THRESHOLDS_C, t, side="right") + 10 * np.searchsorted(HUMIDITY_THRESHOLDS_G_KG, h, side="right") + 1, 0, ) return ClimateZones( "pvcz-2019", ids.astype(np.int64), ZONE_CODES, ZONE_LABELS, provenance, REFERENCE_IDS )