"""Explicit sequential power stages for a calibrated spacecraft PV baseline."""
from __future__ import annotations
import numpy as np
import pandas as pd
from numpy.typing import ArrayLike
from .model import PvwattsReference, pvwatts_dc_space
type NumericInput = ArrayLike | pd.Series
def _finite_array(name: str, value: NumericInput) -> np.ndarray:
"""Coerce real numerical values without losing a dimension or missing value."""
try:
raw = np.asarray(value)
if np.iscomplexobj(raw) or (
raw.dtype.kind == "O"
and any(isinstance(item, (complex, np.complexfloating)) for item in raw.flat)
):
raise ValueError(f"{name} must contain real values")
array = (
value.to_numpy(dtype=float, na_value=np.nan)
if isinstance(value, pd.Series)
else np.asarray(value, dtype=float)
)
except (TypeError, ValueError) as error:
raise ValueError(f"{name} must contain finite real numeric values") from error
if array.ndim > 1 or array.size == 0:
raise ValueError(f"{name} must be a scalar or a nonempty one-dimensional input")
if not np.isfinite(array).all():
raise ValueError(f"{name} must contain only finite values")
return np.atleast_1d(array)
def _reference_value(name: str, value: float) -> float:
if np.ndim(value) != 0:
raise ValueError(f"reference.{name} must be a scalar")
return float(_finite_array(f"reference.{name}", value)[0])
[docs]
def pvwatts_loss_chain(
reference: PvwattsReference,
*,
am0_irradiance_w_m2: NumericInput = 1361.0,
illumination_fraction: NumericInput = 1.0,
cosine_aoi: NumericInput = 1.0,
spectral_factor: NumericInput = 1.0,
optical_factor: NumericInput = 1.0,
cell_temperature_c: NumericInput = 25.0,
degradation_factor: NumericInput = 1.0,
mismatch_factor: NumericInput = 1.0,
wiring_efficiency: NumericInput = 1.0,
conversion_efficiency: NumericInput = 1.0,
power_limit_w: NumericInput | None = None,
availability_factor: NumericInput = 1.0,
curtailment_factor: NumericInput = 1.0,
) -> pd.DataFrame:
"""Return a transparent sequence of modeled PV power stages, in watts.
``reference`` specifies beginning-of-life (BOL) array DC power at its
reference irradiance and cell temperature. That calibration already
includes inherent cell and coverglass efficiencies: ``optical_factor``
represents an *additional* transmission factor relative to that reference,
not another multiplication by the cell efficiency or BOL coverglass loss.
Inputs are finite scalars or nonempty one-dimensional arrays. Scalars and
length-one arrays broadcast to the common sample count. Pandas Series must
have identical indexes; their shared index is preserved, without sorting
or label alignment. An indexed length-one Series cannot be broadcast onto
a larger positional array. With no Series inputs, use a RangeIndex.
AM0 irradiance and ``reference.pdc0_w`` must be nonnegative; reference
irradiance must be positive. All fractional inputs are in [0, 1], except
``spectral_factor``, which must be positive and may exceed one. The
temperature multiplier ``1 + gamma * (Tcell - Tref)`` may produce a gain
but cannot be negative. Values outside these domains are rejected rather
than clipped. Zero irradiance, full eclipse and zero available power are
valid. ``power_limit_w=None`` disables clipping; a finite nonnegative
scalar or per-sample limit caps power *after* electrical conversion.
The returned columns, in sequence, are ``reference_power_w``,
``after_irradiance_w``, ``after_eclipse_w``, ``after_pointing_w``,
``after_spectral_w``, ``after_optical_w``, ``after_temperature_w``,
``after_degradation_w``, ``after_mismatch_w``, ``after_wiring_w``,
``after_conversion_w``, ``after_clipping_w``, ``after_availability_w``,
and ``modeled_power_w`` (after curtailment). The temperature stage calls
:func:`pvwatts_dc_space` with the accumulated effective irradiance.
Through ``after_wiring_w``, power is on the array DC side. Conversion is a
generic DC/DC or other chosen electronics boundary; it does not imply a
terrestrial AC inverter. The cap, availability and curtailment apply on
that output side. Compare measurements at the same electrical boundary.
Battery storage, spacecraft loads and converter standby consumption are
not modeled. Set post-array factors to one and omit the cap for an array
DC-only comparison.
Factors are supplied assumptions or independently established states,
not inferred diagnoses. Differences between consecutive stages provide
an order-dependent accounting, not unique causal attribution. Irradiance,
spectral and temperature changes can create signed gains relative to the
reference. This is the existing calibrated PVWatts engineering baseline,
not a multi-junction spectral or radiation-damage model.
See Also
--------
pvwatts_dc_space : PVWatts DC equation with a space irradiance reference.
References
----------
* pvlib PVWatts DC model:
https://pvlib-python.readthedocs.io/en/stable/reference/generated/pvlib.pvsystem.pvwatts_dc.html
* NASA Small Spacecraft Technology, Power:
https://www.nasa.gov/smallsat-institute/sst-soa/power-subsystems/
"""
if not isinstance(reference, PvwattsReference):
raise TypeError("reference must be a PvwattsReference")
pdc0_w = _reference_value("pdc0_w", reference.pdc0_w)
reference_irradiance = _reference_value(
"reference_irradiance_w_m2", reference.reference_irradiance_w_m2
)
reference_temperature = _reference_value(
"reference_temperature_c", reference.reference_temperature_c
)
gamma = _reference_value("gamma_pdc_per_c", reference.gamma_pdc_per_c)
if pdc0_w < 0:
raise ValueError("reference.pdc0_w must be nonnegative")
if reference_irradiance <= 0:
raise ValueError("reference.reference_irradiance_w_m2 must be positive")
validated_reference = PvwattsReference(
pdc0_w, gamma, reference_irradiance, reference_temperature
)
inputs = {
"am0_irradiance_w_m2": am0_irradiance_w_m2,
"illumination_fraction": illumination_fraction,
"cosine_aoi": cosine_aoi,
"spectral_factor": spectral_factor,
"optical_factor": optical_factor,
"cell_temperature_c": cell_temperature_c,
"degradation_factor": degradation_factor,
"mismatch_factor": mismatch_factor,
"wiring_efficiency": wiring_efficiency,
"conversion_efficiency": conversion_efficiency,
"availability_factor": availability_factor,
"curtailment_factor": curtailment_factor,
}
if power_limit_w is not None:
inputs["power_limit_w"] = power_limit_w
index = None
for name, value in inputs.items():
if isinstance(value, pd.Series):
if index is None:
index = value.index
elif not index.equals(value.index):
raise ValueError(f"{name}: all pandas Series inputs must have identical indexes")
arrays = {name: _finite_array(name, value) for name, value in inputs.items()}
size = max(array.size for array in arrays.values())
if any(array.size not in (1, size) for array in arrays.values()):
raise ValueError("inputs must broadcast to one common one-dimensional sample count")
if index is not None and len(index) != size:
raise ValueError("a pandas Series index must match the broadcast sample count")
arrays = {name: np.broadcast_to(array, (size,)) for name, array in arrays.items()}
for name, values in arrays.items():
if name in ("am0_irradiance_w_m2", "power_limit_w"):
if (values < 0).any():
raise ValueError(f"{name} must be nonnegative")
elif name == "spectral_factor":
if (values <= 0).any():
raise ValueError("spectral_factor must be positive")
elif name != "cell_temperature_c" and ((values < 0) | (values > 1)).any():
raise ValueError(f"{name} must be in [0, 1]")
with np.errstate(over="ignore", invalid="ignore"):
thermal_factor = 1.0 + gamma * (arrays["cell_temperature_c"] - reference_temperature)
if not np.isfinite(thermal_factor).all() or (thermal_factor < 0).any():
raise ValueError("temperature multiplier must be finite and nonnegative")
# Reuse the existing DC equation rather than introduce a second version.
# The earlier columns make its multiplicative inputs separately inspectable.
with np.errstate(over="ignore", invalid="ignore", divide="ignore"):
stages = {"reference_power_w": np.full(size, pdc0_w)}
power = pdc0_w * (arrays["am0_irradiance_w_m2"] / reference_irradiance)
stages["after_irradiance_w"] = power
effective_irradiance = arrays["am0_irradiance_w_m2"].copy()
for factor, column in (
("illumination_fraction", "after_eclipse_w"),
("cosine_aoi", "after_pointing_w"),
("spectral_factor", "after_spectral_w"),
("optical_factor", "after_optical_w"),
):
power = power * arrays[factor]
effective_irradiance = effective_irradiance * arrays[factor]
stages[column] = power
power = pvwatts_dc_space(
effective_irradiance, arrays["cell_temperature_c"], validated_reference
)
stages["after_temperature_w"] = power
for factor, column in (
("degradation_factor", "after_degradation_w"),
("mismatch_factor", "after_mismatch_w"),
("wiring_efficiency", "after_wiring_w"),
("conversion_efficiency", "after_conversion_w"),
):
power = power * arrays[factor]
stages[column] = power
if power_limit_w is not None:
power = np.minimum(power, arrays["power_limit_w"])
stages["after_clipping_w"] = power
power = power * arrays["availability_factor"]
stages["after_availability_w"] = power
stages["modeled_power_w"] = power * arrays["curtailment_factor"]
frame = pd.DataFrame(stages, index=index)
if not np.isfinite(frame.to_numpy()).all():
raise ValueError("inputs produce nonfinite stage power; check magnitudes and reference")
return frame