ssapy_toolkit.compute.lambertian_magnitude

Brightness of a Lambertian sphere in (or above) Earth’s atmosphere.

Three public functions, all sharing the same geometry/spectral engine:

  • lambertian_reflection() – reflected light only

    (sunshine, earthshine, moonshine)

  • thermal_emission() – gray-body self-emission only

  • lambertian_sphere_brightness() – both combined

Each returns in-band irradiance [W m^-2] and apparent AB magnitudes in an arbitrary wavelength band (e.g. V, green, SWIR), including the Lambertian- sphere phase function for every source, Earth umbra/penumbra for direct sun, and Kasten & Young (1989) airmass extinction when the observer is inside the atmosphere.

Every physical model parameter (solar constant, Earth/Moon albedos and radii, OLR, effective temperatures, atmosphere top, AB zero point, …) is a keyword argument; the module-level values are only their defaults.

SSAPy consistency

Everything position-related comes from SSAPy (LLNL), evaluated at an astropy.time.Time (default provided):

  • Observer: ssapy.EarthObserver.getRV(time) -> GCRF meters

  • Sun: ssapy.utils.sunPos(time) -> GCRF meters

  • Moon: ssapy.utils.moonPos(time) -> GCRF meters

  • Zenith angle: astropy AltAz transform – the same backend that ssapy.compute.altaz itself uses internally (SSAPy’s altaz/quickAltAz APIs require an Orbit object rather than a bare position vector).

Geometry: all positions GCRS/GCRF, geocenter at the origin. All phase angles (Sun-object-observer, Sun-Earth-object, Earth-object-observer, Sun-Moon-object, Moon-object-observer) come from the full 3-D vectors.

Spectral model

Planck spectra throughout:

  • Object thermal: B_lambda(T_object) x emissivity (gray)

  • Solar-spectrum components (sun, moonshine, shortwave earthshine):

    t_sun (5772 K) blackbody scaled to the local total solar irradiance (good to ~5% across VIS-SWIR; solar/telluric absorption features are not modeled)

  • Earth longwave: t_earth_lw (255 K) blackbody scaled to the OLR

Magnitudes are on the AB system, from the band-averaged flux density: m_AB = -2.5 log10(<f_nu> / 3631 Jy). For the default V band this agrees with Johnson V to a few hundredths of a magnitude.

Author: generated with Claude.

Functions

airmass_kasten_young(zenith_deg)

Kasten & Young (1989) relative airmass; valid to the horizon.

lambert_sphere_phase(alpha)

Phase function of a Lambertian sphere, normalized so that the flux scattered toward the observer is

lambertian_reflection(obj_pos_gcrs_m[, ...])

Light reflected by a Lambertian sphere: direct sunshine, earthshine (shortwave + Earth-thermal longwave), and moonshine.

lambertian_sphere_brightness(obj_pos_gcrs_m)

Total brightness of a Lambertian, gray-body sphere near Earth in a chosen band: reflected light (via lambertian_reflection) plus thermal self-emission (via thermal_emission).

sun_visibility_factor(r_obj, r_sun[, ...])

Fraction of the solar disk visible from the object, occulted by Earth.

thermal_emission(obj_pos_gcrs_m[, observer, ...])

Gray-body thermal self-emission of the sphere.
ssapy_toolkit.compute.lambertian_magnitude.airmass_kasten_young(zenith_deg)[source]

Kasten & Young (1989) relative airmass; valid to the horizon.

ssapy_toolkit.compute.lambertian_magnitude.lambert_sphere_phase(alpha)[source]

Phase function of a Lambertian sphere, normalized so that the flux scattered toward the observer is

F = E_inc * A * (R/d)^2 * p(alpha), p(0) = 2/3,

with alpha the phase angle [rad] at the object between the illumination source and the observer.

ssapy_toolkit.compute.lambertian_magnitude.lambertian_reflection(obj_pos_gcrs_m, observer=None, radius_m=1.0, albedo=0.3, time=<Time object: scale='utc' format='isot' value=2026-06-09T00:00:00.000>, band='V', k_extinction=0.16, include_sun=True, include_earthshine=True, include_moonshine=True, lon=None, lat=None, elevation=0.0, solar_const=1361.0, t_sun=5772.0, r_sun_radius=695700000.0, r_earth=6378137.0, albedo_earth=0.306, olr_earth=239.0, t_earth_lw=255.0, r_moon=1737400.0, albedo_moon=0.12, atmosphere_top_m=100000.0, f_nu_ab_zero=3.631e-23, _geo=None)[source]

Light reflected by a Lambertian sphere: direct sunshine, earthshine (shortwave + Earth-thermal longwave), and moonshine. No self-emission.

Parameters mirror lambertian_sphere_brightness (see its docstring); every physical model parameter (solar constant, albedos, radii, OLR, effective temperatures, atmosphere top, AB zero point) is a kwarg.

Returns the standard output dict with components ‘sun’, ‘earthshine’, ‘moonshine’.

