@interstellar-tools/equations 1.1.0 → 1.3.0

package/dist/categories/manoeuvres/phasing-wait-time.d.ts

@@ -0,0 +1,55 @@
+import type { Radians } from '@interstellar-tools/types';
+/**
+ * Compute how long to **wait for a phase angle**: when a target, leading a chaser on another circular orbit, will be at the angle a manoeuvre needs.
+ *
+ * The phase angle $ \theta $ is how far the target is ahead of the chaser, and it changes at the difference in mean motions:
+ *
+ * $$
+ * \dot\theta = n_\text{target} - n_\text{chaser}, \qquad
+ * t_\text{wait} = \frac{\theta_\text{required} - \theta_\text{now}}{n_\text{target} - n_\text{chaser}} \pmod{T_\text{syn}}
+ * $$
+ *
+ * returning the first time that's not negative.
+ *
+ * **Units**
+ * - Inputs: angles in **radians**, mean motions in **rad/s**.
+ * - Output: $ t_\text{wait} $ in **s**, in $ [0, T_\text{syn}) $.
+ *
+ * ::: info Notes
+ *
+ * - A chaser in a lower, faster orbit closes the gap: the phase angle shrinks.
+ * - For a Hohmann transfer to a target on a circular orbit, the required angle is $ \theta = \pi - n_\text{target}\, t_\text{transfer} $.
+ * - If the required angle is just behind, the wait is almost a whole synodic period; see {@link synodicPeriod}.
+ *
+ * :::
+ *
+ * @param thetaNow - Current phase angle, target ahead of chaser, in **radians** (finite).
+ * @param thetaRequired - Phase angle wanted, in **radians** (finite).
+ * @param nChaser - Chaser's mean motion in **rad/s** (finite, > 0).
+ * @param nTarget - Target's mean motion in **rad/s** (finite, > 0, not equal to `nChaser`).
+ * @returns Waiting time in **s**, in [0, synodic period).
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If a mean motion is `<= 0`, or both are equal (the phase never changes).
+ * @group Manoeuvres
+ *
+ * @example
+ * ```ts
+ * import type { Radians } from '@interstellar-tools/types';
+ *
+ * // Chaser 1° per orbit faster, target 10° ahead, burn when it's 4° ahead
+ * const nTarget = 0.00113;
+ * const nChaser = nTarget * (1 + 1 / 360);
+ * const t = phasingWaitTime(
+ *   ((10 * Math.PI) / 180) as Radians,
+ *   ((4 * Math.PI) / 180) as Radians,
+ *   nChaser,
+ *   nTarget
+ * );
+ * // t ≈ 6 orbits of the target
+ * ```
+ *
+ * @see {@link synodicPeriod}
+ * @see {@link hohmannTransferTime}
+ */
+export declare const phasingWaitTime: (thetaNow: Radians, thetaRequired: Radians, nChaser: number, nTarget: number) => number;
+//# sourceMappingURL=phasing-wait-time.d.ts.map

package/dist/categories/manoeuvres/phasing-wait-time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phasing-wait-time.d.ts","sourceRoot":"","sources":["../../../src/categories/manoeuvres/phasing-wait-time.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,OAAO,EACjB,eAAe,OAAO,EACtB,SAAS,MAAM,EACf,SAAS,MAAM,KACd,MA4BF,CAAC"}

package/dist/categories/manoeuvres/phasing-wait-time.js

