Source code for nsb2.emitter.moon

import logging

import astropy.units as u
import numpy as np
from astropy.coordinates import get_body, get_body_barycentric
from scipy.interpolate import UnivariateSpline

from nsb2.core.photometry import SolarSpectrumRieke2008
from nsb2.core.sources import EphemerisSource
from nsb2.core.spectral import SpectralGrid

from .. import ASSETS_PATH

__all__ = [
    "from_noll2013",
    "load_rolo_table",
    "lunar_distance_scaling",
    "lunar_phase_angle",
    "rolo_albedo",
    "rolo_log_albedo",
    "tabulate_lunar_spectra",
]


logger = logging.getLogger(__name__)

LUNAR_SOLID_ANGLE = 6.4236e-5

LUNAR_REFERENCE_DISTANCE = 384400

ROLO_ALBEDO_SCALE = 0.87

# Bound on the Moon's libration in longitude, in degrees. This is also the
# range the ROLO libration coefficients were fitted over, so it doubles as the
# validity limit of that term -- see rolo_log_albedo.
LIBRATION_SPREAD = 8

# The phase axis is sampled per branch -- waning and waxing -- so the total is
# odd and one sample lands exactly on full Moon.
N_PHASE_SAMPLES_PER_BRANCH = 50
N_PHASE_SAMPLES = 2 * N_PHASE_SAMPLES_PER_BRANCH - 1

ECLIPTIC_OBLIQUITY = np.deg2rad(23.439281)
ECLIPTIC_POLE_ICRS = np.array(
    [0.0, -np.sin(ECLIPTIC_OBLIQUITY), np.cos(ECLIPTIC_OBLIQUITY)]
)

ROLO_PHASE_PARAMETERS = (
    4.06054,
    12.8802,
    np.deg2rad(-30.5858),
    np.deg2rad(16.7498),
)


