Astrial API & Spacecraft API

Keplerian Orbital Elements

All orbital calculations are based on six orbital elements that uniquely define an object's elliptical orbit:

Element	Symbol	Meaning
Semi-major axis	a	Mean distance from Sun (in AU)
Eccentricity	e	Orbit shape (0 = circle, 0-1 = ellipse)
Inclination	i	Angle to ecliptic plane
Longitude of ascending node	N	Orientation of orbit in 3D space
Argument of perihelion	w	Angle to perihelion (closest point)
Mean anomaly	M	Current position in orbit (0-360°)

Position Calculation Flow

SolarApp calculates celestial body positions through a deterministic pipeline:

1. Time to Days Conversion: Utils.AstralTime(DateTime) converts any date/time to days since December 31, 1999 (J2000 epoch reference).
2. Orbital Element Updates: Each celestial body updates its orbital elements based on elapsed time. Planets use polynomial coefficients; asteroids use fixed elements.
3. Kepler's Equation Solver: The Newton-Raphson numerical method solves Kepler's equation to compute eccentric anomaly from mean anomaly.
4. 3D Position Calculation: Convert from orbital coordinates to 3D heliocentric Cartesian coordinates (X, Y, Z).
5. Hierarchical Positioning: Moons calculate position relative to their parent planet, then offset by the parent's heliocentric position.

The Astrial API

AstrialAPI is the core physics library providing:

Celestial Body Models

• Sun — Reference frame origin; no orbital calculation needed
• Planet — Eight planets with time-varying orbital elements and rotation models
• Moon — Satellites with hierarchical orbit calculations relative to parent
• MinorBody — Asteroids, dwarf planets, comets with fixed or precessing orbits

Each implements DeterminePosition(double time) to compute heliocentric or planet-centric coordinates.

Kepler Solver

The Newton-Raphson solver in the shared DeterminePosition() method solves:

M = E - e * sin(E)

where:
  M = Mean anomaly (input, derived from time)
  E = Eccentric anomaly (output)
  e = Eccentricity

The iterative formula is:

E_{n+1} = E_n - (E_n - e * sin(E_n) - M) / (1 - e * cos(E_n))

This converges rapidly (typically 2-3 iterations) for elliptical orbits with e < 1.

3D Coordinate Transformation

Once eccentric anomaly E is found, compute:

// True anomaly
ν = 2 * atan2(sqrt(1+e) * sin(E/2), sqrt(1-e) * cos(E/2))

// Distance from focus (Sun)
r = a * (1 - e * cos(E))

// Orbital plane coordinates
x_orb = r * cos(ν)
y_orb = r * sin(ν)

// Rotate to heliocentric ecliptic frame using orbital elements (N, i, w)

The Spacecraft API

SpaceCraftAPI extends orbital mechanics for trajectory planning and maneuver design:

Maneuver Planning

• Hohmann & Escape Transfers — Orbit-to-orbit transfers, cislunar injections, and planet-escape trajectories aimed at heliocentric targets
• Gravity Assists & Free Returns — Closed-loop slingshot solving with post-flyby heading targets, plus Apollo-style free-return trajectories
• Lambert's Problem — Pure-Kepler transfer grids that pick launch windows and seed the injection burns for numerical refinement
• Launch & Capture — Closed-loop surface-to-orbit ascents and arrival insertions solved against the integrated trajectory

These phase solvers are composed by the mission compiler, which turns declarative mission JSON into a fully solved multi-leg course — see the Missions deep dive.

Trajectory Propagation

Spacecraft state (position, velocity, mass) is propagated with an adaptive-substep N-body integrator accounting for:

