Skip to content

PLANETARY_NODES_BACKEND_STANDARD

Jump to bottom
TheDaniel166 edited this page Oct 15, 2026 · 5 revisions

Planetary And Small-Body Nodes Backend Standard

Version: 0.2 Date: 2026-09-16 Status: admitted backend standard through Orbital Core Stage 3

Scope

This standard governs Moira's orbital node and apsides surface:

  • moira.planetary_nodes

It covers:

  • kernel-free mean planetary orbital nodes and apsides
  • reader-backed osculating heliocentric nodes and apsides
  • the OrbitalNode result vessel

It does not govern lunar true/mean node computation, chart node placement, nodal aspects, nodal interpretation, or chart-backed node profiles.

Authority Layers

Moira exposes two distinct node products.

Mean planetary nodes:

  • use the Meeus / Simon et al. mean orbital element table in moira.planetary_nodes
  • are kernel-free
  • are documented by the engine as approximately valid from 2000 BCE to 3000 CE
  • return slow mean orbital elements for Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune

Geometric osculating nodes:

  • are an exact adapter over osculating_elements with center=SUN and frame=TRUE_ECLIPTIC_OF_DATE
  • derive the instantaneous heliocentric orbital plane from receipted reader state vectors using the strict orbital core's angular-momentum and eccentricity-vector geometry
  • bind public UT1 to TT and exact TDB state evaluation once
  • use the pinned JPL Horizons gravity policy and the core's singularity rules
  • require a receiptable reader route covering the requested body and exact TDB epoch
  • generalize to classical planets, Pluto, and loaded sovereign asteroid and comet catalogs
  • are admitted only for JD(TT) 2415020.0 through 2488070.0; requests outside that true-date frame interval fail explicitly
  • reject Sun and Moon as heliocentric node targets for this frame

OrbitalNode.perihelion is the ecliptic longitude of the projected pericenter vector. It is not the inclined-orbit dogleg Omega + omega.

Governing Objects

The admitted backend object is:

  • OrbitalNode

Required fields:

  • planet
  • ascending_node
  • descending_node
  • perihelion
  • aphelion
  • inclination
  • eccentricity
  • semi_major_axis

The admitted computations are:

  • planetary_node(planet, jd)
  • all_planetary_nodes(jd)
  • geometric_node(body, jd_ut, reader=None)

Required Transport Invariants

REST transport must preserve:

  • requested body identity
  • returned body identity
  • computation method: mean_elements or geometric_osculating
  • JD and JD scale semantics
  • coordinate frame
  • coordinate basis
  • kernel requirement truth
  • kernel source truth
  • ascending and descending node longitudes
  • perihelion and aphelion longitudes
  • inclination, eccentricity, and semi-major axis
  • method-specific validity note
  • canonical body name, NAIF ID, and body kind for geometric results
  • UT1, TT, and TDB epoch values and source-owned time-conversion receipt
  • selected Horizons gravity rule and GM receipt
  • true-date frame construction and admitted interval
  • path-free SPK route identities, release identities, hashes, and exact coverage intervals
  • singularity and undefined-element policies
  • stage sequence

REST transport must not:

  • collapse mean and osculating nodes into one generic result
  • imply small-body availability from catalog identity alone
  • expose chart-backed lunar-node doctrine through this family
  • treat Sun or Moon as valid heliocentric-node targets for geometric nodes
  • claim kernel-backed truth for mean-element results
  • claim mean-element validity beyond the engine's documented envelope
  • imply that an installed catalog has frozen-Horizons numerical admission unless an exact release hash is bound by the governed catalog admission

Validation Requirements

Transport admission must verify:

  • catalog route declares distinct mean and geometric methods
  • mean single route returns node and provenance
  • mean bulk route returns the admitted mean planetary set
  • mean routes reject non-finite JDs
  • mean routes reject empty and unknown planet names
  • mean bulk routes reject empty and oversized lists
  • geometric route passes the server engine reader into the computation
  • geometric route records strict-core time, gravity, frame, state-source, singularity, and undefined-element provenance without exposing local paths
  • geometric route rejects non-finite jd_ut
  • geometric route rejects Boolean epochs before transport coercion
  • geometric route rejects empty body names
  • geometric route rejects Sun and Moon as non-meaningful heliocentric-node targets
  • all nine admitted planet targets map exactly to one Sun/true-date core result
  • loaded representative asteroid/comet targets map exactly to the same core
  • requests outside the admitted true-date interval retain the typed frame error
  • every installed full-catalog member receives an inventory-wide finite-node and source-receipt check; a missing sovereign release is recorded as NOT RUN
  • frozen Horizons catalog comparisons run only for releases whose manifests carry the reviewed fixture hash and acceptance-gate admission

Non-Goals

This standard does not admit:

  • lunar true-node or mean-node REST routes
  • chart-backed node profiles
  • natal, transit, or synastry nodal interpretation
  • nodal aspect networks
  • a catalog-wide node REST endpoint
  • rendered node maps
  • asteroid/comet position route changes
  • small-body kernel manifest management

Clone this wiki locally