@interstellar-tools/equations 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ *
+ *  Here you will find a set of function that can assist you when calculating orbits, angles, solve for kelper or find true anomalies.
+ * @showCategories
+ * @module
+ */
+export * from './compute-angle';
+export * from './compute-mean-anomaly';
+export * from './eccentric-to-true-anomaly';
+export * from './solve-kepler-bisection';
+export * from './solve-kepler-high-eccentricity';
+export * from './solve-kepler-newton-raphson';
+export * from './solve-kepler';
+export * from './true-anomaly-to-mean-anomaly';
+export * from './wrap-angle';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,iBAAiB,CAAC;AAEhC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,6BAA6B,CAAC;AAE5C,cAAc,0BAA0B,CAAC;AAEzC,cAAc,kCAAkC,CAAC;AAEjD,cAAc,+BAA+B,CAAC;AAE9C,cAAc,gBAAgB,CAAC;AAE/B,cAAc,gCAAgC,CAAC;AAE/C,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ *
+ *  Here you will find a set of function that can assist you when calculating orbits, angles, solve for kelper or find true anomalies.
+ * @showCategories
+ * @module
+ */
+export * from './compute-angle';
+export * from './compute-mean-anomaly';
+export * from './eccentric-to-true-anomaly';
+export * from './solve-kepler-bisection';
+export * from './solve-kepler-high-eccentricity';
+export * from './solve-kepler-newton-raphson';
+export * from './solve-kepler';
+export * from './true-anomaly-to-mean-anomaly';
+export * from './wrap-angle';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,iBAAiB,CAAC;AAEhC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,6BAA6B,CAAC;AAE5C,cAAc,0BAA0B,CAAC;AAEzC,cAAc,kCAAkC,CAAC;AAEjD,cAAc,+BAA+B,CAAC;AAE9C,cAAc,gBAAgB,CAAC;AAE/B,cAAc,gCAAgC,CAAC;AAE/C,cAAc,cAAc,CAAC"}

package/dist/solve-kepler-bisection.d.ts

@@ -0,0 +1,75 @@
+import { Radians } from '@interstellar-tools/types';
+/**
+ * Solves **Kepler's Equation** for the **Eccentric Anomaly** ($E$) using the **bisection method**
+ * when Newton-Raphson or other iterative solvers fail to converge.
+ *
+ * ---
+ *
+ * **Mathematical Explanation:**
+ *
+ * Kepler's equation for eccentric anomaly ($E$) is:
+ * $$
+ * M = E - e \sin(E)
+ * $$
+ * This equation cannot be solved analytically, and numerical methods must be used.
+ * When standard iterative solvers like **Newton-Raphson** fail due to poor convergence,
+ * the **bisection method** provides a robust alternative by performing a bracketed search.
+ *
+ * ---
+ *
+ * **Solving Strategy:**
+ * 1. **Initialize Bounds:**
+ *    - The valid range for $E$ is **$[0, \pi]$** (as $E$ is symmetric around 0).
+ *    - The midpoint $E_0$ is chosen as:
+ *      $$
+ *      E = \frac{E_{low} + E_{high}}{2}
+ *      $$
+ *
+ * 2. **Bisection Iteration:**
+ *    - Compute the function residual:
+ *      $$
+ *      F(E) = E - e \sin(E) - M
+ *      $$
+ *    - If $F(E)$ is sufficiently small (within tolerance), $E$ is returned as the solution.
+ *    - Otherwise, the interval is **halved** by updating either:
+ *      - The lower bound ($E_{low}$) if $F(E) < 0$
+ *      - The upper bound ($E_{high}$) if $F(E) > 0$
+ *
+ * 3. **Convergence Check:**
+ *    - The iteration stops when:
+ *      $$
+ *      |E_{n+1} - E_n| < \text{tolerance}
+ *      $$
+ *      (default tolerance is **1e-9**).
+ *
+ * ---
+ *
+ * **Performance Considerations:**
+ * - **Always converges**, unlike Newton-Raphson, which can fail for some initial guesses.
+ * - **Time complexity:** $O(\log N)$ due to the **logarithmic convergence** of bisection.
+ *
+ * ---
+ *
+ * @param {Radians} M - Mean anomaly ($M$) in **radians**.
+ * @param {number} e - Orbital eccentricity ($0 \leq e < 1$).
+ * @param {number} maxIter - Maximum number of **iterations** before failure.
+ * @param {number} tolerance - Convergence criterion for stopping the iteration.
+ * @returns {Radians} The **eccentric anomaly** ($E$) in **radians** (best approximation).
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * const M = Math.PI / 3; // 60 degrees in radians
+ * const e = 0.5; // Orbital eccentricity
+ * console.log(solveKeplerBisection(M, e, 50, 1e-9)); // Output: Eccentric anomaly in radians
+ * ```
+ *
+ * ---
+ *
+ * @see [Kepler's Equation (Wikipedia)](https://en.wikipedia.org/wiki/Kepler%27s_equation)
+ * @see [Bisection Method (Wikipedia)](https://en.wikipedia.org/wiki/Bisection_method)
+ * @category Solve for Kepler
+ */
+export declare const solveKeplerBisection: (M: Radians, e: number, maxIter: number, tolerance: number) => Radians;
+//# sourceMappingURL=solve-kepler-bisection.d.ts.map