@@ -0,0 +1,77 @@
+/**
+ * Compute how long to **wait for a phase angle**: when a target, leading a chaser on another circular orbit, will be at the angle a manoeuvre needs.
+ *
+ * The phase angle $ \theta $ is how far the target is ahead of the chaser, and it changes at the difference in mean motions:
+ *
+ * $$
+ * \dot\theta = n_\text{target} - n_\text{chaser}, \qquad
+ * t_\text{wait} = \frac{\theta_\text{required} - \theta_\text{now}}{n_\text{target} - n_\text{chaser}} \pmod{T_\text{syn}}
+ * $$
+ *
+ * returning the first time that's not negative.
+ *
+ * **Units**
+ * - Inputs: angles in **radians**, mean motions in **rad/s**.
+ * - Output: $ t_\text{wait} $ in **s**, in $ [0, T_\text{syn}) $.
+ *
+ * ::: info Notes
+ *
+ * - A chaser in a lower, faster orbit closes the gap: the phase angle shrinks.
+ * - For a Hohmann transfer to a target on a circular orbit, the required angle is $ \theta = \pi - n_\text{target}\, t_\text{transfer} $.
+ * - If the required angle is just behind, the wait is almost a whole synodic period; see {@link synodicPeriod}.
+ *
+ * :::
+ *
+ * @param thetaNow - Current phase angle, target ahead of chaser, in **radians** (finite).
+ * @param thetaRequired - Phase angle wanted, in **radians** (finite).
+ * @param nChaser - Chaser's mean motion in **rad/s** (finite, > 0).
+ * @param nTarget - Target's mean motion in **rad/s** (finite, > 0, not equal to `nChaser`).
+ * @returns Waiting time in **s**, in [0, synodic period).
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If a mean motion is `<= 0`, or both are equal (the phase never changes).
+ * @group Manoeuvres
+ *
+ * @example
+ * ```ts
+ * import type { Radians } from '@interstellar-tools/types';
+ *
+ * // Chaser 1° per orbit faster, target 10° ahead, burn when it's 4° ahead
+ * const nTarget = 0.00113;
+ * const nChaser = nTarget * (1 + 1 / 360);
+ * const t = phasingWaitTime(
+ *   ((10 * Math.PI) / 180) as Radians,
+ *   ((4 * Math.PI) / 180) as Radians,
+ *   nChaser,
+ *   nTarget
+ * );
+ * // t ≈ 6 orbits of the target
+ * ```
+ *
+ * @see {@link synodicPeriod}
+ * @see {@link hohmannTransferTime}
+ */
+export const phasingWaitTime = (thetaNow, thetaRequired, nChaser, nTarget) => {
+    for (const [name, x] of [
+        ['thetaNow', thetaNow],
+        ['thetaRequired', thetaRequired],
+        ['nChaser', nChaser],
+        ['nTarget', nTarget]
+    ]) {
+        if (!Number.isFinite(x))
+            throw new TypeError(`${name} must be a finite number. Received: ${x}`);
+    }
+    for (const [name, x] of [
+        ['nChaser', nChaser],
+        ['nTarget', nTarget]
+    ]) {
+        if (x <= 0)
+            throw new RangeError(`${name} must be > 0. Received: ${x}`);
+    }
+    if (nChaser === nTarget)
+        throw new RangeError(`nChaser and nTarget must differ: the phase angle never changes. Received: ${nChaser}`);
+    const rate = nTarget - nChaser;
+    const synodic = (2 * Math.PI) / Math.abs(rate);
+    const t = (thetaRequired - thetaNow) / rate;
+    return ((t % synodic) + synodic) % synodic;
+};
+//# sourceMappingURL=phasing-wait-time.js.map

package/dist/categories/manoeuvres/phasing-wait-time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phasing-wait-time.js","sourceRoot":"","sources":["../../../src/categories/manoeuvres/phasing-wait-time.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,QAAiB,EACjB,aAAsB,EACtB,OAAe,EACf,OAAe,EACP,EAAE;IACV,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI;QACtB,CAAC,UAAU,EAAE,QAAQ,CAAC;QACtB,CAAC,eAAe,EAAE,aAAa,CAAC;QAChC,CAAC,SAAS,EAAE,OAAO,CAAC;QACpB,CAAC,SAAS,EAAE,OAAO,CAAC;KACZ,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,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI;QACtB,CAAC,SAAS,EAAE,OAAO,CAAC;QACpB,CAAC,SAAS,EAAE,OAAO,CAAC;KACZ,EAAE,CAAC;QACX,IAAI,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,2BAA2B,CAAC,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,IAAI,OAAO,KAAK,OAAO;QACrB,MAAM,IAAI,UAAU,CAClB,6EAA6E,OAAO,EAAE,CACvF,CAAC;IAEJ,MAAM,IAAI,GAAG,OAAO,GAAG,OAAO,CAAC;IAC/B,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,CAAC,GAAG,CAAC,aAAa,GAAG,QAAQ,CAAC,GAAG,IAAI,CAAC;IAE5C,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,GAAG,OAAO,CAAC,GAAG,OAAO,CAAC;AAC7C,CAAC,CAAC"}

