Documentation / @interstellar-tools/equations / solveKepler

Function: solveKepler()

function solveKepler(
  M: Radians,
  e: number,
  maxIter?: number,
  tolerance?: number
): Radians;

Defined in: kepler/solve-kepler.ts:98

Solves Kepler's Equation for the Eccentric Anomaly ($E$) using an adaptive approach:

• Newton-Raphson method for fast convergence.
• High-eccentricity solver for extreme orbits ($e>0.9$).
• Bisection fallback if the selected solver doesn't return a root.

This is the conversion from mean anomaly to eccentric anomaly. Use eccentricToTrueAnomaly on the result to get the true anomaly.

---

Mathematical Explanation:

Kepler's equation relates the mean anomaly ($M$), the eccentric anomaly ($E$), and the orbital eccentricity ($e$) as:

$$M=E-e\sin (E)$$

Since this equation cannot be solved algebraically, numerical methods are required.

---

Solving Strategy:

1. Handle Special Cases:

   • If the orbit is circular ($e=0$), then $E=M$ directly.
   • If the orbit is parabolic ($e=1$), an exception is thrown.
   • If eccentricity is out of range ($e<0$ or $e\ge 1$), a RangeError is thrown.

2. Select the Best Solver:

   • For high eccentricities ($e>0.9$) → Uses solveKeplerHighEccentricity().
   • For moderate eccentricities ($e\le 0.9$) → Uses solveKeplerNewtonRaphson().
   • The result is verified against Kepler's equation ($|E-e\sin E-M|\le$ tolerance, modulo $2\pi$). If the solver didn't converge (NaN), stopped at maxIter, or settled away from the root, it falls back to solveKeplerBisection(), which always brackets the root.

3. Normalization:

   • Kepler's equation is $2\pi$-periodic ($M+2\pi k\mapsto E+2\pi k$), so $M$ is first reduced to $[0,2\pi )$ with norm2pi(). This keeps the solvers in their stable range for any finite $M$, including negative values and many revolutions.
   • The solution is normalized to $[0,2\pi )$ with norm2pi().

---

Performance Considerations:

• Newton-Raphson typically converges in 4-5 iterations.
• Bisection fallback ensures robustness for extreme cases.
• High-eccentricity solver prevents instability for $e\approx 1$.

---

Parameters

Parameter	Type	Default value	Description
M	Radians	undefined	Mean anomaly ($M$) in radians.
e	number	undefined	Orbital eccentricity ($0\le e<1$).
maxIter?	number	50	Maximum number of iterations before fallback.
tolerance?	number	1e-9	Convergence criterion for stopping the iteration.

Returns

Radians

The eccentric anomaly ($E$) in radians (normalized to $[0,2\pi )$).

Throws

RangeError If the eccentricity ($e$) is invalid ($e<0$ or $e\ge 1$).

---

Examples

import { solveKepler } from '@interstellar-tools/equations';

// Example 1: Moderate eccentricity
const M = Math.PI / 4; // 45 degrees in radians
const e = 0.1; // Orbital eccentricity
const result = solveKepler(M, e);
console.log(result); // Output: Eccentric anomaly in radians

// Example 2: High-eccentricity orbit (e > 0.9)
const M_high = 1.5; // Mean anomaly in radians
const e_high = 0.95; // High eccentricity
console.log(solveKepler(M_high, e_high)); // Uses high-eccentricity solver

---

See

• Kepler's Equation (Wikipedia)
• Newton-Raphson Method (Wikipedia)
• Eccentric Anomaly (Wikipedia)
• RangeError