package/dist/solve-kepler-bisection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solve-kepler-bisection.d.ts","sourceRoot":"","sources":["../src/solve-kepler-bisection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,eAAO,MAAM,oBAAoB,GAC/B,GAAG,OAAO,EACV,GAAG,MAAM,EACT,SAAS,MAAM,EACf,WAAW,MAAM,KAChB,OAwBF,CAAC"}

package/dist/solve-kepler-bisection.js

@@ -0,0 +1,94 @@
+/**
+ * Solves **Kepler's Equation** for the **Eccentric Anomaly** ($E$) using the **bisection method**
+ * when Newton-Raphson or other iterative solvers fail to converge.
+ *
+ * ---
+ *
+ * **Mathematical Explanation:**
+ *
+ * Kepler's equation for eccentric anomaly ($E$) is:
+ * $$
+ * M = E - e \sin(E)
+ * $$
+ * This equation cannot be solved analytically, and numerical methods must be used.
+ * When standard iterative solvers like **Newton-Raphson** fail due to poor convergence,
+ * the **bisection method** provides a robust alternative by performing a bracketed search.
+ *
+ * ---
+ *
+ * **Solving Strategy:**
+ * 1. **Initialize Bounds:**
+ *    - The valid range for $E$ is **$[0, \pi]$** (as $E$ is symmetric around 0).
+ *    - The midpoint $E_0$ is chosen as:
+ *      $$
+ *      E = \frac{E_{low} + E_{high}}{2}
+ *      $$
+ *
+ * 2. **Bisection Iteration:**
+ *    - Compute the function residual:
+ *      $$
+ *      F(E) = E - e \sin(E) - M
+ *      $$
+ *    - If $F(E)$ is sufficiently small (within tolerance), $E$ is returned as the solution.
+ *    - Otherwise, the interval is **halved** by updating either:
+ *      - The lower bound ($E_{low}$) if $F(E) < 0$
+ *      - The upper bound ($E_{high}$) if $F(E) > 0$
+ *
+ * 3. **Convergence Check:**
+ *    - The iteration stops when:
+ *      $$
+ *      |E_{n+1} - E_n| < \text{tolerance}
+ *      $$
+ *      (default tolerance is **1e-9**).
+ *
+ * ---
+ *
+ * **Performance Considerations:**
+ * - **Always converges**, unlike Newton-Raphson, which can fail for some initial guesses.
+ * - **Time complexity:** $O(\log N)$ due to the **logarithmic convergence** of bisection.
+ *
+ * ---
+ *
+ * @param {Radians} M - Mean anomaly ($M$) in **radians**.
+ * @param {number} e - Orbital eccentricity ($0 \leq e < 1$).
+ * @param {number} maxIter - Maximum number of **iterations** before failure.
+ * @param {number} tolerance - Convergence criterion for stopping the iteration.
+ * @returns {Radians} The **eccentric anomaly** ($E$) in **radians** (best approximation).
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * const M = Math.PI / 3; // 60 degrees in radians
+ * const e = 0.5; // Orbital eccentricity
+ * console.log(solveKeplerBisection(M, e, 50, 1e-9)); // Output: Eccentric anomaly in radians
+ * ```
+ *
+ * ---
+ *
+ * @see [Kepler's Equation (Wikipedia)](https://en.wikipedia.org/wiki/Kepler%27s_equation)
+ * @see [Bisection Method (Wikipedia)](https://en.wikipedia.org/wiki/Bisection_method)
+ * @category Solve for Kepler
+ */
+export const solveKeplerBisection = (M, e, maxIter, tolerance) => {
+    let E_low = 0;
+    let E_high = Math.PI;
+    let E = (E_low + E_high) / 2;
+    let iter = 0;
+    while (iter < maxIter) {
+        const F = E - e * Math.sin(E) - M;
+        if (Math.abs(F) < tolerance) {
+            return E; // Converged
+        }
+        if (F > 0) {
+            E_high = E;
+        }
+        else {
+            E_low = E;
+        }
+        E = (E_low + E_high) / 2;
+        iter++;
+    }
+    return E; // Best approximation
+};
+//# sourceMappingURL=solve-kepler-bisection.js.map