package/dist/categories/orbits/cw-propagate.d.ts

@@ -0,0 +1,48 @@
+import type { CwState } from '@interstellar-tools/types';
+/**
+ * **Propagate** a Clohessy–Wiltshire / Hill relative state in closed form.
+ *
+ * $$
+ * \begin{pmatrix}\mathbf r \\ \mathbf v\end{pmatrix}(t) =
+ * \begin{bmatrix}\Phi_{rr} & \Phi_{rv} \\ \Phi_{vr} & \Phi_{vv}\end{bmatrix}
+ * \begin{pmatrix}\mathbf r_0 \\ \mathbf v_0\end{pmatrix}
+ * $$
+ *
+ * with $ \Phi(t) $ from {@link cwStateTransition}.
+ *
+ * **Units**
+ * - Inputs: `state` positions in **m** and velocities in **m/s**, `n` in **rad/s**, `t` in **s**.
+ * - Output: the state at `t`, in the same units.
+ *
+ * ::: info Notes
+ *
+ * - The exact solution of the equations {@link cwHillDerivatives} gives to a numerical integrator: no step size, no accumulated error.
+ * - Same LVLH frame and `CwState` layout as `cwHillDerivatives`: `[x, y, z, xDot, yDot, zDot]`, with $ x $ radial, $ y $ along-track, $ z $ cross-track.
+ * - A state with $ \dot y_0 = -2n x_0 $ has no along-track drift: it traces a closed ellipse around the chief.
+ *
+ * :::
+ *
+ * @param state - Relative state `[x, y, z, xDot, yDot, zDot]` (finite).
+ * @param n - Mean motion of the circular reference orbit in **rad/s** (finite, > 0).
+ * @param t - Time to propagate in **s** (finite; negative goes backwards).
+ * @returns The relative state at `t`.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `n <= 0`.
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * import type { CwState } from '@interstellar-tools/types';
+ *
+ * // 100 m below the chief with no drift: back where it started after one orbit
+ * const n = 0.00113;
+ * const start: CwState = [-100, 0, 0, 0, 2 * n * 100, 0];
+ * const later = cwPropagate(start, n, (2 * Math.PI) / n);
+ * // later ≈ start
+ * ```
+ *
+ * @see {@link cwStateTransition}
+ * @see {@link cwTwoImpulseTransfer}
+ */
+export declare const cwPropagate: (state: CwState, n: number, t: number) => CwState;
+//# sourceMappingURL=cw-propagate.d.ts.map

package/dist/categories/orbits/cw-propagate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cw-propagate.d.ts","sourceRoot":"","sources":["../../../src/categories/orbits/cw-propagate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,2BAA2B,CAAC;AAM5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,OAAO,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,OAqBlE,CAAC"}

package/dist/categories/orbits/cw-propagate.js

