Lunar surface models and data#

Lunar data, terrain/PV/thermal models, storage sizing and rover analyses.

class orbitalpv.lunar.DivinerConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

PDS4 Diviner south-pole seasonal PCP bolometric temperature tables.

This explicit product family bins 2009–2020 observations at 240 m in L_s=0–60 degrees and one of 24 subsolar-longitude bins, 15 degrees wide. It is a cumulative climatology, not a dated 2026 weather/temperature series. Empty bins are absent. Original TAB and XML labels are both retained.

Parameters:
SOURCE = 'NASA PDS LRO Diviner PCP'#
DOCUMENTATION = 'https://pds-geosciences.wustl.edu/missions/lro/diviner.htm'#
BASE = 'https://pds-geosciences.wustl.edu/lro/urn-nasa-pds-lro_diviner_derived1/data_derived_pcp/seasonal/slon/pols'#
seasonal_temperature(subsolar_bin, directory, *, refresh=False)[source]#

Download a 15-degree bin (1..24), about 200 MB, with its PDS4 label.

Parameters:
Return type:

tuple[DownloadReceipt, DownloadReceipt]

class orbitalpv.lunar.LolaConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

NASA PGDA LOLA DEMs; native metres, lunar south-polar stereographic.

The broad 80 m product is about 189 MB. Five-metre site products have interpolated pixels; nominal grid spacing is not measurement resolution. The same site API also retrieves published height-uncertainty rasters.

Parameters:
SOURCE = 'NASA PGDA LOLA'#
DOCUMENTATION = 'https://pgda.gsfc.nasa.gov/products/90'#
polar_dem(destination, *, refresh=False)[source]#

Download the 80–90 south, 80 m DEM in MOON_ME_DE421.

Parameters:
Return type:

DownloadReceipt

site_dem(site, destination, *, height_error=False, refresh=False)[source]#

Download published 5 m site terrain or total Z uncertainty (metres).

Supported sites are 01, 04 and 11 from PGDA product 78. The uncertainty product is not itself a terrain DEM and must not be used as elevation.

Parameters:
Return type:

DownloadReceipt

class orbitalpv.lunar.LunarIlluminationConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

NASA SVS 4930 metadata and illustration assets, not scientific flux grids.

The two-hour rendered frames are useful qualitative references. Image brightness is NOT irradiance, illumination fraction or measured PV power.

Parameters:
SOURCE = 'NASA SVS lunar illumination 4930'#
DOCUMENTATION = 'https://svs.gsfc.nasa.gov/4930/'#
metadata(*, cache_path=None, refresh=False)[source]#

Retrieve the public metadata API linked by the SVS page.

Parameters:
Return type:

ResearchResponse

reference_image(year, destination, *, refresh=False)[source]#

Download the published overview image for 2023..2030, without a timestamp claim.

Parameters:
Return type:

DownloadReceipt

frame(year, filename, destination, *, refresh=False)[source]#

Download an explicitly selected frame filename from the SVS frame listing.

Frame numbering is provider-defined; read the timestamp rendered in the image rather than inferring it from the index.

Parameters:
Return type:

DownloadReceipt

class orbitalpv.lunar.LunarRover(mass_kg=100.0, rolling_resistance=0.05, drive_efficiency=0.6, speed_m_s=0.1, housekeeping_w=20.0, capacity_wh=500.0, initial_energy_wh=400.0, reserve_wh=100.0, charge_efficiency=0.95, discharge_efficiency=0.95, maximum_charge_w=100.0, maximum_discharge_w=150.0, maximum_slope_deg=20.0)[source]#

Illustrative mobility/electrical inputs; no flight calibration implied.

Parameters:
mass_kg: float = 100.0#
rolling_resistance: float = 0.05#
drive_efficiency: float = 0.6#
speed_m_s: float = 0.1#
housekeeping_w: float = 20.0#
capacity_wh: float = 500.0#
initial_energy_wh: float = 400.0#
reserve_wh: float = 100.0#
charge_efficiency: float = 0.95#
discharge_efficiency: float = 0.95#
maximum_charge_w: float = 100.0#
maximum_discharge_w: float = 150.0#
maximum_slope_deg: float = 20.0#
class orbitalpv.lunar.LunarSpiceConnector(*, timeout_s=30.0, user_agent='space-pv-analytics/0.2')[source]#

Pinned DE421 kernel set matching LOLA’s MOON_ME_DE421 frame.