package/dist/solve-kepler-bisection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solve-kepler-bisection.js","sourceRoot":"","sources":["../src/solve-kepler-bisection.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,CAAU,EACV,CAAS,EACT,OAAe,EACf,SAAiB,EACR,EAAE;IACX,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IACrB,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,IAAI,GAAG,CAAC,CAAC;IAEb,OAAO,IAAI,GAAG,OAAO,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,EAAE,CAAC;YAC5B,OAAO,CAAC,CAAC,CAAC,YAAY;QACxB,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACV,MAAM,GAAG,CAAC,CAAC;QACb,CAAC;aAAM,CAAC;YACN,KAAK,GAAG,CAAC,CAAC;QACZ,CAAC;QAED,CAAC,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,EAAE,CAAC;IACT,CAAC;IAED,OAAO,CAAC,CAAC,CAAC,qBAAqB;AACjC,CAAC,CAAC"}

package/dist/solve-kepler-high-eccentricity.d.ts

@@ -0,0 +1,99 @@
+import { Radians } from '@interstellar-tools/types';
+/**
+ * Solves **Kepler's Equation** for the **Eccentric Anomaly** ($E$) in highly eccentric orbits
+ * ($e > 0.9$) using an iterative numerical approach.
+ *
+ * ---
+ *
+ * **Mathematical Explanation:**
+ *
+ * Kepler's equation for eccentric anomaly ($E$) is:
+ *
+ * ![solve-kelper-high-eccentricity-elliptical-orbit](https://raw.githubusercontent.com/phun-ky/interstellar/b607daf8e014128a6dceb3cf8d522676f06bc233/public/solve-kelper-high-eccentricity-elliptical-orbit.svg)
+ *
+ * $$
+ * M = E - e \sin(E) \quad \text{(for elliptical orbits, } 0 < e < 1\text{)}
+ * $$
+ *
+ * ![solve-kepler-high-eccentricity-hyperbolic-orbit](https://raw.githubusercontent.com/phun-ky/interstellar/b607daf8e014128a6dceb3cf8d522676f06bc233/public/solve-kepler-high-eccentricity-hyperbolic-orbit.svg)
+ *
+ * $$
+ * M = e \sinh(E) - E \quad \text{(for hyperbolic orbits, } e > 1\text{)}
+ * $$
+ *
+ * For orbits with **high eccentricity** ($e \approx 1$), standard Newton-Raphson solvers struggle
+ * due to extreme changes in orbital velocity near perihelion. Instead, we apply a **fixed-point iteration**
+ * method that is more stable for these cases.
+ *
+ * ---
+ *
+ * **Solving Strategy:**
+ * 1. **Initial Guess:**
+ *    - The solver starts with $E_0 = M$ and refines using:
+ * $$
+ * E_0 = M \pm \frac{e \sin(M)}{1 - e \cos(M)}
+ * $$
+ *
+ * 2. **Iterative Refinement:**
+ *    - The method updates $E$ using:
+ * $$
+ * \Delta E = \frac{E - e \sin(E) - M}{1 - e \cos(E)}
+ * $$
+ * for elliptical orbits.
+ *
+ * $$
+ * \Delta E = \frac{e \sinh(E) - E - M}{e \cosh(E) - 1}
+ * $$
+ * for hyperbolic orbits.
+ *
+ *    - Iteration stops when:
+ * $$
+ * |E_{n+1} - E_n| < \text{tolerance}
+ * $$
+ * (default tolerance is **1e-9**).
+ *
+ * 3. **Angle Wrapping (Elliptical Only):**
+ *    - The result is wrapped using `wrapAngle()` for consistency.
+ *
+ * ---
+ *
+ * **Performance Considerations:**
+ * - **Typically converges in fewer than 10 iterations for $e > 0.9$.**
+ * - **Time complexity:** $O(1)$ for standard convergence.
+ *
+ * ---
+ *
+ * @param {Radians} M - Mean anomaly ($M$) in **radians**.
+ * @param {number} e - Orbital eccentricity ($e > 0.9$ for high-eccentricity orbits).
+ * @param {number} [maxIter=Math.max(300, Math.floor(5 + 3 * Math.log(1 + Math.abs(M))))] - Maximum number of **iterations** before failure.
+ * @param {number} [tolerance=1e-9] - Convergence criterion for stopping the iteration.
+ * @returns {Radians} The **eccentric anomaly** ($E$) in **radians** (wrapped to $[-\pi, \pi]$ for elliptical orbits).
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * import { solveKeplerHighEccentricity } from './solve-kepler';
+ *
+ * const M = Math.PI / 4; // 45 degrees in radians
+ * const e = 0.95; // High orbital eccentricity
+ * const result = solveKeplerHighEccentricity(M, e);
+ * console.log(result); // Output: Eccentric anomaly in radians
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Hyperbolic orbit example (e > 1)
+ * const M_hyperbolic = 2.0; // Mean anomaly for hyperbolic orbit
+ * const e_hyperbolic = 1.2; // Hyperbolic eccentricity
+ * console.log(solveKeplerHighEccentricity(M_hyperbolic, e_hyperbolic));
+ * ```
+ *
+ * ---
+ *
+ * @see [Kepler's Equation (Wikipedia)](https://en.wikipedia.org/wiki/Kepler%27s_equation)
+ * @see [Hyperbolic Anomaly (Wikipedia)](https://en.wikipedia.org/wiki/Hyperbolic_trajectory#Hyperbolic_anomaly)
+ * @category Solve for Kepler
+ */
+export declare const solveKeplerHighEccentricity: (M: Radians, e: number, maxIter?: number, tolerance?: number) => Radians;
+//# sourceMappingURL=solve-kepler-high-eccentricity.d.ts.map

