constants.base

constants.base

Foundation classes for planetarypy.constants.

Three types live here:

:class:Constant — a thin astropy.units.Quantity subclass that carries provenance metadata (PCK source, IAU edition, body name, description, reference). Used for every value that comes directly out of a PCK kernel.
:class:Body — a frozen container of constants for one celestial body (Sun, planet, moon, asteroid, comet). Generated by the regenerator script, never hand-edited.
:class:BodyRegistry — a dict of bodies keyed by NAIF ID, with case-insensitive name lookup and class-based filtering helpers.

See docs/explanation/constants_design.qmd for the design rationale.

Classes

Name	Description
Body	All constants for one celestial body.
BodyRegistry	Dict of bodies keyed by NAIF ID, with name + class-based lookup.
Constant	A `Quantity` with attached provenance and (optional) error info.
Range	Inclusive bounds for a quantity that legitimately varies.
RangeWarning	Issued when a Constant with a populated `.range` returns the

Body

constants.base.Body(
    name,
    naif_id,
    body_class,
    parent=None,
    dwarf_planet=False,
    mission_visited=False,
    radii=None,
    GM=None,
    long_axis=None,
    pole_ra=None,
    pole_dec=None,
    pm=None,
    rotation_rate=None,
    pole_ra_coeffs=None,
    pole_dec_coeffs=None,
    pm_coeffs=None,
    mean_radius=None,
    volume_radius=None,
    flattening=None,
    equatorial_radius=None,
    polar_radius=None,
    volumetric_mean_radius=None,
    core_radius=None,
    ellipticity=None,
    mean_density=None,
    surface_gravity=None,
    surface_acceleration=None,
    surface_acceleration_eq=None,
    surface_acceleration_pole=None,
    escape_velocity=None,
    bond_albedo=None,
    geometric_albedo=None,
    v_band_magnitude=None,
    solar_irradiance=None,
    black_body_temperature=None,
    topographic_range=None,
    moment_of_inertia=None,
    J2=None,
    number_of_satellites=None,
    has_ring_system=None,
    semimajor_axis=None,
    sidereal_orbit_period=None,
    tropical_orbit_period=None,
    perihelion=None,
    aphelion=None,
    synodic_period=None,
    mean_orbital_velocity=None,
    max_orbital_velocity=None,
    min_orbital_velocity=None,
    orbit_inclination=None,
    orbit_eccentricity=None,
    sidereal_rotation_period=None,
    length_of_day=None,
    obliquity_to_orbit=None,
    inclination_of_equator=None,
    surface_pressure=None,
    surface_density=None,
    scale_height=None,
    average_temperature=None,
    mean_molecular_weight=None,
    volume=None,
)

[source]

All constants for one celestial body.

Values that came directly from the PCK are :class:Constant instances (with provenance metadata); derived values (mass, density) are plain Quantity properties computed lazily from the PCK constants and astropy.constants.G.

Optional fields default to None — not every body in the PCK has every field (e.g. minor moons often have radii only).

Attributes

Name	Description
body_class	One of `"sun"`, `"planet"`, `"moon"`, `"asteroid"`, `"comet"`.
density	Mean density from `mass` over the triaxial ellipsoid volume.
dwarf_planet	`True` for IAU-classified dwarf planets (Pluto, Ceres, …).
mass	Body mass derived from `GM` and `astropy.constants.G`.
mission_visited	`True` for small bodies that have been flown by, orbited, or landed on.
naif_id	NAIF integer id (e.g. `499` for Mars).
name	Canonical PCK name (uppercase, e.g. `"MARS"`).
parent	NAIF id of parent planet for moons; `None` otherwise.

Methods

Name	Description
at_time	Return a snapshot Body with fields resolved as of `date`.
iter_constants	Yield `(field_name, Constant)` for every Constant-bearing field.

at_time

constants.base.Body.at_time(date)

Return a snapshot Body with fields resolved as of date.

Resolution rules:

PCK fields (radii, GM, pole_*, rotation_rate, …): pulled from whichever IAU PCK edition was current on date. IAU 2009 PCK published 2010-10-21; IAU 2015 PCK published 2018-09-20. Before 2010-10-21 no PCK existed → NSSDC fills in.
NSSDC-only fields (bond_albedo, surface_pressure, …): overlaid from NSSDC at the given date.

date accepts "2001" / "2001-06" / "2001-06-15" — year/year-month resolve to end-of-period.

Returns a fresh frozen Body; self is unmodified.

[source]

iter_constants

constants.base.Body.iter_constants()

Yield (field_name, Constant) for every Constant-bearing field.

Skips fields that are None (unset for this body) and fields whose value isn’t a :class:Constant — metadata like body_class / naif_id / dwarf_planet and structural tuples like pole_ra_coeffs or scalar floats like flattening are filtered out. The result is the set of per-body quantities with provenance.

Useful for tabular display, completions, and introspection without the caller needing to know the dataclass schema.

Example::

>>> from planetarypy.constants import Mars
>>> dict(Mars.iter_constants())["GM"]
<Constant Mars.GM = 42828.4 km3 / s2  (IAU 2015)>

[source]

BodyRegistry

constants.base.BodyRegistry(bodies=None)

[source]

Dict of bodies keyed by NAIF ID, with name + class-based lookup.

Indexable by either NAIF id (registry[499]) or name (registry["MARS"], registry["mars"] — case-insensitive).

Use :meth:by_class to filter by body_class and optional parent.

Methods

Name	Description
by_class	Filter by `body_class`, optionally also by `parent`.
find	Best-effort lookup by NAIF id or name; `None` on miss.

by_class

constants.base.BodyRegistry.by_class(body_class, parent=None)

Filter by body_class, optionally also by parent.

parent may be a NAIF id, a body name, or a :class:Body.

[source]

find

constants.base.BodyRegistry.find(query)

Best-effort lookup by NAIF id or name; None on miss.

[source]

Constant

constants.base.Constant()

[source]

A Quantity with attached provenance and (optional) error info.

Behaves like any other :class:astropy.units.Quantity for math and unit operations — composes in formulas, supports .to(), slices, etc. View operations (slicing, copying, ufuncs) propagate metadata; explicitly demote to plain Quantity if you want a metadata-free value.

Metadata fields (all defaulting to empty/zero/None): name, body, description, reference, iau_year, source, uncertainty, range.

The two error-info fields are orthogonal and semantically distinct (see :class:Range). uncertainty is a symmetric ± value in the same unit as value; range is a :class:Range of bounds for a naturally-varying quantity, with value set to the midpoint as the representative single number for arithmetic.

Range

constants.base.Range(min, max)

[source]

Inclusive bounds for a quantity that legitimately varies.

Distinct from measurement uncertainty: a range expresses that the quantity takes different values under different conditions (seasonal, diurnal, latitudinal, …), not that one measurement is bracketed by an error bar. Mars surface pressure varying between 4.0 mb and 8.7 mb across the year is a range; Mars surface density of 0.020 ± 0.006 kg/m³ is an uncertainty.

RangeWarning

constants.base.RangeWarning()

[source]

Issued when a Constant with a populated .range returns the range midpoint as its scalar value.

The midpoint is an interpretation of NSSDC’s published bounds, not raw data — surfaced because the user opted into the "midpoint" strategy via [constants] range_strategy in ~/.planetarypy_config.toml. Default strategy is "nan", which leaves the underlying value as NaN and never triggers this warning.

Suppress permanently via config ([constants] warn_on_range_midpoint = false) or per-script via the standard warnings module::

import warnings
from planetarypy.constants import RangeWarning
warnings.filterwarnings("ignore", category=RangeWarning)