A compact, fitted mean-element approximation of a satellite's orbit.

Orbis.ReducedOrbit distills a position track — from a precise SP3 product or a list of ECEF samples — into a handful of mean elements that reproduce the motion cheaply, for caching, transport, and quick visibility math. It is not orbit determination and not a substitute for SGP4 or precise ephemeris: it deliberately discards short-period structure and is honest about the error it leaves behind (rms_m/max_m on the fit, and a source-backed drift/3).

Models

Two models are available, chosen with the :model option on fit/2:

• :circular_secular (the default) — a circular orbit; best for near-circular orbits (Galileo).
• :eccentric_secular — adds eccentricity through a nonsingular (h, k) parameterization, recovering the radial a·e signal (~hundreds of km for GPS/BeiDou) while degrading smoothly to the circular model as e -> 0.

circular_secular

A circular orbit (eccentricity fixed at zero) whose orbital plane precesses at a constant nodal rate. At an offset dt = t - t0 from the reference epoch the angles advance linearly,

u(t)    = arg_lat0 + n * dt          # argument of latitude
raan(t) = raan0    + raan_rate * dt
e       = 0

and the inertial (GCRS) position is the in-plane circle rotated by the node and inclination, r = Rz(raan) * Rx(i) * a * [cos u, sin u, 0].

The nodal rate raan_rate is fitted, but seeded from the J2 secular nodal regression (Vallado, Fundamentals of Astrodynamics and Applications):

raan_rate_j2 = -1.5 * n * J2 * (Re / a)^2 * cos(i)

Both the fitted value (raan_rate_rad_s) and the J2 seed (raan_rate_j2_rad_s) are kept; raan_rate_mode is "fitted_j2_seeded". The model does not claim to be a pure J2 propagation.

eccentric_secular

Eight free elements: the four circular plane elements plus h = e·sin ω, k = e·cos ω, L0 (mean argument of latitude at epoch), and n. Derived e = sqrt(h² + k²) and ω = atan2(h, k). At an offset dt the model advances λ = L0 + n·dt, forms the mean anomaly M = λ − ω, solves Kepler's equation E − e·sin E = M, and places the satellite at radius r = a(1 − e·cos E) and argument of latitude u = ω + ν. The (h, k) form is nonsingular: at e = 0 it reproduces circular_secular exactly with arg_lat0 = L0. The struct then carries h, k, e, and arg_perigee_rad (= ω).

Frames

Fitting and evaluation run internally in GCRS; positions are returned in ECEF (ITRF) meters by default, or GCRS via frame: :gcrs. ECEF velocity includes the Earth-rotation transport term. Sample/query epochs are interpreted consistently for the Earth-rotation conversion; the ECEF product (the primary output) is self-consistent across the fit, evaluation, and drift.

Expected accuracy

Representative drift (extrapolated model-vs-source position error): a fit to the first ~6 hours of an MGEX SP3 track, drifted over the rest of the day. Numbers are the max position error over the full day, measured against vendored MGEX products (GRG for GPS/Galileo, a trimmed GBM product for BeiDou):

Reading of the table:

• For eccentric orbits the circular model is unusable — the unmodelled radial a·e signal compounds badly under extrapolation. :eccentric_secular is the recommended model and brings the error down by one-to-three orders of magnitude. Note this holds even for the small eccentricities of BeiDou MEO/IGSO (e ~ 1e-3 to 5e-3): a few-hundred-metre to ~200 km radial signal still wrecks the circular extrapolation, so eccentric wins there too.
• For near-circular orbits (Galileo, e ~ 1e-4) both models are comparable: the eccentric model is essentially identical to the circular one (~8 km either way), so it does not regress and is a safe default when the orbit class is unknown.

These figures are measured through drift/3 (the public NIF-backed pipeline, GPST) against the vendored fixtures; the exact numbers shift slightly with the fit window and drift cadence.

These are characterisations, not guarantees: always measure a given fit with drift/3 against the source. LEO accuracy is characterised once the SGP4/TLE source lands. This is a compact approximation for caching / visibility, never a substitute for SP3 or SGP4.

Persistence

to_map/1 emits a stable, versioned map (frame, model, units, epoch scale, elements, fit stats) that from_map/1 reads back, for caching/transport.