@interstellar-tools/equations 1.0.0 → 1.2.0

package/dist/categories/manoeuvres/thrust-to-weight.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Compute the **thrust-to-weight ratio** of a vehicle in a gravity field.
+ *
+ * $$
+ * \frac{T}{W} = \frac{F}{m\, g}
+ * $$
+ *
+ * Where:
+ * - $ F $ is the thrust (N)
+ * - $ m $ is the vehicle's mass (kg)
+ * - $ g $ is the local gravitational acceleration (m/s²)
+ *
+ * **Units**
+ * - Inputs: `F` in **N**, `m` in **kg**, `g` in **m/s²**.
+ * - Output: dimensionless ratio.
+ *
+ * ::: info Notes
+ *
+ * - A vehicle can only lift off vertically when $ T/W > 1 $.
+ * - Use the local $ g $, e.g. $ \mu / r^2 $ for the body you're on, not standard gravity.
+ * - The ratio grows during a burn as propellant is used up; pass the current mass.
+ *
+ * :::
+ *
+ * ::: practice Apollo 11's lunar module, leaving the Moon
+ *
+ * **1.94**
+ *
+ * _Ascent stage at liftoff, in the Moon's 1.62 m/s² gravity_
+ *
+ * On Earth the same stage would manage only 0.32: too little to lift off.
+ *
+ * ```ts
+ * thrustToWeight(15_409, 4888, 1.624); // ≈ 1.94
+ * ```
+ *
+ * :::
+ *
+ * @param F - Thrust $ F $ in **N** (finite, >= 0).
+ * @param m - Mass $ m $ in **kg** (finite, > 0).
+ * @param g - Local gravitational acceleration $ g $ in **m/s²** (finite, > 0).
+ * @returns Thrust-to-weight ratio (dimensionless).
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `F < 0`, `m <= 0` or `g <= 0`.
+ * @group Manoeuvres
+ *
+ * @example
+ * ```ts
+ * // A 2000 kg lander with a 45 kN engine on Mars (g ≈ 3.71 m/s²)
+ * const tw = thrustToWeight(45_000, 2000, 3.71);
+ * // tw ≈ 6.06
+ * ```
+ *
+ * @see {@link massFlowRate}
+ */
+export declare const thrustToWeight: (F: number, m: number, g: number) => number;
+//# sourceMappingURL=thrust-to-weight.d.ts.map

package/dist/categories/manoeuvres/thrust-to-weight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thrust-to-weight.d.ts","sourceRoot":"","sources":["../../../src/categories/manoeuvres/thrust-to-weight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,cAAc,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,MAiBhE,CAAC"}

package/dist/categories/manoeuvres/thrust-to-weight.js

@@ -0,0 +1,73 @@
+/**
+ * Compute the **thrust-to-weight ratio** of a vehicle in a gravity field.
+ *
+ * $$
+ * \frac{T}{W} = \frac{F}{m\, g}
+ * $$
+ *
+ * Where:
+ * - $ F $ is the thrust (N)
+ * - $ m $ is the vehicle's mass (kg)
+ * - $ g $ is the local gravitational acceleration (m/s²)
+ *
+ * **Units**
+ * - Inputs: `F` in **N**, `m` in **kg**, `g` in **m/s²**.
+ * - Output: dimensionless ratio.
+ *
+ * ::: info Notes
+ *
+ * - A vehicle can only lift off vertically when $ T/W > 1 $.
+ * - Use the local $ g $, e.g. $ \mu / r^2 $ for the body you're on, not standard gravity.
+ * - The ratio grows during a burn as propellant is used up; pass the current mass.
+ *
+ * :::
+ *
+ * ::: practice Apollo 11's lunar module, leaving the Moon
+ *
+ * **1.94**
+ *
+ * _Ascent stage at liftoff, in the Moon's 1.62 m/s² gravity_
+ *
+ * On Earth the same stage would manage only 0.32: too little to lift off.
+ *
+ * ```ts
+ * thrustToWeight(15_409, 4888, 1.624); // ≈ 1.94
+ * ```
+ *
+ * :::
+ *
+ * @param F - Thrust $ F $ in **N** (finite, >= 0).
+ * @param m - Mass $ m $ in **kg** (finite, > 0).
+ * @param g - Local gravitational acceleration $ g $ in **m/s²** (finite, > 0).
+ * @returns Thrust-to-weight ratio (dimensionless).
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `F < 0`, `m <= 0` or `g <= 0`.
+ * @group Manoeuvres
+ *
+ * @example
+ * ```ts
+ * // A 2000 kg lander with a 45 kN engine on Mars (g ≈ 3.71 m/s²)
+ * const tw = thrustToWeight(45_000, 2000, 3.71);
+ * // tw ≈ 6.06
+ * ```
+ *
+ * @see {@link massFlowRate}
+ */
+export const thrustToWeight = (F, m, g) => {
+    for (const [name, v] of [
+        ['F', F],
+        ['m', m],
+        ['g', g]
+    ]) {
+        if (!Number.isFinite(v))
+            throw new TypeError(`${name} must be a finite number. Received: ${v}`);
+    }
+    if (F < 0)
+        throw new RangeError(`F must be >= 0. Received: ${F}`);
+    if (m <= 0)
+        throw new RangeError(`m must be > 0. Received: ${m}`);
+    if (g <= 0)
+        throw new RangeError(`g must be > 0. Received: ${g}`);
+    return F / (m * g);
+};
+//# sourceMappingURL=thrust-to-weight.js.map