Downloading does not load or clear SPICE’s global pool. The leap-second kernel is a fixed version; UTC dates beyond its last leap require checking for subsequent leap seconds before operational use. Coverage is bounded by the kernels (lunar orientation 1900–2050), with errors propagated by SPICE.

Parameters:
SOURCE = 'NASA NAIF lunar DE421 kernels'#
DOCUMENTATION = 'https://naif.jpl.nasa.gov/pub/naif/generic_kernels/fk/satellites/moon_080317.tf'#
KERNELS: ClassVar[dict[str, str]] = {'de421.bsp': 'spk/planets/a_old_versions/de421.bsp', 'moon_080317.tf': 'fk/satellites/moon_080317.tf', 'moon_pa_de421_1900-2050.bpc': 'pck/moon_pa_de421_1900-2050.bpc', 'naif0012.tls': 'lsk/naif0012.tls'}#
download(directory, *, refresh=False)[source]#

Retrieve all four named kernels; checked caches support offline reuse.

Parameters:
Return type:

list[DownloadReceipt]

class orbitalpv.lunar.LunarTerrain(x_m, y_m, elevation_m)[source]#

Regular south-polar stereographic grid, axes increasing, elevation[y,x].

Missing elevations are allowed as NaN and are never replaced by zero. The horizon routine rejects missing cells. Use a valid bounded window explicitly rather than silently bridging data gaps. Units and projection are fixed.

Parameters:
x_m: ndarray#
y_m: ndarray#
elevation_m: ndarray#
height(x_m, y_m)[source]#

Bilinear elevation; reject out-of-bounds points or missing neighbours.

Parameters:
Return type:

float

orbitalpv.lunar.energy_aware_route(elevation_m, time_s, solar_power_w, *, cell_size_m, start, goal, rover, heater_power_w=0.0)[source]#

Find earliest feasible arrival; maximize remaining energy at equal arrival.

Elevations are a local metric grid (row,column). NaNs mark impassable cells. Solar/heater cubes are (interval,row,column); scalar values broadcast. Moves use four neighbours or wait one entire time interval. A move requires speed*dt >= 3D edge length. Energy includes rolling resistance, uphill potential (g=1.62 m/s²), housekeeping and heaters, with no downhill recovery.

Edge solar/heater power is the average of its endpoints for the full step; this explicitly approximates conditions during travel and any waiting. Each edge uses constant net power, so endpoint reserve checks also bound energy inside that interval. Charge/discharge limits and losses apply at the bus. Dominance pruning retains the greatest energy at each cell/time; no global continuous-space or continuous-time optimum is claimed. No wheel slip, boulders, radio visibility or terrain below grid resolution is modelled.

Parameters:
Return type:

DataFrame

orbitalpv.lunar.longest_darkness_hours(time_s, visible_fraction, *, threshold=0.01)[source]#

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.

Parameters:
  • time_s (ArrayLike)

  • visible_fraction (ArrayLike)

  • threshold (float)

Return type:

float

orbitalpv.lunar.lunar_ephemeris(utc_timestamps)[source]#

Sun/Earth vectors using explicitly preloaded DE421 SPICE kernels.

Reuses OrbitalPV’s SPICE engine and does not change the global kernel pool. UTC input must include Z. Output elapsed seconds are ET (SI seconds). Vectors are simultaneous geometric positions, not light-time corrected; the approximation is recorded for reproducible terrain screening studies.

Parameters:

utc_timestamps (list[str])

Return type:

DataFrame

orbitalpv.lunar.lunar_panel_thermal(time_s, poa_direct_w_m2, *, ground_temperature_k, ground_view_factor, ground_emissivity=0.95, surface=None, **thermal_options)[source]#

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.

Parameters:
  • time_s (ArrayLike)

  • poa_direct_w_m2 (ArrayLike)

  • ground_temperature_k (ArrayLike)

  • ground_view_factor (float)

  • ground_emissivity (float)

  • surface (ThermalSurface | None)

Return type:

DataFrame

orbitalpv.lunar.lunar_pv_power(geometry, horizon, *, reference, cell_temperature_c, mode='fixed', tilt_deg=90.0, panel_azimuth_deg=0.0, optical_retention=1.0)[source]#

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.

Parameters:
Return type:

DataFrame

orbitalpv.lunar.lunar_solar_geometry(sun_position_m, earth_position_m, *, longitude_deg, latitude_deg, elevation_m)[source]#

