Source code for energy_methods.physics

"""Shape-constrained PV regression on POA and ambient temperature.

Nonnegative coefficients analytically enforce a nondecreasing, concave response
to irradiance and a nonincreasing response to temperature on the declared domain.
These are empirical response constraints, not identified module thermal physics.

Cite the main thesis for scientific context, Stark-Parker for the BVLS
solver and SciPy for its implementation; the transformed PV basis is this
repository's parameterization. See energy_methods.references.
"""

from __future__ import annotations

from dataclasses import asdict, dataclass
from typing import Literal

import numpy as np
from numpy.typing import ArrayLike
from scipy.optimize import lsq_linear

from energy_methods._arrays import BoolArray, FloatArray, aligned, immutable

REFERENCE_IDS = ("ascencio_vasquez_2021_thesis", "stark_parker_1995_bvls", "virtanen_2020_scipy")


[docs] @dataclass(frozen=True, slots=True) class PhysicsConfig: family: Literal["thermal_quadratic", "concave_spline"] = "concave_spline" alpha: float = 0.1 min_samples: int = 24 poa_max_wm2: float = 1300.0 temperature_min_c: float = -20.0 temperature_max_c: float = 60.0 operational_zero_poa_wm2: float = 1.0 knots_wm2: tuple[float, ...] = (200.0, 400.0, 600.0, 800.0, 1000.0, 1200.0) def __post_init__(self) -> None: if self.family not in {"thermal_quadratic", "concave_spline"}: raise ValueError("Unknown physical response family") values = [ self.alpha, self.poa_max_wm2, self.temperature_min_c, self.temperature_max_c, self.operational_zero_poa_wm2, *self.knots_wm2, ] if not np.isfinite(values).all() or self.alpha < 0 or self.min_samples < 3: raise ValueError( "Finite model settings, nonnegative alpha and >=3 samples are required" ) if not 0 <= self.operational_zero_poa_wm2 < self.poa_max_wm2: raise ValueError("Invalid POA domain or startup cutoff") if self.temperature_min_c >= self.temperature_max_c: raise ValueError("Temperature bounds must be ordered") if any(not 0 < knot < self.poa_max_wm2 for knot in self.knots_wm2): raise ValueError("Spline knots must be strictly inside the irradiance domain") if tuple(sorted(set(self.knots_wm2))) != self.knots_wm2: raise ValueError("Spline knots must be unique and increasing")
DEFAULT_CONFIG = PhysicsConfig() def _design(poa: FloatArray, temperature: FloatArray, config: PhysicsConfig) -> FloatArray: g, t = poa / 1000.0, (temperature - 25.0) / 25.0 tmax = (config.temperature_max_c - 25.0) / 25.0 if config.family == "thermal_quadratic": gmax = config.poa_max_wm2 / 1000.0 return np.column_stack((g, g * (2 * gmax - g), g * (tmax - t))) return np.column_stack( (g, *[np.minimum(g, k / 1000.0) for k in config.knots_wm2], g * (tmax - t)) )
[docs] @dataclass(frozen=True, slots=True) class PhysicsModel: config: PhysicsConfig coefficients: FloatArray training_scale_mwh: float training_rows: int poa_support_wm2: tuple[float, float] temperature_support_c: tuple[float, float]
[docs] def to_dict(self) -> dict[str, object]: """Portable fitted state; no opaque estimator or executable serialization.""" return { "method": "shape_constrained_physical_response", "reference_ids": list(REFERENCE_IDS), "config": asdict(self.config), "coefficients": self.coefficients.tolist(), "training_scale_mwh": self.training_scale_mwh, "training_rows": self.training_rows, "poa_support_wm2": list(self.poa_support_wm2), "temperature_support_c": list(self.temperature_support_c), "parameterization": "nonnegative_transformed_basis", "irradiance_concavity": "analytic_on_declared_domain_before_startup_cutoff", "identified_thermal_parameters": False, }
[docs] def predict(self, poa_wm2: ArrayLike, temperature_c: ArrayLike) -> FloatArray: """Return NaN outside the declared domain; startup cutoff is separate.""" poa, temperature = aligned(poa_wm2, temperature_c) result = np.full(len(poa), np.nan) valid = np.isfinite(poa) & np.isfinite(temperature) & (poa >= 0) valid &= poa <= self.config.poa_max_wm2 valid &= temperature >= self.config.temperature_min_c valid &= temperature <= self.config.temperature_max_c result[valid] = np.maximum( _design(poa[valid], temperature[valid], self.config)
[docs] @ self.coefficients * self.training_scale_mwh, 0.0, ) result[valid & (poa <= self.config.operational_zero_poa_wm2)] = 0.0 return result
def weather_support(self, poa_wm2: ArrayLike, temperature_c: ArrayLike) -> BoolArray: """Training-observed rectangular support, separate from physical domain.""" poa, temperature = aligned(poa_wm2, temperature_c) return ( np.isfinite(poa) & np.isfinite(temperature) & (poa >= self.poa_support_wm2[0]) & (poa <= self.poa_support_wm2[1]) & (temperature >= self.temperature_support_c[0]) & (temperature <= self.temperature_support_c[1]) )
[docs] def fit_physics_model( poa_wm2: ArrayLike, temperature_c: ArrayLike, actual_mwh: ArrayLike, *, config: PhysicsConfig = DEFAULT_CONFIG, ) -> PhysicsModel: """Fit only supplied accepted training rows using nonnegative least squares.""" poa, temperature, actual = aligned(poa_wm2, temperature_c, actual_mwh) valid = np.isfinite(poa) & np.isfinite(temperature) & np.isfinite(actual) & (actual >= 0) valid &= (poa >= 0) & (poa <= config.poa_max_wm2) valid &= (temperature >= config.temperature_min_c) & (temperature <= config.temperature_max_c) if int(valid.sum()) < config.min_samples: raise ValueError("Insufficient accepted finite training rows for the physical model") poa, temperature, actual = poa[valid], temperature[valid], actual[valid] scale = float(np.quantile(actual, 0.95, method="linear")) if scale <= 0: raise ValueError("Accepted-training Q95 energy must be positive") design = _design(poa, temperature, config) if config.family == "thermal_quadratic": penalty = np.asarray( [ [1.0, 2 * config.poa_max_wm2 / 1000.0, (config.temperature_max_c - 25) / 25], [0.0, -1.0, 0.0], [0.0, 0.0, -1.0], ] ) else: penalty = np.eye(design.shape[1]) augmented = np.vstack((design, np.sqrt(config.alpha) * penalty)) target = np.concatenate((actual / scale, np.zeros(penalty.shape[0]))) solved = lsq_linear( augmented, target, bounds=(0.0, np.inf), method="bvls", tol=1e-12, max_iter=1000 ) if not solved.success or not np.isfinite(solved.x).all(): raise RuntimeError(f"Constrained least squares failed: {solved.message}") return PhysicsModel( config, immutable(np.maximum(solved.x, 0.0)), scale, len(actual), (float(poa.min()), float(poa.max())), (float(temperature.min()), float(temperature.max())), )