package/dist/categories/manoeuvres/thrust-to-weight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thrust-to-weight.js","sourceRoot":"","sources":["../../../src/categories/manoeuvres/thrust-to-weight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,CAAS,EAAU,EAAE;IACxE,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI;QACtB,CAAC,GAAG,EAAE,CAAC,CAAC;QACR,CAAC,GAAG,EAAE,CAAC,CAAC;QACR,CAAC,GAAG,EAAE,CAAC,CAAC;KACA,EAAE,CAAC;QACX,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YACrB,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,uCAAuC,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,6BAA6B,CAAC,EAAE,CAAC,CAAC;IAElE,IAAI,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,4BAA4B,CAAC,EAAE,CAAC,CAAC;IAElE,IAAI,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,4BAA4B,CAAC,EAAE,CAAC,CAAC;IAElE,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AACrB,CAAC,CAAC"}

package/dist/categories/orbits/elements-to-state.d.ts

@@ -0,0 +1,61 @@
+import type { ClassicalElementsInterface, StateVectorInterface } from '@interstellar-tools/types';
+/**
+ * Convert the six **classical orbital elements** to a **state vector** (position and velocity).
+ *
+ * In the perifocal frame, with $ p = a(1 - e^2) $:
+ *
+ * $$
+ * \mathbf r_{PQW} = \frac{p}{1 + e\cos\nu}\begin{pmatrix}\cos\nu \\ \sin\nu \\ 0\end{pmatrix}, \quad
+ * \mathbf v_{PQW} = \sqrt{\frac{\mu}{p}}\begin{pmatrix}-\sin\nu \\ e + \cos\nu \\ 0\end{pmatrix}
+ * $$
+ *
+ * then rotated into the inertial frame:
+ *
+ * $$
+ * \mathbf r = R_3(\Omega)\,R_1(i)\,R_3(\omega)\,\mathbf r_{PQW}, \quad
+ * \mathbf v = R_3(\Omega)\,R_1(i)\,R_3(\omega)\,\mathbf v_{PQW}
+ * $$
+ *
+ * **Units**
+ * - Inputs: `a` in **m**, `e` dimensionless, angles in **radians**, `mu` in **m³/s²**.
+ * - Output: `r` in **m**, `v` in **m/s**.
+ *
+ * ::: info Notes
+ *
+ * - The inverse of {@link stateToElements}, including its conventions for circular and equatorial orbits.
+ * - Elliptic orbits need $ a > 0 $ and hyperbolic ones $ a < 0 $. A parabolic orbit ($ e = 1 $) has no finite $ a $, so it isn't supported.
+ * - On a hyperbola, only true anomalies with $ 1 + e\cos\nu > 0 $ exist: the body never reaches the asymptotes.
+ *
+ * :::
+ *
+ * @param elements - The classical orbital elements.
+ * @param mu - Gravitational parameter $ \mu $ in **m³/s²** (finite, > 0).
+ * @returns The position `r` in **m** and velocity `v` in **m/s**.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `mu <= 0`, `e < 0`, `e = 1`, `i` is outside [0, π], `a` has the wrong sign for `e`, or `nu` is beyond a hyperbola's asymptotes.
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * import type { Radians } from '@interstellar-tools/types';
+ *
+ * // A circular, equatorial orbit at 7000 km, a quarter of the way round
+ * const { r, v } = elementsToState(
+ *   {
+ *     a: 7_000_000,
+ *     e: 0,
+ *     i: 0 as Radians,
+ *     raan: 0 as Radians,
+ *     argp: 0 as Radians,
+ *     nu: (Math.PI / 2) as Radians
+ *   },
+ *   3.986004418e14
+ * );
+ * // r ≈ [0, 7 000 000, 0] m, v ≈ [-7546, 0, 0] m/s
+ * ```
+ *
+ * @see {@link stateToElements}
+ * @see https://en.wikipedia.org/wiki/Perifocal_coordinate_system Perifocal coordinate system
+ */
+export declare const elementsToState: (elements: ClassicalElementsInterface, mu: number) => StateVectorInterface;
+//# sourceMappingURL=elements-to-state.d.ts.map

