@interstellar-tools/equations 0.1.1

package/dist/solve-kepler-newton-raphson.js

@@ -0,0 +1,118 @@
+/**
+ * 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 const solveKeplerNewtonRaphson = (M, e, maxIter, tolerance) => {
+    if (e < 0 || e >= 1) {
+        throw new RangeError(`Invalid eccentricity: ${e}. Must be in range [0,1].`);
+    }
+    let E;
+    // Smart initial guess
+    if (e < 0.8) {
+        E = M;
+    }
+    else if (e < 0.97) {
+        E = M + e * Math.sin(M) * (1 + e * Math.cos(M));
+    }
+    else {
+        E = (6 * M) / e; // Nearly parabolic case
+    }
+    let iter = 0;
+    while (iter < maxIter) {
+        const F = E - e * Math.sin(E) - M;
+        const dF = 1 - e * Math.cos(E);
+        const d2F = e * Math.sin(E);
+        const d3F = e * Math.cos(E);
+        const deltaE = -F / dF; // Newton’s step
+        // Apply Householder's method for faster convergence
+        let correction = deltaE / (1 - (0.5 * deltaE * d2F) / dF);
+        correction /= 1 - ((1 / 6) * correction * correction * d3F) / dF;
+        E += correction;
+        if (Math.abs(correction) < tolerance) {
+            return E; // Converged
+        }
+        iter++;
+    }
+    return NaN; // Indicate failure
+};
+//# sourceMappingURL=solve-kepler-newton-raphson.js.map

package/dist/solve-kepler-newton-raphson.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solve-kepler-newton-raphson.js","sourceRoot":"","sources":["../src/solve-kepler-newton-raphson.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACtC,CAAU,EACV,CAAS,EACT,OAAe,EACf,SAAiB,EACR,EAAE;IACX,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,UAAU,CAAC,yBAAyB,CAAC,2BAA2B,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,CAAS,CAAC;IAEd,sBAAsB;IACtB,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACZ,CAAC,GAAG,CAAC,CAAC;IACR,CAAC;SAAM,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC;QACpB,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,CAAC;SAAM,CAAC;QACN,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,wBAAwB;IAC3C,CAAC;IAED,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;QAClC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC/B,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5B,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5B,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,gBAAgB;QAExC,oDAAoD;QACpD,IAAI,UAAU,GAAG,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,GAAG,MAAM,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC;QAE1D,UAAU,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,UAAU,GAAG,UAAU,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC;QAEjE,CAAC,IAAI,UAAU,CAAC;QAEhB,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,SAAS,EAAE,CAAC;YACrC,OAAO,CAAC,CAAC,CAAC,YAAY;QACxB,CAAC;QAED,IAAI,EAAE,CAAC;IACT,CAAC;IAED,OAAO,GAAG,CAAC,CAAC,mBAAmB;AACjC,CAAC,CAAC"}

package/dist/solve-kepler.d.ts

@@ -0,0 +1,82 @@
+import { Radians } from '@interstellar-tools/types';
+/**
+ * Solves **Kepler's Equation** for the **Eccentric Anomaly** ($E$) using an adaptive approach:
+ * - **Newton-Raphson method** for fast convergence.
+ * - **Bisection fallback** if Newton’s method fails.
+ * - **High-eccentricity solver** for extreme orbits ($e > 0.9$).
+ *
+ * ---
+ *
+ * **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 \geq 1$), a `RangeError` is thrown.
+ *
+ * 2. **Select the Best Solver:**
+ *    - **For high eccentricities ($e > 0.9$)** → Uses `solveKeplerHighEccentricity()`.
+ *    - **For moderate eccentricities ($e \leq 0.9$)** → Uses `solveKeplerNewtonRaphson()`.
+ *    - **If Newton-Raphson fails**, falls back to `solveKeplerBisection()`.
+ *
+ * 3. **Final Wrapping:**
+ *    - Ensures the solution is correctly wrapped using `wrapAngle()`.
+ *
+ * ---
+ *
+ * **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$.**
+ *
+ * ---
+ *
+ * @param {Radians} M - Mean anomaly ($M$) in **radians**.
+ * @param {number} e - Orbital eccentricity ($0 \leq e < 1$).
+ * @param {number} [maxIter=50] - Maximum number of **iterations** before fallback.
+ * @param {number} [tolerance=1e-9] - Convergence criterion for stopping the iteration.
+ * @returns {Radians} The **eccentric anomaly** ($E$) in **radians** (wrapped to $[0, 2\pi]$).
+ *
+ * @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
+ * import { solveKepler } from './solve-kepler';
+ *
+ * // 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
+ * ```ts
+ * // 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)](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)
+ * @see [RangeError](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError)
+ * @category Solve for Kepler
+ */
+export declare const solveKepler: (M: Radians, e: number, maxIter?: number, tolerance?: number) => Radians;
+//# sourceMappingURL=solve-kepler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"solve-kepler.d.ts","sourceRoot":"","sources":["../src/solve-kepler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAOpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,eAAO,MAAM,WAAW,GACtB,GAAG,OAAO,EACV,GAAG,MAAM,EACT,gBAAY,EACZ,kBAAgB,KACf,OAkBF,CAAC"}