package/dist/solve-kepler-high-eccentricity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solve-kepler-high-eccentricity.d.ts","sourceRoot":"","sources":["../src/solve-kepler-high-eccentricity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAIpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+FG;AACH,eAAO,MAAM,2BAA2B,GACtC,GAAG,OAAO,EACV,GAAG,MAAM,EACT,gBAAsE,EACtE,kBAAgB,KACf,OAgEF,CAAC"}

package/dist/solve-kepler-high-eccentricity.js

@@ -0,0 +1,150 @@
+import { wrapAngle } from './wrap-angle';
+/**
+ * Solves **Kepler's Equation** for the **Eccentric Anomaly** ($E$) in highly eccentric orbits
+ * ($e > 0.9$) using an iterative numerical approach.
+ *
+ * ---
+ *
+ * **Mathematical Explanation:**
+ *
+ * Kepler's equation for eccentric anomaly ($E$) is:
+ *
+ * ![solve-kelper-high-eccentricity-elliptical-orbit](https://raw.githubusercontent.com/phun-ky/interstellar/b607daf8e014128a6dceb3cf8d522676f06bc233/public/solve-kelper-high-eccentricity-elliptical-orbit.svg)
+ *
+ * $$
+ * M = E - e \sin(E) \quad \text{(for elliptical orbits, } 0 < e < 1\text{)}
+ * $$
+ *
+ * ![solve-kepler-high-eccentricity-hyperbolic-orbit](https://raw.githubusercontent.com/phun-ky/interstellar/b607daf8e014128a6dceb3cf8d522676f06bc233/public/solve-kepler-high-eccentricity-hyperbolic-orbit.svg)
+ *
+ * $$
+ * M = e \sinh(E) - E \quad \text{(for hyperbolic orbits, } e > 1\text{)}
+ * $$
+ *
+ * For orbits with **high eccentricity** ($e \approx 1$), standard Newton-Raphson solvers struggle
+ * due to extreme changes in orbital velocity near perihelion. Instead, we apply a **fixed-point iteration**
+ * method that is more stable for these cases.
+ *
+ * ---
+ *
+ * **Solving Strategy:**
+ * 1. **Initial Guess:**
+ *    - The solver starts with $E_0 = M$ and refines using:
+ * $$
+ * E_0 = M \pm \frac{e \sin(M)}{1 - e \cos(M)}
+ * $$
+ *
+ * 2. **Iterative Refinement:**
+ *    - The method updates $E$ using:
+ * $$
+ * \Delta E = \frac{E - e \sin(E) - M}{1 - e \cos(E)}
+ * $$
+ * for elliptical orbits.
+ *
+ * $$
+ * \Delta E = \frac{e \sinh(E) - E - M}{e \cosh(E) - 1}
+ * $$
+ * for hyperbolic orbits.
+ *
+ *    - Iteration stops when:
+ * $$
+ * |E_{n+1} - E_n| < \text{tolerance}
+ * $$
+ * (default tolerance is **1e-9**).
+ *
+ * 3. **Angle Wrapping (Elliptical Only):**
+ *    - The result is wrapped using `wrapAngle()` for consistency.
+ *
+ * ---
+ *
+ * **Performance Considerations:**
+ * - **Typically converges in fewer than 10 iterations for $e > 0.9$.**
+ * - **Time complexity:** $O(1)$ for standard convergence.
+ *
+ * ---
+ *
+ * @param {Radians} M - Mean anomaly ($M$) in **radians**.
+ * @param {number} e - Orbital eccentricity ($e > 0.9$ for high-eccentricity orbits).
+ * @param {number} [maxIter=Math.max(300, Math.floor(5 + 3 * Math.log(1 + Math.abs(M))))] - Maximum number of **iterations** before failure.
+ * @param {number} [tolerance=1e-9] - Convergence criterion for stopping the iteration.
+ * @returns {Radians} The **eccentric anomaly** ($E$) in **radians** (wrapped to $[-\pi, \pi]$ for elliptical orbits).
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * import { solveKeplerHighEccentricity } from './solve-kepler';
+ *
+ * const M = Math.PI / 4; // 45 degrees in radians
+ * const e = 0.95; // High orbital eccentricity
+ * const result = solveKeplerHighEccentricity(M, e);
+ * console.log(result); // Output: Eccentric anomaly in radians
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Hyperbolic orbit example (e > 1)
+ * const M_hyperbolic = 2.0; // Mean anomaly for hyperbolic orbit
+ * const e_hyperbolic = 1.2; // Hyperbolic eccentricity
+ * console.log(solveKeplerHighEccentricity(M_hyperbolic, e_hyperbolic));
+ * ```
+ *
+ * ---
+ *
+ * @see [Kepler's Equation (Wikipedia)](https://en.wikipedia.org/wiki/Kepler%27s_equation)
+ * @see [Hyperbolic Anomaly (Wikipedia)](https://en.wikipedia.org/wiki/Hyperbolic_trajectory#Hyperbolic_anomaly)
+ * @category Solve for Kepler
+ */
+export const solveKeplerHighEccentricity = (M, e, maxIter = Math.max(300, Math.floor(5 + 3 * Math.log(1 + Math.abs(M)))), tolerance = 1e-9) => {
+    if (e < 0) {
+        throw new RangeError(`Invalid eccentricity: ${e}. Must be e ≥ 0.`);
+    }
+    let E;
+    // Use a more accurate initial guess for highly eccentric orbits
+    if (M < 0) {
+        E = M - (e * Math.sin(M)) / (1 - e * Math.cos(M));
+    }
+    else {
+        E = M + (e * Math.sin(M)) / (1 - e * Math.cos(M));
+    }
+    let delta = 1;
+    let iter = 0;
+    let lastValidE = E;
+    while (Math.abs(delta) > tolerance && iter < maxIter) {
+        let fE;
+        let dfE;
+        // **Elliptical Orbit (0.9 < e < 1)**
+        if (e < 1) {
+            fE = E - e * Math.sin(E) - M;
+            dfE = 1 - e * Math.cos(E);
+        }
+        // **Hyperbolic Orbit (e > 1)**
+        else {
+            const sinhE = Math.sinh(E);
+            const coshE = Math.cosh(E);
+            fE = e * sinhE - E - M;
+            dfE = e * coshE - 1;
+        }
+        // **Prevent divide-by-zero issues**
+        dfE = Math.max(Math.abs(dfE), 1e-6) * Math.sign(dfE);
+        delta = fE / dfE;
+        // **Clamp delta to prevent large jumps**
+        delta = Math.sign(delta) * Math.min(Math.abs(delta), 0.5);
+        E -= delta;
+        iter++;
+        if (!isNaN(E) && isFinite(E)) {
+            lastValidE = E;
+        }
+        // **Clamp extreme values to prevent divergence**
+        if (Math.abs(E) > 100) {
+            E = 100 * Math.sign(E);
+            break;
+        }
+    }
+    // **Wrap angles to the range [-π, π] for elliptical orbits**
+    if (e < 1) {
+        lastValidE = wrapAngle(lastValidE);
+    }
+    return lastValidE;
+};
+//# sourceMappingURL=solve-kepler-high-eccentricity.js.map