package/dist/categories/orbits/elements-to-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elements-to-state.d.ts","sourceRoot":"","sources":["../../../src/categories/orbits/elements-to-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,oBAAoB,EAErB,MAAM,2BAA2B,CAAC;AAOnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,0BAA0B,EACpC,IAAI,MAAM,KACT,oBA4DF,CAAC"}

package/dist/categories/orbits/elements-to-state.js

@@ -0,0 +1,107 @@
+import { applyMatrix3 } from '../helpers/apply-matrix-3.js';
+import { matMul3 } from '../helpers/mat-mul3.js';
+import { rot1 } from '../helpers/rot-1.js';
+import { rot3 } from '../helpers/rot-3.js';
+/**
+ * Convert the six **classical orbital elements** to a **state vector** (position and velocity).
+ *
+ * In the perifocal frame, with $ p = a(1 - e^2) $:
+ *
+ * $$
+ * \mathbf r_{PQW} = \frac{p}{1 + e\cos\nu}\begin{pmatrix}\cos\nu \\ \sin\nu \\ 0\end{pmatrix}, \quad
+ * \mathbf v_{PQW} = \sqrt{\frac{\mu}{p}}\begin{pmatrix}-\sin\nu \\ e + \cos\nu \\ 0\end{pmatrix}
+ * $$
+ *
+ * then rotated into the inertial frame:
+ *
+ * $$
+ * \mathbf r = R_3(\Omega)\,R_1(i)\,R_3(\omega)\,\mathbf r_{PQW}, \quad
+ * \mathbf v = R_3(\Omega)\,R_1(i)\,R_3(\omega)\,\mathbf v_{PQW}
+ * $$
+ *
+ * **Units**
+ * - Inputs: `a` in **m**, `e` dimensionless, angles in **radians**, `mu` in **m³/s²**.
+ * - Output: `r` in **m**, `v` in **m/s**.
+ *
+ * ::: info Notes
+ *
+ * - The inverse of {@link stateToElements}, including its conventions for circular and equatorial orbits.
+ * - Elliptic orbits need $ a > 0 $ and hyperbolic ones $ a < 0 $. A parabolic orbit ($ e = 1 $) has no finite $ a $, so it isn't supported.
+ * - On a hyperbola, only true anomalies with $ 1 + e\cos\nu > 0 $ exist: the body never reaches the asymptotes.
+ *
+ * :::
+ *
+ * @param elements - The classical orbital elements.
+ * @param mu - Gravitational parameter $ \mu $ in **m³/s²** (finite, > 0).
+ * @returns The position `r` in **m** and velocity `v` in **m/s**.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `mu <= 0`, `e < 0`, `e = 1`, `i` is outside [0, π], `a` has the wrong sign for `e`, or `nu` is beyond a hyperbola's asymptotes.
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * import type { Radians } from '@interstellar-tools/types';
+ *
+ * // A circular, equatorial orbit at 7000 km, a quarter of the way round
+ * const { r, v } = elementsToState(
+ *   {
+ *     a: 7_000_000,
+ *     e: 0,
+ *     i: 0 as Radians,
+ *     raan: 0 as Radians,
+ *     argp: 0 as Radians,
+ *     nu: (Math.PI / 2) as Radians
+ *   },
+ *   3.986004418e14
+ * );
+ * // r ≈ [0, 7 000 000, 0] m, v ≈ [-7546, 0, 0] m/s
+ * ```
+ *
+ * @see {@link stateToElements}
+ * @see https://en.wikipedia.org/wiki/Perifocal_coordinate_system Perifocal coordinate system
+ */
+export const elementsToState = (elements, mu) => {
+    const { a, e, i, raan, argp, nu } = elements;
+    for (const [name, x] of [
+        ['a', a],
+        ['e', e],
+        ['i', i],
+        ['raan', raan],
+        ['argp', argp],
+        ['nu', nu],
+        ['mu', mu]
+    ]) {
+        if (!Number.isFinite(x))
+            throw new TypeError(`${name} must be a finite number. Received: ${x}`);
+    }
+    if (mu <= 0)
+        throw new RangeError(`mu must be > 0. Received: ${mu}`);
+    if (e < 0)
+        throw new RangeError(`e must be >= 0. Received: ${e}`);
+    if (Math.abs(e - 1) < 1e-12)
+        throw new RangeError('Parabolic orbits (e = 1) are not supported: they have no finite semi-major axis.');
+    if (i < 0 || i > Math.PI)
+        throw new RangeError(`i must be in [0, π]. Received: ${i}`);
+    if (e < 1 && a <= 0)
+        throw new RangeError(`a must be > 0 for an elliptic orbit. Received: a=${a}, e=${e}`);
+    if (e > 1 && a >= 0)
+        throw new RangeError(`a must be < 0 for a hyperbolic orbit. Received: a=${a}, e=${e}`);
+    const p = a * (1 - e * e);
+    const denominator = 1 + e * Math.cos(nu);
+    if (denominator <= 0)
+        throw new RangeError(`nu is beyond the hyperbola's asymptotes (1 + e cos nu <= 0). Received: nu=${nu}, e=${e}`);
+    const rPqw = [
+        (p * Math.cos(nu)) / denominator,
+        (p * Math.sin(nu)) / denominator,
+        0
+    ];
+    const speed = Math.sqrt(mu / p);
+    const vPqw = [
+        -speed * Math.sin(nu),
+        speed * (e + Math.cos(nu)),
+        0
+    ];
+    const Q = matMul3(matMul3(rot3(raan), rot1(i)), rot3(argp));
+    return { r: applyMatrix3(Q, rPqw), v: applyMatrix3(Q, vPqw) };
+};
+//# sourceMappingURL=elements-to-state.js.map