package/dist/solve-kepler.js

@@ -0,0 +1,99 @@
+import { solveKeplerBisection } from './solve-kepler-bisection';
+import { solveKeplerHighEccentricity } from './solve-kepler-high-eccentricity';
+import { solveKeplerNewtonRaphson } from './solve-kepler-newton-raphson';
+import { wrapAngle } from './wrap-angle';
+/**
+ * Solves **Kepler's Equation** for the **Eccentric Anomaly** ($E$) using an adaptive approach:
+ * - **Newton-Raphson method** for fast convergence.
+ * - **Bisection fallback** if Newton’s method fails.
+ * - **High-eccentricity solver** for extreme orbits ($e > 0.9$).
+ *
+ * ---
+ *
+ * **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 \geq 1$), a `RangeError` is thrown.
+ *
+ * 2. **Select the Best Solver:**
+ *    - **For high eccentricities ($e > 0.9$)** → Uses `solveKeplerHighEccentricity()`.
+ *    - **For moderate eccentricities ($e \leq 0.9$)** → Uses `solveKeplerNewtonRaphson()`.
+ *    - **If Newton-Raphson fails**, falls back to `solveKeplerBisection()`.
+ *
+ * 3. **Final Wrapping:**
+ *    - Ensures the solution is correctly wrapped using `wrapAngle()`.
+ *
+ * ---
+ *
+ * **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$.**
+ *
+ * ---
+ *
+ * @param {Radians} M - Mean anomaly ($M$) in **radians**.
+ * @param {number} e - Orbital eccentricity ($0 \leq e < 1$).
+ * @param {number} [maxIter=50] - Maximum number of **iterations** before fallback.
+ * @param {number} [tolerance=1e-9] - Convergence criterion for stopping the iteration.
+ * @returns {Radians} The **eccentric anomaly** ($E$) in **radians** (wrapped to $[0, 2\pi]$).
+ *
+ * @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
+ * import { solveKepler } from './solve-kepler';
+ *
+ * // 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
+ * ```ts
+ * // 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)](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)
+ * @see [RangeError](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError)
+ * @category Solve for Kepler
+ */
+export const solveKepler = (M, e, maxIter = 50, tolerance = 1e-9) => {
+    if (e < 0 || e >= 1) {
+        throw new RangeError(`Invalid eccentricity: ${e}. Must be in range [0,1).`);
+    }
+    // **Use different solvers for high-eccentricity cases**
+    if (e > 0.9) {
+        return solveKeplerHighEccentricity(M, e, maxIter, tolerance);
+    }
+    // Use Newton-Raphson first; if it fails, fallback to bisection
+    let E = solveKeplerNewtonRaphson(M, e, maxIter, tolerance);
+    if (isNaN(E)) {
+        E = solveKeplerBisection(M, e, maxIter, tolerance);
+    }
+    return wrapAngle(E);
+};
+//# sourceMappingURL=solve-kepler.js.map

package/dist/solve-kepler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solve-kepler.js","sourceRoot":"","sources":["../src/solve-kepler.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AAC/E,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,CAAU,EACV,CAAS,EACT,OAAO,GAAG,EAAE,EACZ,SAAS,GAAG,IAAI,EACP,EAAE;IACX,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,UAAU,CAAC,yBAAyB,CAAC,2BAA2B,CAAC,CAAC;IAC9E,CAAC;IAED,wDAAwD;IACxD,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACZ,OAAO,2BAA2B,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IAC/D,CAAC;IAED,+DAA+D;IAC/D,IAAI,CAAC,GAAG,wBAAwB,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IAE3D,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACb,CAAC,GAAG,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IACrD,CAAC;IAED,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;AACtB,CAAC,CAAC"}

