Source code for space_pv_pvmodel.pointing
"""Instantaneous cosine-law array pointing constraints at the regulated bus."""
from __future__ import annotations
import numpy as np
import pandas as pd
from numpy.typing import ArrayLike
[docs]
def pointing_power_envelope(
normal_bus_w: ArrayLike,
load_w: float,
*,
reserve_fraction: float = 0.2,
offpoint_deg: float = 30.0,
) -> pd.DataFrame:
"""Screen sunlit, fixed-array pointing against a load plus reserve.
``normal_bus_w`` is a nonempty scalar or 1-D sequence of available bus power
at normal incidence, in W, after distance and electrical/retention losses.
Required power is ``load_w * (1 + reserve_fraction)``. The maximum angle
between the array normal and Sun direction is acos(required/normal), in
degrees. An infeasible normal-incidence state has a NaN angle, not zero.
``headroom_w`` is generation at ``offpoint_deg`` minus required power.
This instantaneous cosine law assumes uniform, unshadowed illumination and
constant electrical efficiency. It excludes eclipses, battery support,
temperature response, gimbal limits and bus voltage constraints. A reserve
fraction is an engineering assumption, not a probabilistic confidence bound.
"""
normal = np.atleast_1d(np.asarray(normal_bus_w, dtype=float))
if normal.ndim != 1 or normal.size == 0 or not np.isfinite(normal).all():
raise ValueError("normal_bus_w must be a nonempty finite scalar or 1-D array")
if (normal < 0).any():
raise ValueError("normal_bus_w must be nonnegative")
if not np.isfinite(load_w) or load_w <= 0:
raise ValueError("load_w must be finite and positive")
if not np.isfinite(reserve_fraction) or reserve_fraction < 0:
raise ValueError("reserve_fraction must be finite and nonnegative")
if not np.isfinite(offpoint_deg) or not 0 <= offpoint_deg <= 90:
raise ValueError("offpoint_deg must be between 0 and 90 degrees")
required = load_w * (1 + reserve_fraction)
if not np.isfinite(required):
raise ValueError("required bus power must be finite")
feasible = normal >= required
angle = np.full(normal.shape, np.nan)
angle[feasible] = np.rad2deg(np.arccos(np.clip(required / normal[feasible], 0, 1)))
at_angle = normal * np.cos(np.deg2rad(offpoint_deg))
if offpoint_deg == 90:
at_angle[:] = 0.0
return pd.DataFrame(
{
"normal_bus_w": normal,
"required_bus_w": required,
"normal_feasible": feasible,
"max_offpoint_deg": angle,
"offpoint_bus_w": at_angle,
"headroom_w": at_angle - required,
"offpoint_feasible": at_angle >= required,
}
)