ssapy_toolkit.compute.lambertian_magnitude.lambertian_sphere_brightness(obj_pos_gcrs_m, observer=None, temperature_K=300.0, radius_m=1.0, albedo=0.3, emissivity=None, time=<Time object: scale='utc' format='isot' value=2026-06-09T00:00:00.000>, band='V', k_extinction=0.16, include_sun=True, include_earthshine=True, include_moonshine=True, include_thermal=True, lon=None, lat=None, elevation=0.0, solar_const=1361.0, t_sun=5772.0, r_sun_radius=695700000.0, r_earth=6378137.0, albedo_earth=0.306, olr_earth=239.0, t_earth_lw=255.0, r_moon=1737400.0, albedo_moon=0.12, atmosphere_top_m=100000.0, f_nu_ab_zero=3.631e-23)[source]

Total brightness of a Lambertian, gray-body sphere near Earth in a chosen band: reflected light (via lambertian_reflection) plus thermal self-emission (via thermal_emission).

Parameters:

  • obj_pos_gcrs_m (array-like (3,)) – Object position in GCRS/GCRF, meters from the geocenter.

  • observer (ssapy.EarthObserver, EarthLocation, or array-like (3,), optional) – Observer as an ssapy.EarthObserver (GCRF position from EarthObserver.getRV(time)), an astropy EarthLocation, or a raw GCRS position vector in meters (e.g. another spacecraft; extinction applies only below atmosphere_top_m). May be omitted if lon and lat are given.

  • lon (float, optional) – Geodetic site (degrees East-positive, degrees, meters); builds an ssapy.EarthObserver internally when observer is None.

  • lat (float, optional) – Geodetic site (degrees East-positive, degrees, meters); builds an ssapy.EarthObserver internally when observer is None.

  • elevation (float, optional) – Geodetic site (degrees East-positive, degrees, meters); builds an ssapy.EarthObserver internally when observer is None.

  • temperature_K (float) – Sphere temperature [K], radius [m], gray Bond/Lambert albedo (0-1).

  • radius_m (float) – Sphere temperature [K], radius [m], gray Bond/Lambert albedo (0-1).

  • albedo (float) – Sphere temperature [K], radius [m], gray Bond/Lambert albedo (0-1).

  • emissivity (float, optional) – Gray emissivity; defaults to 1 - albedo (Kirchhoff).

  • time (astropy.time.Time) – Epoch for the SSAPy ephemerides (default 2026-06-09 00:00 UTC).

  • band (str or (float, float)) – Named key from BANDS (e.g. ‘V’, ‘green’, ‘SWIR’, ‘J’, ‘LWIR’) or explicit (lam_lo, lam_hi) in meters (Quantities accepted).

  • k_extinction (float) – Extinction coefficient [mag/airmass] for the chosen band.

  • include_* (bool) – Toggle individual components.

  • solar_const

  • t_sun

  • r_sun_radius

  • r_earth

  • albedo_earth

  • olr_earth

:param : :param t_earth_lw: Physical model parameters; defaults are the module-level constants. :type t_earth_lw: float :param r_moon: Physical model parameters; defaults are the module-level constants. :type r_moon: float :param albedo_moon: Physical model parameters; defaults are the module-level constants. :type albedo_moon: float :param atmosphere_top_m: Physical model parameters; defaults are the module-level constants. :type atmosphere_top_m: float :param f_nu_ab_zero: Physical model parameters; defaults are the module-level constants. :type f_nu_ab_zero: float

Returns:

dict – ‘earthshine’, ‘moonshine’, ‘thermal’) and totals [W m^-2], AB magnitudes per component and total (exoatmospheric and observed), airmass, extinction, range, band, and all phase angles [deg].

Return type:

in-band and bolometric irradiances per component (‘sun’,

ssapy_toolkit.compute.lambertian_magnitude.sun_visibility_factor(r_obj, r_sun, r_earth=6378137.0, r_sun_radius=695700000.0)[source]

Fraction of the solar disk visible from the object, occulted by Earth. 1 = full sun, 0 = umbra, linear interpolation across the penumbra (adequate to a few percent of the penumbral contribution).

ssapy_toolkit.compute.lambertian_magnitude.thermal_emission(obj_pos_gcrs_m, observer=None, temperature_K=300.0, radius_m=1.0, albedo=0.3, emissivity=None, time=<Time object: scale='utc' format='isot' value=2026-06-09T00:00:00.000>, band='V', k_extinction=0.16, lon=None, lat=None, elevation=0.0, r_earth=6378137.0, atmosphere_top_m=100000.0, f_nu_ab_zero=3.631e-23, _geo=None)[source]

Gray-body thermal self-emission of the sphere. No reflected light.

emissivityfloat, optional

Gray emissivity. Defaults to Kirchhoff’s law, 1 - albedo.

Other parameters mirror lambertian_sphere_brightness. Returns the standard output dict with component ‘thermal’.