Topocentric Sun angles and direct-normal flux, including Earth eclipses.

Input vectors originate at the Moon centre in MOON_ME_DE421. Spherical, opaque Earth occultation reuses the orbit model; terrestrial atmospheric transmission during lunar eclipses is omitted. Terrain shading is separate.

Parameters:
  • sun_position_m (ArrayLike)

  • earth_position_m (ArrayLike)

  • longitude_deg (float)

  • latitude_deg (float)

  • elevation_m (float)

Return type:

DataFrame

orbitalpv.lunar.lunar_surface_position(longitude_deg, latitude_deg, elevation_m=0.0)[source]#

Cartesian body-fixed positions, last dimension XYZ, in metres.

Parameters:
  • longitude_deg (ArrayLike)

  • latitude_deg (ArrayLike)

  • elevation_m (ArrayLike)

Return type:

ndarray

orbitalpv.lunar.parse_diviner_pcp(content, label, *, allow_subset=False)[source]#

Parse the labelled six-column PCP family; preserve missing values as NaN.

Labels incorrectly assign degrees to normalized x/y; the field descriptions specify normalization by lunar radius. Output x_m/y_m follows that description and is checked against the published longitude/latitude. The original normalized coordinates are retained. allow_subset is only for byte-preserving subsets with separately recorded extraction provenance.

Parameters:
Return type:

DataFrame

orbitalpv.lunar.read_lola_geotiff(path, *, bounds_m=None, stride=1)[source]#

Read an explicit window, retaining pixel centres and missing cells.

bounds_m is (left,bottom,right,top), in projected lunar metres. Optional integer stride samples native pixels without smoothing; it can miss peaks. Requires the ground extra (rasterio). Verify the product is elevation, not a height-error, count or hillshade map, before calling this function.

Parameters:
Return type:

LunarTerrain

orbitalpv.lunar.size_lunar_storage(time_s, generation_per_m2_w, demand_w, *, array_areas_m2, capacities_wh, battery_template, array_mass_kg_m2=3.0, battery_specific_energy_wh_kg=150.0, require_terminal_soc=True)[source]#

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.

Parameters:
  • 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)

  • battery_specific_energy_wh_kg (float)

  • require_terminal_soc (bool)

Return type:

DataFrame

orbitalpv.lunar.solar_disc_visibility(elevation_deg, horizon_deg, angular_radius_deg=0.2666)[source]#

Visible area of a uniform solar disc above a locally straight horizon.

Neglect limb darkening and horizon variation across the disc. No atmospheric refraction is applied. This is a geometric area fraction, not a measurement.

Parameters:
  • elevation_deg (ArrayLike)

  • horizon_deg (ArrayLike)

  • angular_radius_deg (ArrayLike)

Return type:

ndarray

orbitalpv.lunar.south_polar_lonlat(x_m, y_m)[source]#

Invert spherical stereographic coordinates (lat_0=-90, lon_0=0, k=1).

Return longitude [0, 360) and latitude in degrees. At the projection pole, longitude is set to zero. +Y points towards longitude zero, +X to 90 east.

Parameters:
  • x_m (ArrayLike)

  • y_m (ArrayLike)

Return type:

tuple[ndarray, ndarray]

orbitalpv.lunar.survival_heater_power(sink_temperature_k, *, setpoint_k, thermal_conductance_w_k, internal_heat_w=0.0)[source]#

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.

Parameters:
  • sink_temperature_k (ArrayLike)

  • setpoint_k (float)

  • thermal_conductance_w_k (float)

  • internal_heat_w (ArrayLike)

Return type:

ndarray

orbitalpv.lunar.terrain_horizon(terrain, *, site_x_m, site_y_m, tower_height_m, azimuth_bins=360, site_elevation_m=None, minimum_distance_m=0.0)[source]#

Maximum sampled terrain elevation angle per azimuth sector, with curvature.

Ray directions are evaluated in the site’s true east/north/up basis, not projection-grid north. Every DEM pixel centre contributes to one sector. This sector-envelope approximation can over-shade within a sector while missing subpixel obstacles; refine DEM and sectors before engineering use. site_elevation_m holds the observer at one common ground elevation when combining grids. minimum_distance_m excludes inner samples from coarser layers; the caller must cover the excluded region with a finer grid. The reported angular coverage is finite and not an assertion that distant terrain has been checked. Heights are measured above interpolated ground.

Parameters:
Return type:

DataFrame