Source code for space_pv_pvmodel.lunar

"""Lunar PV screening, explicit thermal forcing and storage design sweeps."""

from __future__ import annotations

from dataclasses import replace
from typing import Literal

import numpy as np
import pandas as pd
from numpy.typing import ArrayLike

from space_pv_space_env.lunar import solar_disc_visibility
from space_pv_space_env.thermal import STEFAN_BOLTZMANN, ThermalSurface, simulate_panel_thermal

from .eps import BatterySpec, dispatch_power
from .model import PvwattsReference, pvwatts_dc_space


def _positive(value: float, name: str, *, zero: bool = False) -> None:
    if not np.isfinite(value) or (value < 0 if zero else value <= 0):
        raise ValueError(f"{name} must be finite and {'non-negative' if zero else 'positive'}")


def _series(value: ArrayLike, n: int, name: str) -> np.ndarray:
    a = np.broadcast_to(np.asarray(value, dtype=float), (n,)).copy()
    if not np.isfinite(a).all():
        raise ValueError(f"{name} must be finite")
    return a


[docs] def lunar_pv_power( geometry: pd.DataFrame, horizon: pd.DataFrame, *, reference: PvwattsReference, cell_temperature_c: ArrayLike, mode: Literal["fixed", "azimuth_tracking", "sun_tracking"] = "fixed", tilt_deg: float = 90.0, panel_azimuth_deg: float = 0.0, optical_retention: ArrayLike = 1.0, ) -> pd.DataFrame: """Project direct AM0 radiation and reuse the calibrated PVWatts baseline. Tilt is from horizontal, azimuth clockwise from true north. Azimuth tracking keeps the selected tilt; sun tracking follows the centre of the Sun in two axes (including small negative elevations from elevated sites). No sky diffuse, ground-reflected light, self-shading, tracker power, degradation or spectral correction is implicit. Optical retention is a supplied scenario. Earth/terrain visibility fractions are multiplied: their simultaneous overlap is approximate. Disc area visibility uses centre-ray incidence. """ if mode not in {"fixed", "azimuth_tracking", "sun_tracking"}: raise ValueError("Unknown tracking mode") if not np.isfinite([tilt_deg, panel_azimuth_deg]).all() or not 0 <= tilt_deg <= 180: raise ValueError("Finite angles and tilt in [0,180] required") required = [ "azimuth_deg", "elevation_deg", "solar_angular_radius_deg", "earth_visible_fraction", "unobstructed_dni_w_m2", ] values = geometry[required].to_numpy(dtype=float) if len(values) == 0 or not np.isfinite(values).all(): raise ValueError("Geometry must contain finite, nonempty data") az, el, radius, earth, dni = values.T if np.any((earth < 0) | (earth > 1)) or np.any(dni < 0): raise ValueError("Invalid eclipse fraction or irradiance") n = len(horizon) expected_az = (np.arange(n) + 0.5) * 360 / max(n, 1) if n < 4 or not np.allclose(horizon.azimuth_deg, expected_az): raise ValueError("Horizon must use complete, regular sector centres") angles = horizon.horizon_elevation_deg.to_numpy(dtype=float) if not np.isfinite(angles).all() or np.any(np.abs(angles) > 90): raise ValueError("Invalid horizon angles") sector = np.minimum((np.mod(az, 360) / 360 * n).astype(int), n - 1) skyline = angles[sector] visible = solar_disc_visibility(el, skyline, radius) if mode == "sun_tracking": incidence = np.ones(len(geometry)) else: delta = ( np.zeros(len(az)) if mode == "azimuth_tracking" else np.deg2rad(az - panel_azimuth_deg) ) beta = np.deg2rad(tilt_deg) incidence = np.maximum( 0, np.sin(np.deg2rad(el)) * np.cos(beta) + np.cos(np.deg2rad(el)) * np.sin(beta) * np.cos(delta), ) retention = _series(optical_retention, len(geometry), "optical_retention") temperature = _series(cell_temperature_c, len(geometry), "cell_temperature_c") if np.any((retention < 0) | (retention > 1)) or np.any(temperature <= -273.15): raise ValueError("Retention must be in [0,1] and temperature above absolute zero") _positive(reference.pdc0_w, "reference power") _positive(reference.reference_irradiance_w_m2, "reference irradiance") if not np.isfinite([reference.gamma_pdc_per_c, reference.reference_temperature_c]).all(): raise ValueError("Reference must be finite") if np.any( 1 + reference.gamma_pdc_per_c * (temperature - reference.reference_temperature_c) < 0 ): raise ValueError("Temperature correction would yield negative power") poa = dni * earth * visible * incidence * retention result = geometry.copy() result["horizon_elevation_deg"] = skyline result["terrain_visible_fraction"] = visible result["cosine_incidence"] = incidence result["poa_direct_w_m2"] = poa result["cell_temperature_c"] = temperature result["dc_power_w"] = pvwatts_dc_space(poa, temperature, reference) result.attrs.update(mode=mode, model="direct AM0; sector horizon; calibrated scalar PVWatts") return result
[docs] def lunar_panel_thermal( time_s: ArrayLike, poa_direct_w_m2: ArrayLike, *, ground_temperature_k: ArrayLike, ground_view_factor: float, ground_emissivity: float = 0.95, surface: ThermalSurface | None = None, **thermal_options, ) -> pd.DataFrame: """Reuse the vacuum thermal balance with explicit lunar ground IR. View factor is averaged over *all emitting panel faces*. Multiplication by radiating_area/receiving_area converts it to the existing solver's receiving area convention. For bolometric brightness temperature (Diviner), set ``ground_emissivity=1`` because emissivity is already encoded in radiance. For physical ground temperature, supply its emissivity. Ground-reflected background IR is neglected. Surface temperatures are environmental boundary values, not cell temperatures. Direct forcing and ground values at index i apply to (time[i-1], time[i]]; the first sample initializes the model. """ surface = surface or ThermalSurface() for name, value in ( ("ground_view_factor", ground_view_factor), ("ground_emissivity", ground_emissivity), ): if not np.isfinite(value) or not 0 <= value <= 1: raise ValueError(f"{name} must be in [0,1]") temperature = _series(ground_temperature_k, len(np.asarray(time_s)), "ground_temperature_k") if np.any(temperature <= 0): raise ValueError("Ground temperature must be positive Kelvin") ground_ir = ( surface.radiating_area_m2 / surface.area_m2 * ground_view_factor * ground_emissivity * STEFAN_BOLTZMANN * temperature**4 ) # Restrict the existing solver's uniform background term to the sky-facing # fraction. Ground irradiance is then added once, in its receiving-area units. surface = replace( surface, sink_temperature_k=surface.sink_temperature_k * (1 - ground_view_factor) ** 0.25 ) result = simulate_panel_thermal( time_s, poa_direct_w_m2, surface=surface, earth_ir_w_m2=ground_ir, **thermal_options ) result["ground_temperature_k"] = temperature result["ground_ir_on_receiving_area_w_m2"] = ground_ir result.attrs["environment"] = "lunar ground IR; vacuum; no convective cooling" return result
[docs] def survival_heater_power( sink_temperature_k: ArrayLike, *, setpoint_k: float, thermal_conductance_w_k: float, internal_heat_w: ArrayLike = 0.0, ) -> np.ndarray: """Steady equivalent-conductance heater demand, max(UA*(Tset-Tsink)-Q,0). UA is a user-supplied effective thermal-loss coefficient, not lunar air convection. This screening relation omits thermal mass and must not be confused with the separate nonlinear panel thermal model. """ _positive(setpoint_k, "setpoint_k") _positive(thermal_conductance_w_k, "thermal_conductance_w_k", zero=True) t, q = np.broadcast_arrays( np.asarray(sink_temperature_k, dtype=float), np.asarray(internal_heat_w, dtype=float) ) if not np.isfinite(t).all() or not np.isfinite(q).all() or np.any(t <= 0) or np.any(q < 0): raise ValueError("Positive Kelvin and non-negative finite internal heat required") return np.maximum(thermal_conductance_w_k * (setpoint_k - t) - q, 0)
[docs] def longest_darkness_hours( time_s: ArrayLike, visible_fraction: ArrayLike, *, threshold: float = 0.01 ) -> float: """Longest contiguous low-visibility interval; no wraparound is assumed. Times are N+1 boundaries and visibility has N interval values. Results are censored by the simulation start/end, and resolved only at the supplied step. """ t = np.asarray(time_s, dtype=float) if t.ndim != 1 or len(t) < 2 or not np.isfinite(t).all() or np.any(np.diff(t) <= 0): raise ValueError("Require increasing finite interval boundaries") v = _series(visible_fraction, len(t) - 1, "visible_fraction") if not np.isfinite(threshold) or not 0 <= threshold <= 1 or np.any((v < 0) | (v > 1)): raise ValueError("Visibility and threshold must be in [0,1]") longest = current = 0.0 for dt, fraction in zip(np.diff(t), v, strict=True): current = current + float(dt) if fraction <= threshold else 0.0 longest = max(longest, current) return longest / 3600
[docs] def size_lunar_storage( time_s: ArrayLike, generation_per_m2_w: ArrayLike, demand_w: ArrayLike, *, array_areas_m2: ArrayLike, capacities_wh: ArrayLike, battery_template: BatterySpec, array_mass_kg_m2: float = 3.0, battery_specific_energy_wh_kg: float = 150.0, require_terminal_soc: bool = True, ) -> pd.DataFrame: """Enumerate PV/storage candidates using existing energy-conserving dispatch. Feasible means zero unmet energy (1e-6 Wh tolerance) and, by default, final SOC >= initial SOC. The latter prevents initially charged batteries from disguising an energy deficit. This does not establish multi-year survival. Mass is an explicit panel+battery scenario excluding structures, conversion, insulation and redundancy. Battery properties are constant, not temperature or ageing dependent. Grid minimum is not a continuous global optimum. """ areas, capacities = ( np.asarray(array_areas_m2, dtype=float), np.asarray(capacities_wh, dtype=float), ) for name, a in (("array_areas_m2", areas), ("capacities_wh", capacities)): if a.ndim != 1 or len(a) == 0 or not np.isfinite(a).all() or np.any(a <= 0): raise ValueError(f"{name} must be a nonempty positive vector") _positive(array_mass_kg_m2, "array_mass_kg_m2") _positive(battery_specific_energy_wh_kg, "battery_specific_energy_wh_kg") rows = [] for area in areas: for capacity in capacities: battery = replace(battery_template, capacity_wh=float(capacity)) dispatch = dispatch_power( time_s, np.asarray(generation_per_m2_w) * area, demand_w, battery=battery ) unserved = float((dispatch.unserved_load_w * dispatch.duration_h).sum()) terminal = float(dispatch.soc_end.iloc[-1]) sustainable = terminal >= battery.initial_soc - 1e-10 rows.append( dict( array_area_m2=float(area), capacity_wh=float(capacity), unserved_energy_wh=unserved, final_soc=terminal, minimum_soc=float(dispatch.soc_end.min()), terminal_soc_satisfied=sustainable, feasible=unserved <= 1e-6 and (sustainable or not require_terminal_soc), scenario_mass_kg=float( area * array_mass_kg_m2 + capacity / battery_specific_energy_wh_kg ), ) ) return pd.DataFrame(rows).sort_values("scenario_mass_kg").reset_index(drop=True)