@@ -0,0 +1,68 @@
+import { applyMatrix3 } from '../helpers/apply-matrix-3.js';
+import { cwStateTransition } from './cw-state-transition.js';
+/**
+ * **Propagate** a Clohessy–Wiltshire / Hill relative state in closed form.
+ *
+ * $$
+ * \begin{pmatrix}\mathbf r \\ \mathbf v\end{pmatrix}(t) =
+ * \begin{bmatrix}\Phi_{rr} & \Phi_{rv} \\ \Phi_{vr} & \Phi_{vv}\end{bmatrix}
+ * \begin{pmatrix}\mathbf r_0 \\ \mathbf v_0\end{pmatrix}
+ * $$
+ *
+ * with $ \Phi(t) $ from {@link cwStateTransition}.
+ *
+ * **Units**
+ * - Inputs: `state` positions in **m** and velocities in **m/s**, `n` in **rad/s**, `t` in **s**.
+ * - Output: the state at `t`, in the same units.
+ *
+ * ::: info Notes
+ *
+ * - The exact solution of the equations {@link cwHillDerivatives} gives to a numerical integrator: no step size, no accumulated error.
+ * - Same LVLH frame and `CwState` layout as `cwHillDerivatives`: `[x, y, z, xDot, yDot, zDot]`, with $ x $ radial, $ y $ along-track, $ z $ cross-track.
+ * - A state with $ \dot y_0 = -2n x_0 $ has no along-track drift: it traces a closed ellipse around the chief.
+ *
+ * :::
+ *
+ * @param state - Relative state `[x, y, z, xDot, yDot, zDot]` (finite).
+ * @param n - Mean motion of the circular reference orbit in **rad/s** (finite, > 0).
+ * @param t - Time to propagate in **s** (finite; negative goes backwards).
+ * @returns The relative state at `t`.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `n <= 0`.
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * import type { CwState } from '@interstellar-tools/types';
+ *
+ * // 100 m below the chief with no drift: back where it started after one orbit
+ * const n = 0.00113;
+ * const start: CwState = [-100, 0, 0, 0, 2 * n * 100, 0];
+ * const later = cwPropagate(start, n, (2 * Math.PI) / n);
+ * // later ≈ start
+ * ```
+ *
+ * @see {@link cwStateTransition}
+ * @see {@link cwTwoImpulseTransfer}
+ */
+export const cwPropagate = (state, n, t) => {
+    for (const x of state)
+        if (!Number.isFinite(x))
+            throw new TypeError(`state must have finite components. Received: ${x}`);
+    const { rr, rv, vr, vv } = cwStateTransition(n, t);
+    const r0 = [state[0], state[1], state[2]];
+    const v0 = [state[3], state[4], state[5]];
+    const rA = applyMatrix3(rr, r0);
+    const rB = applyMatrix3(rv, v0);
+    const vA = applyMatrix3(vr, r0);
+    const vB = applyMatrix3(vv, v0);
+    return [
+        rA[0] + rB[0],
+        rA[1] + rB[1],
+        rA[2] + rB[2],
+        vA[0] + vB[0],
+        vA[1] + vB[1],
+        vA[2] + vB[2]
+    ];
+};
+//# sourceMappingURL=cw-propagate.js.map

package/dist/categories/orbits/cw-propagate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cw-propagate.js","sourceRoot":"","sources":["../../../src/categories/orbits/cw-propagate.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAE5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAc,EAAE,CAAS,EAAE,CAAS,EAAW,EAAE;IAC3E,KAAK,MAAM,CAAC,IAAI,KAAK;QACnB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YACrB,MAAM,IAAI,SAAS,CAAC,gDAAgD,CAAC,EAAE,CAAC,CAAC;IAE7E,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACnD,MAAM,EAAE,GAAsB,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,MAAM,EAAE,GAAsB,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,MAAM,EAAE,GAAG,YAAY,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAChC,MAAM,EAAE,GAAG,YAAY,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAChC,MAAM,EAAE,GAAG,YAAY,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAChC,MAAM,EAAE,GAAG,YAAY,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAEhC,OAAO;QACL,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACb,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACb,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACb,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACb,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACb,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;KACL,CAAC;AACb,CAAC,CAAC"}

package/dist/categories/orbits/cw-state-transition.d.ts