package/dist/categories/orbits/elements-to-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"elements-to-state.js","sourceRoot":"","sources":["../../../src/categories/orbits/elements-to-state.ts"],"names":[],"mappings":"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"}

package/dist/categories/orbits/hyperbolic-eccentricity.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Compute the **eccentricity of a hyperbola** from the excess speed and the periapsis distance.
+ *
+ * $$
+ * e = 1 + \frac{r_p\, v_\infty^2}{\mu}
+ * $$
+ *
+ * Where:
+ * - $ r_p $ is the periapsis distance from the body's centre (m)
+ * - $ v_\infty $ is the hyperbolic excess speed (m/s)
+ * - $ \mu $ is the body's gravitational parameter (m³/s²)
+ *
+ * **Units**
+ * - Inputs: `vInfinity` in **m/s**, `rp` in **m**, `mu` in **m³/s²**.
+ * - Output: $ e $ dimensionless, > 1.
+ *
+ * ::: info Notes
+ *
+ * - From $ r_p = a(1 - e) $ with $ a = -\mu / v_\infty^2 $.
+ * - A slow, close pass gives $ e $ just above 1, a nearly parabolic swing; a fast, distant one gives a large $ e $ and a nearly straight path.
+ * - The trajectory turns through $ 2\arcsin(1/e) $; see `gravityAssistTurningAngle`.
+ *
+ * :::
+ *
+ * ::: practice Apollo 11, arriving at the Moon
+ *
+ * **1.44**
+ *
+ * _Approach hyperbola: 1.08 km/s excess speed, closest approach 113.9 km above the surface_
+ *
+ * ```ts
+ * hyperbolicEccentricity(1080, 1_737_400 + 113_900, 4.902800118e12); // ≈ 1.440
+ * ```
+ *
+ * :::
+ *
+ * @param vInfinity - Hyperbolic excess speed $ v_\infty $ in **m/s** (finite, > 0).
+ * @param rp - Periapsis distance $ r_p $ in **m** (finite, > 0).
+ * @param mu - Gravitational parameter $ \mu $ in **m³/s²** (finite, > 0).
+ * @returns Eccentricity $ e $ (> 1).
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `vInfinity <= 0`, `rp <= 0` or `mu <= 0`.
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * // A Jupiter flyby: v∞ = 6 km/s, periapsis at 5 Jupiter radii
+ * const e = hyperbolicEccentricity(6000, 5 * 71_492e3, 1.26686534e17);
+ * // e ≈ 1.102
+ * ```
+ *
+ * @see {@link hyperbolicSemiMajorAxis}
+ * @see {@link asymptoteTrueAnomaly}
+ */
+export declare const hyperbolicEccentricity: (vInfinity: number, rp: number, mu: number) => number;
+//# sourceMappingURL=hyperbolic-eccentricity.d.ts.map

package/dist/categories/orbits/hyperbolic-eccentricity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hyperbolic-eccentricity.d.ts","sourceRoot":"","sources":["../../../src/categories/orbits/hyperbolic-eccentricity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,sBAAsB,GACjC,WAAW,MAAM,EACjB,IAAI,MAAM,EACV,IAAI,MAAM,KACT,MAkBF,CAAC"}

package/dist/categories/orbits/hyperbolic-eccentricity.js

@@ -0,0 +1,72 @@
+/**
+ * Compute the **eccentricity of a hyperbola** from the excess speed and the periapsis distance.
+ *
+ * $$
+ * e = 1 + \frac{r_p\, v_\infty^2}{\mu}
+ * $$
+ *
+ * Where:
+ * - $ r_p $ is the periapsis distance from the body's centre (m)
+ * - $ v_\infty $ is the hyperbolic excess speed (m/s)
+ * - $ \mu $ is the body's gravitational parameter (m³/s²)
+ *
+ * **Units**
+ * - Inputs: `vInfinity` in **m/s**, `rp` in **m**, `mu` in **m³/s²**.
+ * - Output: $ e $ dimensionless, > 1.
+ *
+ * ::: info Notes
+ *
+ * - From $ r_p = a(1 - e) $ with $ a = -\mu / v_\infty^2 $.
+ * - A slow, close pass gives $ e $ just above 1, a nearly parabolic swing; a fast, distant one gives a large $ e $ and a nearly straight path.
+ * - The trajectory turns through $ 2\arcsin(1/e) $; see `gravityAssistTurningAngle`.
+ *
+ * :::
+ *
+ * ::: practice Apollo 11, arriving at the Moon
+ *
+ * **1.44**
+ *
+ * _Approach hyperbola: 1.08 km/s excess speed, closest approach 113.9 km above the surface_
+ *
+ * ```ts
+ * hyperbolicEccentricity(1080, 1_737_400 + 113_900, 4.902800118e12); // ≈ 1.440
+ * ```
+ *
+ * :::
+ *
+ * @param vInfinity - Hyperbolic excess speed $ v_\infty $ in **m/s** (finite, > 0).
+ * @param rp - Periapsis distance $ r_p $ in **m** (finite, > 0).
+ * @param mu - Gravitational parameter $ \mu $ in **m³/s²** (finite, > 0).
+ * @returns Eccentricity $ e $ (> 1).
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `vInfinity <= 0`, `rp <= 0` or `mu <= 0`.
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * // A Jupiter flyby: v∞ = 6 km/s, periapsis at 5 Jupiter radii
+ * const e = hyperbolicEccentricity(6000, 5 * 71_492e3, 1.26686534e17);
+ * // e ≈ 1.102
+ * ```
+ *
+ * @see {@link hyperbolicSemiMajorAxis}
+ * @see {@link asymptoteTrueAnomaly}
+ */
+export const hyperbolicEccentricity = (vInfinity, rp, mu) => {
+    for (const [name, x] of [
+        ['vInfinity', vInfinity],
+        ['rp', rp],
+        ['mu', mu]
+    ]) {
+        if (!Number.isFinite(x))
+            throw new TypeError(`${name} must be a finite number. Received: ${x}`);
+    }
+    if (vInfinity <= 0)
+        throw new RangeError(`vInfinity must be > 0. Received: ${vInfinity}`);
+    if (rp <= 0)
+        throw new RangeError(`rp must be > 0. Received: ${rp}`);
+    if (mu <= 0)
+        throw new RangeError(`mu must be > 0. Received: ${mu}`);
+    return 1 + (rp * vInfinity * vInfinity) / mu;
+};
+//# sourceMappingURL=hyperbolic-eccentricity.js.map