package/dist/true-anomaly-to-mean-anomaly.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Converts **true anomaly** ($\nu$) to **mean anomaly** ($M$) using Kepler's equation.
+ *
+ * ---
+ *
+ * **Mathematical Explanation:**
+ *
+ * In orbital mechanics, the **true anomaly** ($\nu$), the **eccentric anomaly** ($E$),
+ * and the **mean anomaly** ($M$) are related through Kepler's equation.
+ *
+ * **Step 1: Convert True Anomaly ($\nu$) to Eccentric Anomaly ($E$)**
+ * $$
+ * E = 2 \tan^{-1} \left( \sqrt{\frac{1 - e}{1 + e}} \tan\left(\frac{\nu}{2}\right) \right)
+ * $$
+ *
+ * This transformation ensures that $E$ is computed correctly **across all quadrants**,
+ * using `atan2(y, x)` instead of `atan(x)` to avoid ambiguity in angle computation.
+ *
+ * **Step 2: Convert Eccentric Anomaly ($E$) to Mean Anomaly ($M$)**
+ *
+ * Kepler’s equation states:
+ * $$
+ * M = E - e \sin(E)
+ * $$
+ *
+ * Since anomalies are periodic over **one full orbit** ($0 \leq M < 2\pi$),
+ * we apply `wrapAngle(M)` to ensure that the computed **mean anomaly remains within this range**.
+ *
+ * ---
+ *
+ * **Why Use `wrapAngle`?**
+ * - Ensures that the mean anomaly **is always wrapped within** $[0, 2\pi]$.
+ * - Corrects floating-point precision issues that may cause values slightly greater than $2\pi$.
+ * - Prevents negative anomalies by shifting them into the valid range.
+ *
+ * ---
+ *
+ * @param {number} V - **True anomaly** ($\nu$) in radians.
+ * @param {number} e - **Eccentricity** of the orbit ($0 \leq e < 1$).
+ *
+ * @returns {number} The **mean anomaly** ($M$) in radians, wrapped to the range $[0, 2\pi]$.
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError | RangeError} If the **eccentricity** ($e$) is outside the valid range $0 \leq e < 1$.
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * import { trueAnomalyToMeanAnomaly } from './true-anomaly-to-mean-anomaly';
+ *
+ * // Example 1: Standard elliptical orbit
+ * const V = Math.PI / 3; // 60 degrees in radians
+ * const e = 0.1; // Eccentricity
+ * console.log(trueAnomalyToMeanAnomaly(V, e)); // Output: Mean anomaly in radians
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Example 2: Retrograde motion handling
+ * const V_retrograde = -Math.PI / 2; // -90 degrees
+ * const e_retrograde = 0.2;
+ * console.log(trueAnomalyToMeanAnomaly(V_retrograde, e_retrograde));
+ * ```
+ *
+ * ---
+ *
+ * @see [Kepler's Equation (Wikipedia)](https://en.wikipedia.org/wiki/Kepler%27s_equation)
+ * @see [True Anomaly (Wikipedia)](https://en.wikipedia.org/wiki/True_anomaly)
+ * @see [Mean Anomaly (Wikipedia)](https://en.wikipedia.org/wiki/Mean_anomaly)
+ * @see [Orbital Eccentricity (Wikipedia)](https://en.wikipedia.org/wiki/Orbital_eccentricity)
+ * @category Anomaly
+ */
+export declare const trueAnomalyToMeanAnomaly: (V: number, e: number) => number;
+//# sourceMappingURL=true-anomaly-to-mean-anomaly.d.ts.map

package/dist/true-anomaly-to-mean-anomaly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"true-anomaly-to-mean-anomaly.d.ts","sourceRoot":"","sources":["../src/true-anomaly-to-mean-anomaly.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,eAAO,MAAM,wBAAwB,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,MAuB/D,CAAC"}

package/dist/true-anomaly-to-mean-anomaly.js

@@ -0,0 +1,91 @@
+import { wrapAngle } from './wrap-angle';
+/**
+ * Converts **true anomaly** ($\nu$) to **mean anomaly** ($M$) using Kepler's equation.
+ *
+ * ---
+ *
+ * **Mathematical Explanation:**
+ *
+ * In orbital mechanics, the **true anomaly** ($\nu$), the **eccentric anomaly** ($E$),
+ * and the **mean anomaly** ($M$) are related through Kepler's equation.
+ *
+ * **Step 1: Convert True Anomaly ($\nu$) to Eccentric Anomaly ($E$)**
+ * $$
+ * E = 2 \tan^{-1} \left( \sqrt{\frac{1 - e}{1 + e}} \tan\left(\frac{\nu}{2}\right) \right)
+ * $$
+ *
+ * This transformation ensures that $E$ is computed correctly **across all quadrants**,
+ * using `atan2(y, x)` instead of `atan(x)` to avoid ambiguity in angle computation.
+ *
+ * **Step 2: Convert Eccentric Anomaly ($E$) to Mean Anomaly ($M$)**
+ *
+ * Kepler’s equation states:
+ * $$
+ * M = E - e \sin(E)
+ * $$
+ *
+ * Since anomalies are periodic over **one full orbit** ($0 \leq M < 2\pi$),
+ * we apply `wrapAngle(M)` to ensure that the computed **mean anomaly remains within this range**.
+ *
+ * ---
+ *
+ * **Why Use `wrapAngle`?**
+ * - Ensures that the mean anomaly **is always wrapped within** $[0, 2\pi]$.
+ * - Corrects floating-point precision issues that may cause values slightly greater than $2\pi$.
+ * - Prevents negative anomalies by shifting them into the valid range.
+ *
+ * ---
+ *
+ * @param {number} V - **True anomaly** ($\nu$) in radians.
+ * @param {number} e - **Eccentricity** of the orbit ($0 \leq e < 1$).
+ *
+ * @returns {number} The **mean anomaly** ($M$) in radians, wrapped to the range $[0, 2\pi]$.
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError | RangeError} If the **eccentricity** ($e$) is outside the valid range $0 \leq e < 1$.
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * import { trueAnomalyToMeanAnomaly } from './true-anomaly-to-mean-anomaly';
+ *
+ * // Example 1: Standard elliptical orbit
+ * const V = Math.PI / 3; // 60 degrees in radians
+ * const e = 0.1; // Eccentricity
+ * console.log(trueAnomalyToMeanAnomaly(V, e)); // Output: Mean anomaly in radians
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Example 2: Retrograde motion handling
+ * const V_retrograde = -Math.PI / 2; // -90 degrees
+ * const e_retrograde = 0.2;
+ * console.log(trueAnomalyToMeanAnomaly(V_retrograde, e_retrograde));
+ * ```
+ *
+ * ---
+ *
+ * @see [Kepler's Equation (Wikipedia)](https://en.wikipedia.org/wiki/Kepler%27s_equation)
+ * @see [True Anomaly (Wikipedia)](https://en.wikipedia.org/wiki/True_anomaly)
+ * @see [Mean Anomaly (Wikipedia)](https://en.wikipedia.org/wiki/Mean_anomaly)
+ * @see [Orbital Eccentricity (Wikipedia)](https://en.wikipedia.org/wiki/Orbital_eccentricity)
+ * @category Anomaly
+ */
+export const trueAnomalyToMeanAnomaly = (V, e) => {
+    if (e < 0 || e >= 1) {
+        throw new RangeError('Eccentricity (e) must be in the range 0 ≤ e < 1 for elliptical orbits.');
+    }
+    // Compute Eccentric Anomaly (E) properly using atan2 for quadrant correctness
+    const tanHalfV = Math.tan(V / 2);
+    const factor = Math.sqrt((1 - e) / (1 + e));
+    let E = 2 * Math.atan2(tanHalfV * factor, 1);
+    // Ensure correct quadrant handling for retrograde motion
+    if (V < -Math.PI || V > Math.PI) {
+        E = wrapAngle(E + Math.PI) - Math.PI;
+    }
+    // Convert eccentric anomaly (E) to mean anomaly (M)
+    const M = E - e * Math.sin(E);
+    // Ensure M is always in the range [0, 2π]
+    return wrapAngle(M);
+};
+//# sourceMappingURL=true-anomaly-to-mean-anomaly.js.map

package/dist/true-anomaly-to-mean-anomaly.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"true-anomaly-to-mean-anomaly.js","sourceRoot":"","sources":["../src/true-anomaly-to-mean-anomaly.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE;IACvE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,UAAU,CAClB,wEAAwE,CACzE,CAAC;IACJ,CAAC;IAED,8EAA8E;IAC9E,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAE5C,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC;IAE7C,yDAAyD;IACzD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,CAAC;QAChC,CAAC,GAAG,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;IACvC,CAAC;IAED,oDAAoD;IACpD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAE9B,0CAA0C;IAC1C,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;AACtB,CAAC,CAAC"}

package/dist/wrap-angle.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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.
+ *
+ * - Uses the JavaScript remainder operator to reduce the angle:
+ *
+ * $$
+ * r \;=\; \theta \bmod \tau,\quad \tau = 2\pi
+ * $$
+ *
+ * - Because JS remainders keep the **sign of the dividend**, after the reduction:
+ *
+ * $$
+ * r \in (-\tau,\;\tau)
+ * $$
+ *
+ * - If the reduced result is numerically indistinguishable from **±τ** within small
+ * tolerances, it returns **0**:
+ *
+ * $$
+ * \text{wrap}(\theta) =
+ * \begin{cases}
+ * 0, & |r - \tau| < \varepsilon \;\lor\; |r + \tau| < \varepsilon \\
+ * r, & \text{otherwise}
+ * \end{cases}
+ * $$
+ *
+ * where \( r = \theta \bmod \tau \) and \( \varepsilon \in \{\texttt{EPSILON}, \texttt{LARGE\_EPSILON}\} \).
+ *
+ * @param angle Input angle in **radians** (any real number).
+ * @returns Wrapped angle in **radians**, guaranteed to lie in **(-τ, τ)**,
+ *          with values near **±τ** snapped to **0**.
+ *
+ * ::: info
+ *
+ *
+ * - This function **does not** force the common principal ranges **[0, τ)** or **(-π, π]**.
+ *   It merely ensures the magnitude is **< τ** while preserving sign.
+ *   If you need a principal value in **[0, τ)**, post-process via:
+ *
+ *   ```ts
+ *   const wrapToZeroTau = (θ: number) => {
+ *     const r = wrapAngle(θ);
+ *     return r < 0 ? r + TWO_PI : r;
+ *   };
+ *   ```
+ *
+ *   For **(-π, π]**:
+ *
+ *   ```ts
+ *   const wrapToMinusPiPi = (θ: number) => {
+ *     const r = wrapAngle(θ);
+ *     return r > Math.PI ? r - TWO_PI : r;
+ *   };
+ *   ```
+ *
+ * - Very small values near **0** are **not** snapped to zero by this helper;
+ *   only values near **±τ** are. If you also want to zero-out tiny magnitudes,
+ *   apply your own deadband, e.g. `Math.abs(r) < 1e-12 ? 0 : r`.
+ *
+ * :::
+ *
+ * @example
+ * ```ts
+ * // Basic reductions
+ * wrapAngle(3 * Math.PI);      // →  Math.PI
+ * wrapAngle(-3 * Math.PI);     // → -Math.PI
+ *
+ * // Exact multiples of 2π snap to 0 (within tolerance)
+ * wrapAngle(2 * Math.PI);      // → 0
+ * wrapAngle(-2 * Math.PI);     // → 0
+ *
+ * // Preserve positive values under 2π
+ * wrapAngle(1.5 * Math.PI);    // → 1.5π
+ *
+ * // Preserve negative values under 2π
+ * wrapAngle(-0.1);             // → -0.1
+ * ```
+ * @category Angle
+ */
+export declare const wrapAngle: (angle: number) => number;
+//# sourceMappingURL=wrap-angle.d.ts.map

package/dist/wrap-angle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-angle.d.ts","sourceRoot":"","sources":["../src/wrap-angle.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,MAAM,WAgBtC,CAAC"}

package/dist/wrap-angle.js

@@ -0,0 +1,97 @@
+import { TWO_PI } from '@interstellar-tools/constants';
+const EPSILON = 1e-10; // Small threshold for floating-point drift
+const LARGE_EPSILON = 1e-8; // Higher tolerance for large angles
+/**
+ * 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.
+ *
+ * - Uses the JavaScript remainder operator to reduce the angle:
+ *
+ * $$
+ * r \;=\; \theta \bmod \tau,\quad \tau = 2\pi
+ * $$
+ *
+ * - Because JS remainders keep the **sign of the dividend**, after the reduction:
+ *
+ * $$
+ * r \in (-\tau,\;\tau)
+ * $$
+ *
+ * - If the reduced result is numerically indistinguishable from **±τ** within small
+ * tolerances, it returns **0**:
+ *
+ * $$
+ * \text{wrap}(\theta) =
+ * \begin{cases}
+ * 0, & |r - \tau| < \varepsilon \;\lor\; |r + \tau| < \varepsilon \\
+ * r, & \text{otherwise}
+ * \end{cases}
+ * $$
+ *
+ * where \( r = \theta \bmod \tau \) and \( \varepsilon \in \{\texttt{EPSILON}, \texttt{LARGE\_EPSILON}\} \).
+ *
+ * @param angle Input angle in **radians** (any real number).
+ * @returns Wrapped angle in **radians**, guaranteed to lie in **(-τ, τ)**,
+ *          with values near **±τ** snapped to **0**.
+ *
+ * ::: info
+ *
+ *
+ * - This function **does not** force the common principal ranges **[0, τ)** or **(-π, π]**.
+ *   It merely ensures the magnitude is **< τ** while preserving sign.
+ *   If you need a principal value in **[0, τ)**, post-process via:
+ *
+ *   ```ts
+ *   const wrapToZeroTau = (θ: number) => {
+ *     const r = wrapAngle(θ);
+ *     return r < 0 ? r + TWO_PI : r;
+ *   };
+ *   ```
+ *
+ *   For **(-π, π]**:
+ *
+ *   ```ts
+ *   const wrapToMinusPiPi = (θ: number) => {
+ *     const r = wrapAngle(θ);
+ *     return r > Math.PI ? r - TWO_PI : r;
+ *   };
+ *   ```
+ *
+ * - Very small values near **0** are **not** snapped to zero by this helper;
+ *   only values near **±τ** are. If you also want to zero-out tiny magnitudes,
+ *   apply your own deadband, e.g. `Math.abs(r) < 1e-12 ? 0 : r`.
+ *
+ * :::
+ *
+ * @example
+ * ```ts
+ * // Basic reductions
+ * wrapAngle(3 * Math.PI);      // →  Math.PI
+ * wrapAngle(-3 * Math.PI);     // → -Math.PI
+ *
+ * // Exact multiples of 2π snap to 0 (within tolerance)
+ * wrapAngle(2 * Math.PI);      // → 0
+ * wrapAngle(-2 * Math.PI);     // → 0
+ *
+ * // Preserve positive values under 2π
+ * wrapAngle(1.5 * Math.PI);    // → 1.5π
+ *
+ * // Preserve negative values under 2π
+ * wrapAngle(-0.1);             // → -0.1
+ * ```
+ * @category Angle
+ */
+export const wrapAngle = (angle) => {
+    // Reduce angle while preserving sign
+    angle = angle % TWO_PI;
+    // Handle floating-point precision at ±2π
+    if (Math.abs(angle - TWO_PI) < EPSILON)
+        return 0;
+    if (Math.abs(angle + TWO_PI) < EPSILON)
+        return 0;
+    if (Math.abs(angle - TWO_PI) < LARGE_EPSILON ||
+        Math.abs(angle + TWO_PI) < LARGE_EPSILON)
+        return 0;
+    return angle;
+};
+//# sourceMappingURL=wrap-angle.js.map

package/dist/wrap-angle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-angle.js","sourceRoot":"","sources":["../src/wrap-angle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAEvD,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,2CAA2C;AAClE,MAAM,aAAa,GAAG,IAAI,CAAC,CAAC,oCAAoC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAa,EAAE,EAAE;IACzC,qCAAqC;IACrC,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;IAEvB,yCAAyC;IACzC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,OAAO;QAAE,OAAO,CAAC,CAAC;IAEjD,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,OAAO;QAAE,OAAO,CAAC,CAAC;IAEjD,IACE,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,aAAa;QACxC,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,aAAa;QAExC,OAAO,CAAC,CAAC;IAEX,OAAO,KAAK,CAAC;AACf,CAAC,CAAC"}