Architecture & Physics

ASTRA-Core uses SGP4 for large catalogs and Cowell for high-fidelity segments. For model assumptions (ephemeris span, Pc inputs, strict mode), see Operational limitations.

The stack is organized around numerical rigor and clear separation of parsing, propagation, and screening.

Two Propagation Tiers

  1. Analytical SGP4 (Vectorized)

    The standard for processing massive space catalogs (e.g., all active satellites). SGP4 is incredibly fast but limited by the accuracy of the underlying Two-Line Element (TLE) mean-element models. ASTRA-Core vectorizes SGP4 natively via NumPy, propagating thousands of trajectories concurrently with a single propagate_many call.

  2. Numerical Cowell Integrator (7-DOF)

    For high-fidelity operations, ASTRA implements a Dormand-Prince DOP853 (8th-order, scipy.integrate.solve_ivp) direct integration scheme. A segmented orchestrator slices the propagation at engine ignition / cutoff boundaries so the integrator never steps across a force-model discontinuity:

    • Coast arc (6-DOF): state vector [x, y, z, vx, vy, vz].

    • Powered arc (7-DOF): state vector [x, y, z, vx, vy, vz, mass], with continuous mass depletion via the Tsiolkovsky equation \(\dot{m} = -F / (I_{sp} \cdot g_0)\).

    Physical forces modelled:

    • Gravity: WGS-84 zonal harmonics through \(J_6\).

    • Atmospheric Drag: NRLMSISE-00 atmospheric density model driven by live Space Weather indicators (F10.7, Ap). Calibration anchor: ρ(400 km, F10.7 = 150, Ap = 15) ≈ 3.7 × 10−12 kg/m³.

    • Third-Body Dynamics: Lunar & Solar gravitational perturbations from JPL DE421 (1900–2050, ~17 MB).

    • Solar Radiation Pressure (SRP): Cannonball model with a high-fidelity conical Earth umbra/penumbra geometry. The illumination factor ν is computed as the fractional area of the solar disk not occulted by Earth, transitioning smoothly from ν = 1 (full sun) through the penumbra to ν = 0 (full umbra). Use DragConfig(srp_conical_shadow=True) (the default); the old alias srp_cylindrical_shadow is deprecated.

Numba JIT Acceleration

The innermost loop of the Cowell integrator—where forces are summed at every substep—is JIT-compiled to LLVM machine code using @njit(fastmath=True, cache=True).

To prevent I/O bottlenecks inside the tight integration loop, JPL DE421 planetary positions are pre-fitted into piecewise 7-day, 20-node Chebyshev polynomial splines via Clenshaw recurrence (_eval_cheb_3d_njit). The splines are evaluated entirely in memory with no file I/O during integration.

A pure-Python fallback (_acceleration) is available when Numba is not installed; it produces numerically identical results but is significantly slower.

6×6 State Transition Matrix (STM) Covariance

propagate_covariance_stm(cov0, Phi) propagates an initial covariance matrix forward in time using the 6×6 state transition matrix:

\[P(t) = \Phi(t, t_0) \, P_0 \, \Phi(t, t_0)^T\]

The Jacobian _compute_force_jacobian includes exact analytical J2 partial derivatives (Montenbruck & Gill §3.2.4) alongside the two-body term, so the dominant nodal-precession uncertainty growth in LEO is captured correctly. A co-rotating drag Jacobian correction preserves covariance positive-definiteness.

JIT Warm-Up

astra.warmup() pre-compiles all Numba kernels (Cowell force model, SpatialIndex screening) by running a trivial 1-second propagation and a do-nothing conjunction check. Call it once at worker startup in production to eliminate first-call latency.

Data Source Priority

When physics models require environmental data, ASTRA follows a strict priority hierarchy (strict mode is enabled by default as of v3.6.1):

  1. Spacebook / COMSPOC (live observational) — space weather, EOP, synthetic covariance.

  2. CelesTrak — SW-All.csv space weather fallback; standard TLE/OMM.

  3. Synthetic defaults — (F10.7 = 150, Ap = 15); forbidden in strict mode.

Error Hierarchy

All ASTRA errors inherit from AstraError:

  • InvalidTLEError — malformed TLE checksum or out-of-range field.

  • PropagationError — SGP4 error code or NaN trajectory in strict mode.

  • EphemerisError — DE421 unavailable in strict mode.

  • SpaceWeatherError — space weather data missing in strict mode.

  • CoordinateError — frame transformation failure.

  • ManeuverError — invalid burn sequence or parameter.

  • FilterError — catalog filter configuration error.

  • SpacebookError — Spacebook network / HTTP failure.

  • SpacebookLookupError — NORAD ID not found in Spacebook SATCAT.