package/dist/categories/orbits/hyperbolic-eccentricity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hyperbolic-eccentricity.js","sourceRoot":"","sources":["../../../src/categories/orbits/hyperbolic-eccentricity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,SAAiB,EACjB,EAAU,EACV,EAAU,EACF,EAAE;IACV,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI;QACtB,CAAC,WAAW,EAAE,SAAS,CAAC;QACxB,CAAC,IAAI,EAAE,EAAE,CAAC;QACV,CAAC,IAAI,EAAE,EAAE,CAAC;KACF,EAAE,CAAC;QACX,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YACrB,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,uCAAuC,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,SAAS,IAAI,CAAC;QAChB,MAAM,IAAI,UAAU,CAAC,oCAAoC,SAAS,EAAE,CAAC,CAAC;IAExE,IAAI,EAAE,IAAI,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,6BAA6B,EAAE,EAAE,CAAC,CAAC;IAErE,IAAI,EAAE,IAAI,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,6BAA6B,EAAE,EAAE,CAAC,CAAC;IAErE,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC;AAC/C,CAAC,CAAC"}

package/dist/categories/orbits/hyperbolic-semi-major-axis.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Compute the **semi-major axis of a hyperbola** from the hyperbolic excess speed.
+ *
+ * $$
+ * a = -\frac{\mu}{v_\infty^2}
+ * $$
+ *
+ * Where:
+ * - $ v_\infty $ is the hyperbolic excess speed: the speed left over far from the body (m/s)
+ * - $ \mu $ is the body's gravitational parameter (m³/s²)
+ *
+ * **Units**
+ * - Inputs: `vInfinity` in **m/s**, `mu` in **m³/s²**.
+ * - Output: $ a $ in **m**, negative.
+ *
+ * ::: info Notes
+ *
+ * - Negative by convention, so that vis-viva $ v^2 = \mu(2/r - 1/a) $ holds for hyperbolas too.
+ * - $ v_\infty $ comes from a speed $ v $ at distance $ r $ by energy: $ v_\infty^2 = v^2 - 2\mu/r $, or from {@link characteristicEnergyC3} as $ \sqrt{C_3} $.
+ *
+ * :::
+ *
+ * ::: practice Apollo 11, arriving at the Moon
+ *
+ * **−4 203 km**
+ *
+ * _Approach hyperbola, with 1.08 km/s left over far from the Moon_
+ *
+ * ```ts
+ * hyperbolicSemiMajorAxis(1080, 4.902800118e12); // ≈ -4 203 361 m
+ * ```
+ *
+ * :::
+ *
+ * @param vInfinity - Hyperbolic excess speed $ v_\infty $ in **m/s** (finite, > 0).
+ * @param mu - Gravitational parameter $ \mu $ in **m³/s²** (finite, > 0).
+ * @returns Semi-major axis $ a $ in **m** (negative).
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `vInfinity <= 0` or `mu <= 0`.
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * // Leaving Earth for Mars with v∞ ≈ 2.95 km/s
+ * const a = hyperbolicSemiMajorAxis(2950, 3.986004418e14);
+ * // a ≈ -45 803 km
+ * ```
+ *
+ * @see {@link hyperbolicEccentricity}
+ * @see {@link hyperbolicPeriapsisSpeed}
+ */
+export declare const hyperbolicSemiMajorAxis: (vInfinity: number, mu: number) => number;
+//# sourceMappingURL=hyperbolic-semi-major-axis.d.ts.map

package/dist/categories/orbits/hyperbolic-semi-major-axis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hyperbolic-semi-major-axis.d.ts","sourceRoot":"","sources":["../../../src/categories/orbits/hyperbolic-semi-major-axis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,eAAO,MAAM,uBAAuB,GAClC,WAAW,MAAM,EACjB,IAAI,MAAM,KACT,MAeF,CAAC"}

package/dist/categories/orbits/hyperbolic-semi-major-axis.js

@@ -0,0 +1,66 @@
+/**
+ * Compute the **semi-major axis of a hyperbola** from the hyperbolic excess speed.
+ *
+ * $$
+ * a = -\frac{\mu}{v_\infty^2}
+ * $$
+ *
+ * Where:
+ * - $ v_\infty $ is the hyperbolic excess speed: the speed left over far from the body (m/s)
+ * - $ \mu $ is the body's gravitational parameter (m³/s²)
+ *
+ * **Units**
+ * - Inputs: `vInfinity` in **m/s**, `mu` in **m³/s²**.
+ * - Output: $ a $ in **m**, negative.
+ *
+ * ::: info Notes
+ *
+ * - Negative by convention, so that vis-viva $ v^2 = \mu(2/r - 1/a) $ holds for hyperbolas too.
+ * - $ v_\infty $ comes from a speed $ v $ at distance $ r $ by energy: $ v_\infty^2 = v^2 - 2\mu/r $, or from {@link characteristicEnergyC3} as $ \sqrt{C_3} $.
+ *
+ * :::
+ *
+ * ::: practice Apollo 11, arriving at the Moon
+ *
+ * **−4 203 km**
+ *
+ * _Approach hyperbola, with 1.08 km/s left over far from the Moon_
+ *
+ * ```ts
+ * hyperbolicSemiMajorAxis(1080, 4.902800118e12); // ≈ -4 203 361 m
+ * ```
+ *
+ * :::
+ *
+ * @param vInfinity - Hyperbolic excess speed $ v_\infty $ in **m/s** (finite, > 0).
+ * @param mu - Gravitational parameter $ \mu $ in **m³/s²** (finite, > 0).
+ * @returns Semi-major axis $ a $ in **m** (negative).
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `vInfinity <= 0` or `mu <= 0`.
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * // Leaving Earth for Mars with v∞ ≈ 2.95 km/s
+ * const a = hyperbolicSemiMajorAxis(2950, 3.986004418e14);
+ * // a ≈ -45 803 km
+ * ```
+ *
+ * @see {@link hyperbolicEccentricity}
+ * @see {@link hyperbolicPeriapsisSpeed}
+ */
+export const hyperbolicSemiMajorAxis = (vInfinity, mu) => {
+    for (const [name, x] of [
+        ['vInfinity', vInfinity],
+        ['mu', mu]
+    ]) {
+        if (!Number.isFinite(x))
+            throw new TypeError(`${name} must be a finite number. Received: ${x}`);
+    }
+    if (vInfinity <= 0)
+        throw new RangeError(`vInfinity must be > 0. Received: ${vInfinity}`);
+    if (mu <= 0)
+        throw new RangeError(`mu must be > 0. Received: ${mu}`);
+    return -mu / (vInfinity * vInfinity);
+};
+//# sourceMappingURL=hyperbolic-semi-major-axis.js.map