• Solar gravity (dominant)
• Planetary and lunar gravity (moving sources, updated every substep)
• Finite burns (thrust and mass flow from the craft's engine and tank sections)

Substep size adapts to both the craft's speed/acceleration ratio and each gravity source's free-fall timescale, so fast planetary encounters integrate finely even when heliocentric velocity is huge.

Porkchop Analysis

A "porkchop plot" computes the Δv requirement for all combinations of departure and arrival times across a mission window. In the current pipeline these pure-Kepler grids serve as the seed for the closed-loop solvers, which refine the winning cell against the full N-body integration.

Launch Windows

A porkchop grid searches the window it is handed — but something has to decide where that window is. The launch-window finder answers that from ephemeris geometry alone: it measures each body's orbital period by walking its true longitude through one full revolution, takes the semi-major axis from the apsides, derives μ from the origin by Kepler's third law, and then finds when the real ephemeris hits the Hohmann departure phase angle π − ωtarget·ttransfer. No integration, no Lambert solve — microseconds per query.

Measuring rather than approximating matters more than it looks. Mars's eccentricity of 0.093 is enough to shift its departure phase angle from the textbook circular-orbit 44.3° to 34.1° at a real 2028 epoch, and a period estimated by fitting a slope instead of walking a revolution comes out 4.9% wrong — about a month of error in a window centre.

The finder is deliberately advisory: it reports what the geometry offers, and the mission author decides. It also declines to guess — co-orbital bodies have no transfer window at all, and while it will happily report Neptune's (which recurs annually), it reports the 30-year ballistic leg alongside it, because the real answer that far out is a gravity-assist sequence rather than a single Hohmann transfer.

A mission phase can opt into being solved inside the located window, and the catalog carries a matched pair of scenarios to show what that costs. Both fly the same ship out of the same 420 km parking orbit on the same date; one departs immediately, the other waits 70 days for the classical window. The one that waits buys time, not Δv: it still arrives sooner — the window forces a faster crossing — but the faster arrival's higher v∞ is paid straight back at Mars orbit insertion, and the total never comes out meaningfully cheaper than just departing.

That is not a defect in the window; it is a reminder of what the window optimises. The Hohmann phase angle minimises the energy of an idealised two-impulse transfer between circular, coplanar orbits with tangential burns. A real mission to an eccentric Mars near aphelion, departing from a parking orbit that contributes its own Oberth benefit and ending in an orbit-insertion burn that dominates the budget, is none of those things — and its cheapest departure wants a slower crossing than minimum transfer energy nominates. Minimum transfer energy and minimum mission Δv are simply not the same quantity.

Gravitational Influence & Hierarchies

SolarApp uses a heliocentric model as the primary frame, with planet-centric sub-frames for moons:

This avoids accumulating numerical errors that would occur if every moon orbited the Sun directly. Secondary perturbations (e.g., Jupiter's gravity on Saturn's moons) are negligible at rendering scale.

Data Sources & Accuracy

SolarApp loads orbital elements from authoritative sources:

• MPC (Minor Planet Center) — Asteroid and comet orbital elements, updated regularly
• JPL Horizons — High-precision planetary and satellite ephemerides
• DE430/DE440 Ephemeris — NASA's Development Ephemeris for long-term accuracy

Accuracy is typically ±1% in position for modern data, sufficient for visualisation. For deep-space navigation, higher-order perturbations and relativistic corrections would be needed.

Real-Time Performance

SolarApp maintains 60 FPS by:

• Vectorized math — Using Vector3 operations and SIMD where possible
• Lazy evaluation — Calculating only visible bodies each frame
• Spatial queries — Culling orbits and bodies outside camera view
• Caching — Pre-computing common trigonometric values

Integration with the 3D API

The Astrial 3D API bridges orbital mechanics and rendering:

• Query 3D positions for any celestial body at any time
• Get orbital velocity vectors for trajectory visualization
• Retrieve orbital elements for UI display and mission planning
• Predict future positions for trajectory trails and projections

This clean separation allows the rendering layer to focus on visualization while the Astrial API handles all celestial mechanics.

Going Deeper

For the complete mathematical derivation, see the project README which includes Newton-Raphson convergence analysis and numerical stability discussions.