[docs] def load_rolo_table() -> np.ndarray: """Load the bundled ROLO albedo coefficient table. Returns ------- numpy.ndarray Shape ``(25, 11)``. Column 0 holds the band wavelength in nanometres; columns 1 to 10 hold that band's ROLO coefficients. """ return np.genfromtxt(ASSETS_PATH / "noll2013_lunar_rolo.dat", delimiter=",")
[docs] def rolo_log_albedo(coefficients, phase_angle, libration_lon): """Evaluate the ROLO log-albedo of one wavelength band. The empirical fit of [Kieffer2005]_ is a sum of three terms: a cubic polynomial in phase angle, an odd polynomial in the observer's selenographic longitude that carries the libration dependence, and two exponentials plus a cosine that capture the opposition surge near full Moon. The phase and libration arguments are independent geometry. All of the phase dependence sits in the first and third terms; the libration term contributes well under a per cent across its physical range and must not be driven by the phase angle. Parameters ---------- coefficients : array_like The ten ROLO coefficients of the band. phase_angle : array_like Absolute lunar phase angle in radians. libration_lon : array_like Selenographic longitude of the observer in radians, i.e. the Moon's libration in longitude. Physically bounded by :data:`LIBRATION_SPREAD`, which is also the range the fit was derived over. The fifth-power term turns over near 90 degrees and diverges beyond it, so extrapolating this argument is not meaningful. Returns ------- numpy.ndarray Natural logarithm of the disc-equivalent albedo. Notes ----- The full model of [Kieffer2005]_ carries two further terms in the selenographic latitude and longitude of the Sun. Those are omitted here, so the fit is even in phase angle and cannot reproduce the difference between a waxing and a waning Moon. """ p = np.asarray(coefficients) g = phase_angle phi = libration_lon p_1, p_2, p_3, p_4 = ROLO_PHASE_PARAMETERS sum_a = p[0] + p[1] * g + p[2] * g**2 + p[3] * g**3 sum_b = p[4] * phi + p[5] * phi**3 + p[6] * phi**5 sum_c = ( p[7] * np.exp(-g / p_1) + p[8] * np.exp(-g / p_2) + p[9] * np.cos((g - p_3) / p_4) ) return sum_a + sum_b + sum_c
[docs] def rolo_albedo(rolo_table, wvl: u.Quantity, phase_angle, libration_lon): """Interpolate the ROLO albedo onto a wavelength grid. The model is tabulated in 25 discrete bands, so each band is evaluated at the requested geometry and the result linearly interpolated in wavelength. The 13 per cent reduction of [Noll2012]_ is applied. Parameters ---------- rolo_table : numpy.ndarray Coefficient table from :func:`load_rolo_table`. wvl : astropy.units.Quantity Wavelengths to evaluate at. phase_angle : float Absolute lunar phase angle in radians. libration_lon : float Libration in longitude in radians; see :func:`rolo_log_albedo` for its valid range. Returns ------- numpy.ndarray Dimensionless disc-equivalent albedo at each wavelength. """ bands = [ np.exp(rolo_log_albedo(row[1:], phase_angle, libration_lon)) * ROLO_ALBEDO_SCALE for row in rolo_table ] spline = UnivariateSpline(rolo_table[:, 0], np.asarray(bands), k=1, s=0) return spline(wvl.to_value(u.nm))
[docs] def lunar_distance_scaling(obstime) -> u.Quantity: """ Scale the lunar brightness for the Sun-Moon and Moon-Earth distances. Parameters ---------- obstime : astropy.time.Time Time of observation. Returns ------- astropy.units.Quantity Dimensionless brightness weight, shape ``(1,)`` for a scalar time. """ moon = get_body("moon", obstime) sun = get_body("sun", obstime) sun_factor = (1.0 * u.AU / sun.distance.to(u.AU)) ** 2 obs_factor = (LUNAR_REFERENCE_DISTANCE * u.km / moon.distance.to(u.km)) ** 2 return ( np.atleast_1d(1 / np.pi * LUNAR_SOLID_ANGLE * obs_factor * sun_factor) * u.dimensionless_unscaled )
[docs] def lunar_phase_angle(obstime) -> np.ndarray: """ Compute the signed lunar phase angle seen from Earth. Parameters ---------- obstime : astropy.time.Time Time of observation. Returns ------- numpy.ndarray Phase angle in radians, in ``[-pi, pi]``, shape ``(N,)`` for ``N`` times and ``(1,)`` for a scalar one. Positive while the Moon is waxing, negative when waning. """ # Reshaping to (3, N) lets scalar and array times share one code path. pos = { b: get_body_barycentric(b, obstime).xyz.value.reshape(3, -1) for b in ("sun", "moon", "earth") } v_sun = pos["sun"] - pos["moon"] v_earth = pos["earth"] - pos["moon"] cos_g = np.einsum("ij,ij->j", v_sun, v_earth) / ( np.linalg.norm(v_sun, axis=0) * np.linalg.norm(v_earth, axis=0) ) g = np.arccos(np.clip(cos_g, -1, 1)) # The Moon leads the Sun in ecliptic longitude by 0 to 180 deg while waxing. r_moon = pos["moon"] - pos["earth"] r_sun = pos["sun"] - pos["earth"] handedness = np.einsum( "ij,i->j", np.cross(r_sun, r_moon, axis=0), ECLIPTIC_POLE_ICRS ) # Never zero: an exactly coplanar Moon is counted as waxing rather than # having its phase angle collapse to zero. return np.where(handedness < 0, -1.0, 1.0) * g
[docs] def tabulate_lunar_spectra( rolo_table, wvl: u.Quantity, solar_spectrum: u.Quantity ) -> tuple[np.ndarray, u.Quantity]: """Tabulate reflected solar spectra over phase angle and libration. Parameters ---------- rolo_table : numpy.ndarray Coefficient table from :func:`load_rolo_table`. wvl : astropy.units.Quantity Wavelength grid, shape ``(W,)``. solar_spectrum : astropy.units.Quantity Solar spectral flux density on that grid, shape ``(W,)``. Returns ------- phase_angles : numpy.ndarray The tabulated signed phase angles in radians, shape ``(N_PHASE_SAMPLES,)``, spanning ``[-pi, pi]``. spectra : astropy.units.Quantity Reflected photon spectra, shape ``(N_PHASE_SAMPLES, W, 3)``. The trailing axis holds the three libration variants, ordered so that they bracket the albedo uncertainty. Notes ----- The libration variants are offsets in the observer's selenographic longitude alone. They are deliberately independent of the phase angle: the two are separate arguments to the ROLO fit, and coupling them drives the libration polynomial far outside the range it was derived over, where its fifth-power term diverges. Because the fit omits the Sun's selenographic coordinates it is even in phase angle, so the tabulated axis is symmetric about full Moon. It is still tabulated signed, over ``[-pi, pi]``, to match the convention of :func:`lunar_phase_angle` and to leave room for a waxing/waning asymmetry once those terms are added. """ logger.debug("tabulating lunar albedo over %d phase angles", N_PHASE_SAMPLES) phase_angles = np.deg2rad(np.linspace(-180, 180, N_PHASE_SAMPLES)) # Ascending, so the trailing axis comes out as the minimum, median and # maximum a Prediction expects: the fit rises with libration longitude. libration = np.deg2rad([-LIBRATION_SPREAD, 0, LIBRATION_SPREAD]) spec = np.zeros((len(phase_angles), len(wvl), len(libration))) for i, g in enumerate(phase_angles): for j, offset in enumerate(libration): albedo = rolo_albedo(rolo_table, wvl, abs(g), offset) spec[i, :, j] = albedo * solar_spectrum spec = spec * solar_spectrum.unit photon_spec = ( spec.to( u.photon / (u.nm * u.s * u.cm**2), equivalencies=u.spectral_density(wvl[np.newaxis, :, np.newaxis]), ) / u.photon ) return phase_angles, photon_spec
[docs] def from_noll2013() -> EphemerisSource: """Build the lunar source of [Noll2012]_ from the ROLO albedo model. The Moon shines by reflected sunlight, so its spectrum is the solar spectrum of [Rieke2008]_ multiplied by the lunar albedo. The albedo is taken from the ROLO photometric model of [Kieffer2005]_, which parametrises it as a function of wavelength, phase angle and libration, with the 13 per cent reduction recommended by [Noll2012]_. Because libration is not modelled explicitly, three albedo variants spanning +/- :data:`LIBRATION_SPREAD` degrees of selenographic longitude are tabulated side by side. They propagate through the simulation as the minimum, median and maximum of a :class:`~nsb2.core.dtypes.Prediction`, bracketing this uncertainty. Returns ------- nsb2.core.sources.EphemerisSource The Moon, with brightness and phase angle evaluated from the ephemeris at prediction time. Notes ----- The selenographic terms of [Kieffer2005]_ for the Sun are not implemented, so the albedo is symmetric about full Moon: a waxing and a waning Moon at the same phase angle are predicted to be equally bright. Requires network access on first use to fetch the solar reference spectrum; see :func:`nsb2.core.photometry.SolarSpectrumRieke2008`. """ rolo = load_rolo_table() wvl, spectrum = SolarSpectrumRieke2008() mask = (wvl >= rolo[0, 0] * u.nm) & (wvl <= rolo[-1, 0] * u.nm) wvl = wvl[mask] spectrum = spectrum[mask] phase_angles, photon_spec = tabulate_lunar_spectra(rolo, wvl, spectrum) return EphemerisSource( "moon", lunar_distance_scaling, lunar_phase_angle, SpectralGrid([phase_angles], wvl, photon_spec), )