package/dist/solve-kepler-high-eccentricity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solve-kepler-high-eccentricity.js","sourceRoot":"","sources":["../src/solve-kepler-high-eccentricity.ts"],"names":[],"mappings":"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"}

package/dist/solve-kepler-newton-raphson.d.ts

@@ -0,0 +1,87 @@
+import { Radians } from '@interstellar-tools/types';
+/**
+ * Solves **Kepler's Equation** for the **Eccentric Anomaly** ($E$) using the **Newton-Raphson method**
+ * with Householder acceleration for fast convergence.
+ *
+ * ---
+ *
+ * **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**, iterative 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 **nearly parabolic** ($e \geq 0.97$), a special approximation is used.
+ *    - If **eccentricity is out of range** ($e < 0$ or $e \geq 1$), a `RangeError` is thrown.
+ *
+ * 2. **Initial Approximation:**
+ *    - **For small eccentricities ($e < 0.8$):** $E_0 = M$.
+ *    - **For moderate eccentricities ($0.8 \leq e < 0.97$):** $E_0 = M + e \sin(M) (1 + e \cos(M))$.
+ *    - **For nearly parabolic orbits ($e \geq 0.97$):** $E_0 = \frac{6M}{e}$.
+ *
+ * 3. **Newton-Raphson Iteration with Householder Acceleration:**
+ *    - The **Newton-Raphson method** iterates using:
+ *      $$
+ *      E_{n+1} = E_n - \frac{f(E_n)}{f'(E_n)}
+ *      $$
+ *      where:
+ *      - $f(E) = E - e \sin(E) - M$
+ *      - $f'(E) = 1 - e \cos(E)$
+ *
+ *    - **Householder acceleration** refines the correction:
+ *      $$
+ *      \Delta E = \frac{f(E)}{f'(E)} \left( 1 - \frac{1}{2} \frac{f''(E)}{f'(E)} \Delta E \right)^{-1}
+ *      $$
+ *
+ * 4. **Convergence Check:**
+ *    - The iteration stops when:
+ *      $$
+ *      |E_{n+1} - E_n| < \text{tolerance}
+ *      $$
+ *      (default tolerance is **1e-9**).
+ *
+ * 5. **Failure Handling:**
+ *    - If the method **does not converge**, `NaN` is returned, signaling that a fallback method should be used.
+ *
+ * ---
+ *
+ * **Performance Considerations:**
+ * - **Typically converges in 4-5 iterations for most eccentricities.**
+ * - **Time complexity:** $O(1)$ for Newton-Raphson.
+ *
+ * ---
+ *
+ * @param {Radians} M - Mean anomaly ($M$) in **radians**.
+ * @param {number} e - Orbital eccentricity ($0 \leq e < 1$).
+ * @param {number} maxIter - Maximum number of **iterations** before failure.
+ * @param {number} tolerance - Convergence criterion for stopping the iteration.
+ * @returns {Radians} The **eccentric anomaly** ($E$) in **radians** (or `NaN` if the method fails).
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError | RangeError} If the **eccentricity ($e$) is invalid** ($e < 0$ or $e \geq 1$).
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * const M = Math.PI / 4; // 45 degrees in radians
+ * const e = 0.1; // Orbital eccentricity
+ * console.log(solveKeplerNewtonRaphson(M, e, 50, 1e-9)); // Output: Eccentric anomaly in radians
+ * ```
+ *
+ * ---
+ *
+ * @see [Kepler's Equation (Wikipedia)](https://en.wikipedia.org/wiki/Kepler%27s_equation)
+ * @see [Newton-Raphson Method (Wikipedia)](https://en.wikipedia.org/wiki/Newton%27s_method)
+ * @see [Eccentric Anomaly (Wikipedia)](https://en.wikipedia.org/wiki/Mean_anomaly#Eccentric_anomaly)
+ * @category Solve for Kepler
+ */
+export declare const solveKeplerNewtonRaphson: (M: Radians, e: number, maxIter: number, tolerance: number) => Radians;
+//# sourceMappingURL=solve-kepler-newton-raphson.d.ts.map

package/dist/solve-kepler-newton-raphson.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solve-kepler-newton-raphson.d.ts","sourceRoot":"","sources":["../src/solve-kepler-newton-raphson.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,eAAO,MAAM,wBAAwB,GACnC,GAAG,OAAO,EACV,GAAG,MAAM,EACT,SAAS,MAAM,EACf,WAAW,MAAM,KAChB,OAwCF,CAAC"}