@@ -0,0 +1,65 @@
+import type { Matrix3x3Type } from '@interstellar-tools/types';
+/**
+ * The Clohessy–Wiltshire state transition matrix $ \Phi(t) $, split into its four 3×3 blocks:
+ * $ \mathbf r(t) = \Phi_{rr}\mathbf r_0 + \Phi_{rv}\mathbf v_0 $ and $ \mathbf v(t) = \Phi_{vr}\mathbf r_0 + \Phi_{vv}\mathbf v_0 $.
+ *
+ * @group Orbits
+ */
+export interface CwStateTransitionInterface {
+    /** Position from initial position. */
+    rr: Matrix3x3Type;
+    /** Position from initial velocity (s). */
+    rv: Matrix3x3Type;
+    /** Velocity from initial position (1/s). */
+    vr: Matrix3x3Type;
+    /** Velocity from initial velocity. */
+    vv: Matrix3x3Type;
+}
+/**
+ * Compute the **Clohessy–Wiltshire state transition matrix**: the closed-form solution of the CW / Hill equations.
+ *
+ * With $ s = \sin nt $ and $ c = \cos nt $, in the LVLH frame of {@link cwHillDerivatives}
+ * ($ x $ radial, $ y $ along-track, $ z $ cross-track):
+ *
+ * $$
+ * \Phi_{rr} = \begin{bmatrix} 4 - 3c & 0 & 0 \\ 6(s - nt) & 1 & 0 \\ 0 & 0 & c \end{bmatrix}, \quad
+ * \Phi_{rv} = \frac{1}{n}\begin{bmatrix} s & 2(1 - c) & 0 \\ -2(1 - c) & 4s - 3nt & 0 \\ 0 & 0 & s \end{bmatrix}
+ * $$
+ *
+ * $$
+ * \Phi_{vr} = \begin{bmatrix} 3ns & 0 & 0 \\ 6n(c - 1) & 0 & 0 \\ 0 & 0 & -ns \end{bmatrix}, \quad
+ * \Phi_{vv} = \begin{bmatrix} c & 2s & 0 \\ -2s & 4c - 3 & 0 \\ 0 & 0 & c \end{bmatrix}
+ * $$
+ *
+ * **Units**
+ * - Inputs: `n` in **rad/s**, `t` in **s**.
+ * - Output: dimensionless blocks, except $ \Phi_{rv} $ in **s** and $ \Phi_{vr} $ in **1/s**.
+ *
+ * ::: info Notes
+ *
+ * - Valid near a **circular** reference orbit, for separations small compared with its radius. Elliptic reference orbits need other solutions (e.g. Yamanaka–Ankersen).
+ * - The $ -3nt $ terms grow without bound: a deputy slightly lower than the chief drifts ahead every orbit.
+ * - $ \Phi(0) $ is the identity, and $ \Phi(t_1 + t_2) = \Phi(t_2)\,\Phi(t_1) $.
+ * - Negative `t` propagates backwards.
+ *
+ * :::
+ *
+ * @param n - Mean motion of the circular reference orbit $ n $ in **rad/s** (finite, > 0).
+ * @param t - Time since the initial state $ t $ in **s** (finite).
+ * @returns The four 3×3 blocks of $ \Phi(t) $.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `n <= 0`.
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * // ISS-like orbit: n ≈ 0.00113 rad/s, a quarter of an orbit later
+ * const { rr, rv } = cwStateTransition(0.00113, (Math.PI / 2) / 0.00113);
+ * ```
+ *
+ * @see {@link cwPropagate}
+ * @see {@link cwTwoImpulseTransfer}
+ * @see https://en.wikipedia.org/wiki/Clohessy%E2%80%93Wiltshire_equations Clohessy–Wiltshire equations
+ */
+export declare const cwStateTransition: (n: number, t: number) => CwStateTransitionInterface;
+//# sourceMappingURL=cw-state-transition.d.ts.map

package/dist/categories/orbits/cw-state-transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cw-state-transition.d.ts","sourceRoot":"","sources":["../../../src/categories/orbits/cw-state-transition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,sCAAsC;IACtC,EAAE,EAAE,aAAa,CAAC;IAClB,0CAA0C;IAC1C,EAAE,EAAE,aAAa,CAAC;IAClB,4CAA4C;IAC5C,EAAE,EAAE,aAAa,CAAC;IAClB,sCAAsC;IACtC,EAAE,EAAE,aAAa,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,iBAAiB,GAC5B,GAAG,MAAM,EACT,GAAG,MAAM,KACR,0BAqCF,CAAC"}

package/dist/categories/orbits/cw-state-transition.js

