"""Replayable interval-mean GHI transposition and training-only effective geometry.
Twelve solar-position substeps distribute hourly GHI proportional to positive
cos(true zenith), conserving its mean. Erbs at these synthetic substeps is an
explicit approximation; it does not reconstruct subhourly cloud variability.
Citations are collected in energy_methods.references: the main thesis,
Reda-Andreas solar position, Erbs, Hay-Davies, Spencer, tracker backtracking,
and pvlib. Effective geometry search and interval disaggregation are project
adaptations, not reconstructed as-built geometry.
"""
from __future__ import annotations
from collections.abc import Sequence
from dataclasses import asdict, dataclass
from typing import Literal
import numpy as np
import pandas as pd
import pvlib
from numpy.typing import ArrayLike
from energy_methods._arrays import FloatArray, aligned, epoch_ns, utc_index, vector
REFERENCE_IDS = (
"ascencio_vasquez_2021_thesis",
"reda_andreas_2004_solar_position",
"erbs_1982_diffuse",
"hay_davies_1980_transposition",
"spencer_1971_solar_fourier",
"anderson_mikofski_2020_backtracking",
"lorenzo_2011_backtracking",
"anderson_2023_pvlib",
)
[docs]
@dataclass(frozen=True, slots=True)
class Geometry:
kind: Literal["fixed", "single_axis"] = "fixed"
tilt_deg: float = 20.0
azimuth_deg: float = 0.0
axis_tilt_deg: float = 0.0
axis_azimuth_deg: float = 0.0
max_angle_deg: float = 60.0
backtrack: bool = True
gcr: float = 0.35
def __post_init__(self) -> None:
if self.kind not in {"fixed", "single_axis"}:
raise ValueError("Only declared fixed and single-axis geometries are supported")
if not 0 <= self.tilt_deg <= 90 or not -90 <= self.axis_tilt_deg <= 90:
raise ValueError("Invalid surface or axis tilt")
if not 0 <= self.azimuth_deg < 360 or not 0 <= self.axis_azimuth_deg < 360:
raise ValueError("Azimuth is degrees clockwise from true north in [0,360)")
if not 0 < self.max_angle_deg <= 90 or not 0 < self.gcr <= 1:
raise ValueError("Invalid tracker rotation limit or ground coverage ratio")
[docs]
@dataclass(frozen=True, slots=True)
class POAResult:
poa_wm2: FloatArray
solar_elevation_deg: FloatArray
[docs]
@dataclass(frozen=True, slots=True)
class EffectivePOAFit:
geometry: Geometry
lag_hours: int
training_correlation: float
training_rows: int
poa_wm2: FloatArray
solar_elevation_deg: FloatArray
training_end_utc: str
[docs]
def to_dict(self) -> dict[str, object]:
"""Small replay specification; arrays remain in the analysis table."""
return {
"reference_ids": list(REFERENCE_IDS),
"geometry": asdict(self.geometry),
"lag_hours": self.lag_hours,
"training_correlation": self.training_correlation,
"training_rows": self.training_rows,
"training_end_utc": self.training_end_utc,
"geometry_verified_as_built": False,
"pvlib_version": pvlib.__version__,
"substeps": 12,
"decomposition": "erbs",
"transposition": "haydavies",
"lag_convention": "positive lag uses an earlier source-weather interval",
}
DEFAULT_GEOMETRY = Geometry()
def _coordinates(latitude: float, longitude: float) -> None:
if not -90 <= latitude <= 90 or not -180 <= longitude <= 180:
raise ValueError("Finite WGS84 latitude and longitude are required")
[docs]
def solar_elevation_midpoint(
timestamps: pd.DatetimeIndex, latitude: float, longitude: float
) -> FloatArray:
"""Original resource evidence independent of fitting or available generation."""
utc = utc_index(timestamps)
_coordinates(latitude, longitude)
if not len(utc):
return np.empty(0, dtype=np.float64)
solar = pvlib.solarposition.get_solarposition(
utc + pd.Timedelta(minutes=30), latitude, longitude, method="nrel_numpy"
)
return np.asarray(solar["elevation"], dtype=np.float64)
@dataclass(frozen=True, slots=True)
class _PreparedIrradiance:
"""One bounded fit's weather-only intermediates, reused across geometries."""
ghi: FloatArray
true_zenith: FloatArray
apparent_zenith: FloatArray
solar_azimuth: FloatArray
flat_ghi: FloatArray
dni: FloatArray
dhi: FloatArray
dni_extra: FloatArray
elevation: FloatArray
substeps: int
def _prepare_irradiance(
utc: pd.DatetimeIndex,
ghi: FloatArray,
latitude: float,
longitude: float,
substeps: int,
) -> _PreparedIrradiance:
offsets = ((np.arange(substeps) + 0.5) * 3_600_000_000_000 / substeps).astype(np.int64)
subtime = pd.to_datetime((epoch_ns(utc)[:, None] + offsets).ravel(), utc=True)
sun = pvlib.solarposition.get_solarposition(subtime, latitude, longitude, method="nrel_numpy")
true_zenith = np.asarray(sun["zenith"], dtype=np.float64)
cosine = np.maximum(np.cos(np.radians(true_zenith)), 0.0).reshape(len(utc), substeps)
mean_cosine = cosine.mean(axis=1)
disaggregated = np.zeros_like(cosine)
valid_ghi = np.isfinite(ghi) & (ghi >= 0)
np.divide(
ghi[:, None] * cosine,
mean_cosine[:, None],
out=disaggregated,
where=(valid_ghi & (mean_cosine > 0))[:, None],
)
flat_ghi = disaggregated.ravel()
parts = pvlib.irradiance.erbs(
flat_ghi, true_zenith, subtime, min_cos_zenith=0.065, max_zenith=87.0
)
return _PreparedIrradiance(
ghi,
true_zenith,
np.asarray(sun["apparent_zenith"], dtype=np.float64),
np.asarray(sun["azimuth"], dtype=np.float64),
flat_ghi,
np.asarray(parts["dni"], dtype=np.float64),
np.asarray(parts["dhi"], dtype=np.float64),
np.asarray(pvlib.irradiance.get_extra_radiation(subtime), dtype=np.float64),
solar_elevation_midpoint(utc, latitude, longitude),
substeps,
)
def _project(prepared: _PreparedIrradiance, geometry: Geometry) -> POAResult:
if geometry.kind == "fixed":
tilt: float | FloatArray = geometry.tilt_deg
azimuth: float | FloatArray = geometry.azimuth_deg
else:
tracking = pvlib.tracking.singleaxis(
prepared.apparent_zenith,
prepared.solar_azimuth,
axis_tilt=geometry.axis_tilt_deg,
axis_azimuth=geometry.axis_azimuth_deg,
max_angle=geometry.max_angle_deg,
backtrack=geometry.backtrack,
gcr=geometry.gcr,
)
tilt = np.nan_to_num(np.asarray(tracking["surface_tilt"], dtype=np.float64))
azimuth = np.nan_to_num(np.asarray(tracking["surface_azimuth"], dtype=np.float64))
total = pvlib.irradiance.get_total_irradiance(
surface_tilt=tilt,
surface_azimuth=azimuth,
solar_zenith=prepared.true_zenith,
solar_azimuth=prepared.solar_azimuth,
dni=prepared.dni,
ghi=prepared.flat_ghi,
dhi=prepared.dhi,
dni_extra=prepared.dni_extra,
model="haydavies",
albedo=0.2,
)
poa = np.maximum(np.asarray(total["poa_global"], dtype=np.float64), 0.0)
poa[prepared.true_zenith >= 90] = 0.0
poa = poa.reshape(len(prepared.ghi), prepared.substeps).mean(axis=1)
poa[~np.isfinite(prepared.ghi) | (prepared.ghi < 0)] = np.nan
return POAResult(poa, prepared.elevation)
[docs]
def transpose_ghi(
timestamps: pd.DatetimeIndex,
ghi_wm2: ArrayLike,
latitude: float,
longitude: float,
geometry: Geometry = DEFAULT_GEOMETRY,
*,
substeps: int = 12,
) -> POAResult:
"""Transpose one-hour mean GHI without consulting any generation observations."""
utc = utc_index(timestamps)
ghi = vector(ghi_wm2, "ghi_wm2")
if len(utc) != len(ghi):
raise ValueError("GHI and timestamps must align")
_coordinates(latitude, longitude)
if not isinstance(substeps, int) or not 1 <= substeps <= 60:
raise ValueError("substeps must be an integer in [1,60]")
if not len(utc):
return POAResult(np.empty(0, dtype=np.float64), np.empty(0, dtype=np.float64))
return _project(_prepare_irradiance(utc, ghi, latitude, longitude, substeps), geometry)
[docs]
def shift_weather(values: ArrayLike, lag_hours: int) -> FloatArray:
"""Shift a regular hourly feature array without circular wrap or gap filling."""
source = vector(values, "weather")
if not isinstance(lag_hours, int):
raise ValueError("lag_hours must be an integer")
result = np.full(len(source), np.nan)
if abs(lag_hours) >= len(source) and lag_hours != 0:
return result
if lag_hours > 0:
result[lag_hours:] = source[:-lag_hours]
elif lag_hours < 0:
result[:lag_hours] = source[-lag_hours:]
else:
result[:] = source
return result
[docs]
def fit_effective_poa(
timestamps: pd.DatetimeIndex,
ghi_wm2: ArrayLike,
actual_mwh: ArrayLike,
latitude: float,
longitude: float,
*,
training_end: pd.Timestamp,
candidates: Sequence[Geometry],
lag_hours: Sequence[int] = (-2, -1, 0, 1, 2),
min_samples: int = 48,
) -> EffectivePOAFit:
"""Choose a bounded geometry/lag bank using training-only Pearson correlation.
Holdout labels are never read by the objective. Shifted training weather is
also restricted to source timestamps within the training interval. Correlation
does not establish true racking geometry or causal time alignment.
"""
utc = utc_index(timestamps, regular_hourly=True)
ghi, actual = aligned(ghi_wm2, actual_mwh)
if len(utc) != len(ghi) or min_samples < 3 or not candidates or not lag_hours:
raise ValueError("Aligned hourly inputs, nonempty candidates and >=3 samples are required")
cutoff = pd.Timestamp(training_end)
if cutoff.tzinfo is None:
raise ValueError("training_end must be timezone-aware")
cutoff = cutoff.tz_convert("UTC")
if any(not isinstance(lag, int) or abs(lag) > 24 for lag in lag_hours):
raise ValueError("Integer weather lags must be within +/-24 hours")
train = np.asarray(utc <= cutoff) & np.isfinite(actual) & (actual >= 0)
train &= np.isfinite(ghi) & (ghi >= 100)
_coordinates(latitude, longitude)
if not len(utc):
raise ValueError("Effective POA fitting requires observations")
prepared = _prepare_irradiance(utc, ghi, latitude, longitude, 12)
best: EffectivePOAFit | None = None
# Candidate count is finite; expensive solar calculations are independent of labels.
for geometry in candidates:
projection = _project(prepared, geometry)
for lag in lag_hours:
shifted = shift_weather(projection.poa_wm2, lag)
source_within_training = np.asarray(utc - pd.Timedelta(hours=lag) <= cutoff)
usable = train & source_within_training & np.isfinite(shifted) & (shifted > 0)
count = int(usable.sum())
if count < min_samples or np.std(actual[usable]) <= 0 or np.std(shifted[usable]) <= 0:
continue
correlation = float(np.corrcoef(shifted[usable], actual[usable])[0, 1])
if not np.isfinite(correlation):
continue
if best is None or correlation > best.training_correlation:
best = EffectivePOAFit(
geometry,
lag,
correlation,
count,
shifted,
projection.solar_elevation_deg,
cutoff.isoformat(),
)
if best is None:
raise ValueError("Insufficient varying training data for effective POA fitting")
return best