package/dist/categories/orbits/hyperbolic-semi-major-axis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hyperbolic-semi-major-axis.js","sourceRoot":"","sources":["../../../src/categories/orbits/hyperbolic-semi-major-axis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,SAAiB,EACjB,EAAU,EACF,EAAE;IACV,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI;QACtB,CAAC,WAAW,EAAE,SAAS,CAAC;QACxB,CAAC,IAAI,EAAE,EAAE,CAAC;KACF,EAAE,CAAC;QACX,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YACrB,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,uCAAuC,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,SAAS,IAAI,CAAC;QAChB,MAAM,IAAI,UAAU,CAAC,oCAAoC,SAAS,EAAE,CAAC,CAAC;IAExE,IAAI,EAAE,IAAI,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,6BAA6B,EAAE,EAAE,CAAC,CAAC;IAErE,OAAO,CAAC,EAAE,GAAG,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;AACvC,CAAC,CAAC"}

package/dist/categories/orbits/hyperbolic-time-of-flight.d.ts

@@ -0,0 +1,64 @@
+import type { Radians } from '@interstellar-tools/types';
+/**
+ * Compute the **time of flight between two points on a hyperbola**, given by their true anomalies.
+ *
+ * $$
+ * t_2 - t_1 = \sqrt{\frac{-a^3}{\mu}}\,\Big[(e\sinh F_2 - F_2) - (e\sinh F_1 - F_1)\Big]
+ * $$
+ *
+ * with each hyperbolic anomaly $ F $ from {@link trueToHyperbolicAnomaly}.
+ *
+ * **Units**
+ * - Inputs: `nu1`, `nu2` in **radians**, `e` dimensionless, `a` in **m** (negative), `mu` in **m³/s²**.
+ * - Output: time in **s**, negative if `nu2` comes before `nu1`.
+ *
+ * ::: info Notes
+ *
+ * - Both points must lie inside the asymptotes. The incoming branch can be given as negative angles or just below 2π.
+ * - Crossing periapsis needs no special handling: $ F $ changes sign there.
+ * - To go from a time to a position, solve $ M_h = e\sinh F - F $ with {@link solveKeplerHyperbolic}, then use {@link hyperbolicToTrueAnomaly}.
+ *
+ * :::
+ *
+ * ::: practice Apollo 11, falling towards the Moon
+ *
+ * **13.8 h**
+ *
+ * _From the edge of the Moon's sphere of influence, 62 640 km out, to closest approach_
+ *
+ * The flight took 14 h 10 min from crossing into the sphere to lighting the engine for lunar orbit insertion. Patched conics leave out Earth's pull inside the sphere, one reason the two differ.
+ *
+ * ```ts
+ * const e = 1.44; // approach hyperbola
+ * const a = -4_203_000; // m
+ * const p = a * (1 - e * e);
+ * const nuSoi = -Math.acos((p / 62_640_000 - 1) / e) as Radians; // incoming
+ * hyperbolicTimeOfFlight(nuSoi, 0 as Radians, e, a, 4.902800118e12); // ≈ 49 600 s
+ * ```
+ *
+ * :::
+ *
+ * @param nu1 - True anomaly at the start $ \nu_1 $ in **radians** (finite, inside the asymptotes).
+ * @param nu2 - True anomaly at the end $ \nu_2 $ in **radians** (finite, inside the asymptotes).
+ * @param e - Eccentricity $ e $ (finite, > 1).
+ * @param a - Semi-major axis $ a $ in **m** (finite, < 0).
+ * @param mu - Gravitational parameter $ \mu $ in **m³/s²** (finite, > 0).
+ * @returns Time of flight in **s** from `nu1` to `nu2`.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `e <= 1`, `a >= 0`, `mu <= 0`, or either true anomaly is at or beyond the asymptotes.
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * import type { Radians } from '@interstellar-tools/types';
+ *
+ * // From periapsis to 90° on a hyperbola with e = 2, a = -10 000 km, around Earth
+ * const t = hyperbolicTimeOfFlight(0 as Radians, (Math.PI / 2) as Radians, 2, -10_000e3, 3.986004418e14);
+ * // t ≈ 3 401 s
+ * ```
+ *
+ * @see {@link solveKeplerHyperbolic}
+ * @see https://en.wikipedia.org/wiki/Hyperbolic_trajectory Hyperbolic trajectory
+ */
+export declare const hyperbolicTimeOfFlight: (nu1: Radians, nu2: Radians, e: number, a: number, mu: number) => number;
+//# sourceMappingURL=hyperbolic-time-of-flight.d.ts.map

package/dist/categories/orbits/hyperbolic-time-of-flight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hyperbolic-time-of-flight.d.ts","sourceRoot":"","sources":["../../../src/categories/orbits/hyperbolic-time-of-flight.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAIzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,eAAO,MAAM,sBAAsB,GACjC,KAAK,OAAO,EACZ,KAAK,OAAO,EACZ,GAAG,MAAM,EACT,GAAG,MAAM,EACT,IAAI,MAAM,KACT,MA0BF,CAAC"}