@@ -0,0 +1,83 @@
+/**
+ * Compute the **Clohessy–Wiltshire state transition matrix**: the closed-form solution of the CW / Hill equations.
+ *
+ * With $ s = \sin nt $ and $ c = \cos nt $, in the LVLH frame of {@link cwHillDerivatives}
+ * ($ x $ radial, $ y $ along-track, $ z $ cross-track):
+ *
+ * $$
+ * \Phi_{rr} = \begin{bmatrix} 4 - 3c & 0 & 0 \\ 6(s - nt) & 1 & 0 \\ 0 & 0 & c \end{bmatrix}, \quad
+ * \Phi_{rv} = \frac{1}{n}\begin{bmatrix} s & 2(1 - c) & 0 \\ -2(1 - c) & 4s - 3nt & 0 \\ 0 & 0 & s \end{bmatrix}
+ * $$
+ *
+ * $$
+ * \Phi_{vr} = \begin{bmatrix} 3ns & 0 & 0 \\ 6n(c - 1) & 0 & 0 \\ 0 & 0 & -ns \end{bmatrix}, \quad
+ * \Phi_{vv} = \begin{bmatrix} c & 2s & 0 \\ -2s & 4c - 3 & 0 \\ 0 & 0 & c \end{bmatrix}
+ * $$
+ *
+ * **Units**
+ * - Inputs: `n` in **rad/s**, `t` in **s**.
+ * - Output: dimensionless blocks, except $ \Phi_{rv} $ in **s** and $ \Phi_{vr} $ in **1/s**.
+ *
+ * ::: info Notes
+ *
+ * - Valid near a **circular** reference orbit, for separations small compared with its radius. Elliptic reference orbits need other solutions (e.g. Yamanaka–Ankersen).
+ * - The $ -3nt $ terms grow without bound: a deputy slightly lower than the chief drifts ahead every orbit.
+ * - $ \Phi(0) $ is the identity, and $ \Phi(t_1 + t_2) = \Phi(t_2)\,\Phi(t_1) $.
+ * - Negative `t` propagates backwards.
+ *
+ * :::
+ *
+ * @param n - Mean motion of the circular reference orbit $ n $ in **rad/s** (finite, > 0).
+ * @param t - Time since the initial state $ t $ in **s** (finite).
+ * @returns The four 3×3 blocks of $ \Phi(t) $.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `n <= 0`.
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * // ISS-like orbit: n ≈ 0.00113 rad/s, a quarter of an orbit later
+ * const { rr, rv } = cwStateTransition(0.00113, (Math.PI / 2) / 0.00113);
+ * ```
+ *
+ * @see {@link cwPropagate}
+ * @see {@link cwTwoImpulseTransfer}
+ * @see https://en.wikipedia.org/wiki/Clohessy%E2%80%93Wiltshire_equations Clohessy–Wiltshire equations
+ */
+export const cwStateTransition = (n, t) => {
+    for (const [name, x] of [
+        ['n', n],
+        ['t', t]
+    ]) {
+        if (!Number.isFinite(x))
+            throw new TypeError(`${name} must be a finite number. Received: ${x}`);
+    }
+    if (n <= 0)
+        throw new RangeError(`n must be > 0. Received: ${n}`);
+    const nt = n * t;
+    const s = Math.sin(nt);
+    const c = Math.cos(nt);
+    return {
+        rr: [
+            [4 - 3 * c, 0, 0],
+            [6 * (s - nt), 1, 0],
+            [0, 0, c]
+        ],
+        rv: [
+            [s / n, (2 * (1 - c)) / n, 0],
+            [(-2 * (1 - c)) / n, (4 * s - 3 * nt) / n, 0],
+            [0, 0, s / n]
+        ],
+        vr: [
+            [3 * n * s, 0, 0],
+            [6 * n * (c - 1), 0, 0],
+            [0, 0, -n * s]
+        ],
+        vv: [
+            [c, 2 * s, 0],
+            [-2 * s, 4 * c - 3, 0],
+            [0, 0, c]
+        ]
+    };
+};
+//# sourceMappingURL=cw-state-transition.js.map

package/dist/categories/orbits/cw-state-transition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cw-state-transition.js","sourceRoot":"","sources":["../../../src/categories/orbits/cw-state-transition.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,CAAS,EACT,CAAS,EACmB,EAAE;IAC9B,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI;QACtB,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,IAAI,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,4BAA4B,CAAC,EAAE,CAAC,CAAC;IAElE,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IACjB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACvB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAEvB,OAAO;QACL,EAAE,EAAE;YACF,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACjB,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACpB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;SACV;QACD,EAAE,EAAE;YACF,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC7B,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC7C,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;SACd;QACD,EAAE,EAAE;YACF,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACjB,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACvB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;SACf;QACD,EAAE,EAAE;YACF,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACb,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACtB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;SACV;KACF,CAAC;AACJ,CAAC,CAAC"}

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"}