Documentation / @interstellar-tools/equations

@interstellar-tools/equations

Curated, tested orbital mechanics and dynamics formulas: Newtonian gravity, vis-viva, Kepler’s third law, Kepler’s equation solvers, anomaly conversions, Hohmann transfers, rocket equation, J2 perturbations and more. SI units in, SI units out, with clear errors for invalid input.

Documentation

The full documentation lives at phun-ky.net/interstellar-tools:

• Getting started: installation, unit conventions and recommended practices
• API reference for @interstellar-tools/equations: every export, with formulas, parameters and examples

Installation

• Node.js version 22.9.0 or higher

npm

npm i --save @interstellar-tools/equations

WARNING

These equations have not YET been battle-tested or tested to real world mechanics, YMMV!

Here you will find a set of function that can assist you when calculating orbits, angles, solve for kelper or find true anomalies.

Type Aliases

Type Alias	Description
HohmannTransferReturnType	-

Functions

Function	Description
planetographicLatitudeOblate	Compute planetographic latitude (oblate spheroid) from body-fixed Cartesian coordinates.

Angles

Function	Description
computeAngle	Advances a body along its orbit by one time step and returns its new true anomaly ($\nu$).
wrapAngle	Wrap an angle (in radians) to a single-turn range and snap values extremely close to ±τ (±2π) back to 0 to curb floating-point drift.

Anomalies

Function	Description
advanceMeanAnomaly	Advances an orbit by a time step and returns its new mean anomaly ($M$).
eccentricToTrueAnomaly	Converts Eccentric Anomaly ($E$) to True Anomaly ($V$) for an orbit.
meanAnomalyAt	The mean anomaly ($M$) of an orbit at a given date.
trueAnomalyAt	The true anomaly ($\nu$) of an orbit at a given date: where the body is.
trueToMeanAnomaly	Converts true anomaly ($\nu$) to mean anomaly ($M$) using Kepler's equation.

Cartography

Function	Description
bodyFixedFromInertialDcmIAU	Build the IAU-style inertial → body-fixed direction cosine matrix (DCM).
eccentricitySquaredOblateSpheroid	Compute first eccentricity squared ($e^2$) for an oblate spheroid.
flatteningOblateSpheroid	Compute flattening ($f$) of an oblate spheroid.
isOnTriaxialEllipsoidSurface	Test whether a 3D point lies on the surface of a triaxial ellipsoid (within a tolerance).
planetocentricLatitude	Compute planetocentric latitude (${\phi }_c$) from body-fixed Cartesian coordinates.

Gravity

Function	Description
accelerationOn1By2	Gravitational acceleration of body 1 due to body 2 (vector, m/s²).
forceOn1By2	Gravitational force vector on body 1 due to body 2 (newtons, N).
gravitationalForce	Compute the Newtonian gravitational force on body 1 due to body 2.
gravitationalParameter	Two-body gravitational parameter ($\mu$).

Helpers

Name	Description
METERS_PER	Meters-per-unit lookup for all canonical DistanceUnitType symbols.
NORMALIZE_DISTANCE_UNIT	Lookup table that normalizes distance unit aliases (and the canonical symbols themselves) to a single, canonical DistanceUnitType.
applyMatrix3	Apply a 3×3 matrix to a 3D vector (matrix–vector multiplication).
convertDistanceUnit	Convert a distance between any two DistanceUnitType units.
det3	Compute the determinant of a 3×3 matrix (row-major).
dot	Compute the dot product of two 3D vectors.
matMul3	Multiply two 3×3 matrices (row-major).
norm	Compute the Euclidean norm (length / magnitude) of a 3D vector.
norm2pi	Normalize an angle to the range [0, 2π).
normalizeDistanceUnit	Normalize a distance unit string into a canonical DistanceUnitType.
rad	Brand a numeric value as Radians.
rot1	Construct a right-handed rotation matrix about the x-axis (often written R₁).
rot3	Construct a right-handed rotation matrix about the z-axis (often written R₃).
scale	Scale a 3D vector by a scalar.
sub	Subtract two 3D vectors (a - b).
toRad	Convert degrees → radians.
transpose3	Transpose a 3×3 matrix (row-major).

Kepler

Function	Description
residual	Compute the Kepler equation residual for an elliptical orbit:

Kepler Solvers

Function	Description
solveKepler	Solves Kepler's Equation for the Eccentric Anomaly ($E$) using an adaptive approach:
solveKeplerBisection	Solve Kepler's equation for the eccentric anomaly ($E$) via bisection (elliptic case: ($0\le e<1$)).
solveKeplerHighEccentricity	Solves Kepler's Equation for the Eccentric Anomaly ($E$) in highly eccentric orbits ($e>0.9$) using an iterative numerical approach.
solveKeplerNewtonRaphson	Solves Kepler's Equation for the Eccentric Anomaly ($E$) using the Newton-Raphson method with Householder acceleration for fast convergence.

Manoeuvres

Function	Description
combineBurnsDeltaV	Combine non-collinear burns (vector law / law of cosines for velocities).
gravityAssistTurningAngle	Compute gravity-assist turning angle (flyby deflection) for a hyperbolic encounter.
hohmannSemiMajorAxis	Convenience: compute only the semi-major axis ($a_t$) (m) of the Hohmann transfer.
hohmannTransfer	Hohmann transfer (coplanar, circular ($r_1\to r_2$)).
hohmannTransferTime	Convenience: compute only the transfer time ($t_t$) (s).
oberthEnergyGain	Oberth effect (specific energy gain near periapsis).
planeChangeDeltaV	Inclination (plane) change Δv at speed ($v$).
rocketDeltaVFromIsp	Compute ideal delta-v from the Tsiolkovsky rocket equation using specific impulse.
rocketDeltaVFromVe	Compute ideal delta-v from the Tsiolkovsky rocket equation using effective exhaust velocity.

Orbits

Function	Description
atmosphericDragAcceleration	Compute atmospheric drag acceleration magnitude.
characteristicEnergyC3	Compute characteristic energy (C3) from hyperbolic excess speed.
circularSpeed	Circular speed ($v_c$) for a body in a circular orbit at radius ($r$).
cwHillDerivatives	Compute the time-derivative of a Clohessy–Wiltshire / Hill relative-motion state (right-hand side for ODE integration).
escapeSpeed	Escape speed ($v_{\text{esc}}$) - minimum speed to escape a central body's gravity from radius ($r$) (ignoring drag/perturbations).
flightPathAngleFromTrueAnomaly	Flight-path angle ($\gamma$) from true anomaly ($\nu$) and eccentricity ($e$).
hyperbolicPeriapsisSpeed	Compute hyperbolic periapsis speed for a flyby/escape hyperbola.
j2ArgumentOfPerigeeRate	Compute argument of perigee rotation (J2 secular drift of ω) for an orbit about an oblate body.
j2NodalPrecessionRate	Compute J2 nodal precession (RAAN drift) for an orbit about an oblate body.
keplerPeriod	Kepler's 3rd law - orbital period ($T$) from semi-major axis ($a$) and gravitational parameter ($\mu$).
meanMotion	Compute mean motion for a (near-)circular reference orbit.
periApoapsisRadii	Peri/apoapsis radii from semi-major axis ($a$) and eccentricity ($e$).
specificAngularMomentum	Specific angular momentum ($h$) (scalar magnitude).
specificAngularMomentumFromElements	Specific angular momentum ($h$) from orbital elements.
specificMechanicalEnergy	Specific mechanical energy ($\epsilon$) of a point mass in a central gravity field.
sphereOfInfluenceRadius	Compute sphere of influence radius (patched conics approximation).
visVivaSpeed	Vis-viva (orbital speed) - compute speed magnitude ($v$) from ($r$), ($a$), and ($\mu$).