@interstellar-tools/equations 1.2.0 → 1.4.0

package/dist/categories/entry/terminal-velocity.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Compute the **terminal speed** of a falling body: where drag balances its weight.
+ *
+ * $$
+ * v_t = \sqrt{\frac{2\,m\,g}{\rho\, C_D\, A}}
+ * $$
+ *
+ * Where:
+ * - $ m $ is the mass (kg)
+ * - $ g $ is the local gravitational acceleration (m/s²)
+ * - $ \rho $ is the air density (kg/m³)
+ * - $ C_D $ is the drag coefficient (dimensionless)
+ * - $ A $ is the reference area (m²)
+ *
+ * **Units**
+ * - Inputs: `m` in **kg**, `g` in **m/s²**, `rho` in **kg/m³**, `Cd` dimensionless, `A` in **m²**.
+ * - Output: $ v_t $ in **m/s**.
+ *
+ * ::: info Notes
+ *
+ * - For a parachute, $ C_D $ and $ A $ are the canopy's. For a cluster, $ A $ is the total canopy area, and real clusters lose a little drag to interference between the canopies.
+ * - The density rises as the body descends, so the terminal speed falls: evaluate it at the altitude you care about, e.g. sea level for splashdown.
+ * - At $ v_t $, `atmosphericDragAcceleration` equals $ g $.
+ *
+ * :::
+ *
+ * @param m - Mass $ m $ in **kg** (finite, > 0).
+ * @param g - Gravitational acceleration $ g $ in **m/s²** (finite, > 0).
+ * @param rho - Air density $ \rho $ in **kg/m³** (finite, > 0).
+ * @param Cd - Drag coefficient $ C_D $ (finite, > 0).
+ * @param A - Reference area $ A $ in **m²** (finite, > 0).
+ * @returns Terminal speed $ v_t $ in **m/s**.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If any input is `<= 0`.
+ * @group Entry
+ *
+ * @example
+ * ```ts
+ * // A 4.9 t capsule under three 25.5 m canopies (Cd ≈ 0.8) at sea level
+ * const v = terminalVelocity(4932, 9.80665, 1.225, 0.8, 3 * Math.PI * 12.75 ** 2);
+ * // v ≈ 8.0 m/s
+ * ```
+ *
+ * @see {@link ballisticCoefficient}
+ * @see https://en.wikipedia.org/wiki/Terminal_velocity Terminal velocity
+ */
+export declare const terminalVelocity: (m: number, g: number, rho: number, Cd: number, A: number) => number;
+//# sourceMappingURL=terminal-velocity.d.ts.map

package/dist/categories/entry/terminal-velocity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-velocity.d.ts","sourceRoot":"","sources":["../../../src/categories/entry/terminal-velocity.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,gBAAgB,GAC3B,GAAG,MAAM,EACT,GAAG,MAAM,EACT,KAAK,MAAM,EACX,IAAI,MAAM,EACV,GAAG,MAAM,KACR,MAaF,CAAC"}

package/dist/categories/entry/terminal-velocity.js

@@ -0,0 +1,60 @@
+import { assertFinite, assertPositive } from './validate.js';
+/**
+ * Compute the **terminal speed** of a falling body: where drag balances its weight.
+ *
+ * $$
+ * v_t = \sqrt{\frac{2\,m\,g}{\rho\, C_D\, A}}
+ * $$
+ *
+ * Where:
+ * - $ m $ is the mass (kg)
+ * - $ g $ is the local gravitational acceleration (m/s²)
+ * - $ \rho $ is the air density (kg/m³)
+ * - $ C_D $ is the drag coefficient (dimensionless)
+ * - $ A $ is the reference area (m²)
+ *
+ * **Units**
+ * - Inputs: `m` in **kg**, `g` in **m/s²**, `rho` in **kg/m³**, `Cd` dimensionless, `A` in **m²**.
+ * - Output: $ v_t $ in **m/s**.
+ *
+ * ::: info Notes
+ *
+ * - For a parachute, $ C_D $ and $ A $ are the canopy's. For a cluster, $ A $ is the total canopy area, and real clusters lose a little drag to interference between the canopies.
+ * - The density rises as the body descends, so the terminal speed falls: evaluate it at the altitude you care about, e.g. sea level for splashdown.
+ * - At $ v_t $, `atmosphericDragAcceleration` equals $ g $.
+ *
+ * :::
+ *
+ * @param m - Mass $ m $ in **kg** (finite, > 0).
+ * @param g - Gravitational acceleration $ g $ in **m/s²** (finite, > 0).
+ * @param rho - Air density $ \rho $ in **kg/m³** (finite, > 0).
+ * @param Cd - Drag coefficient $ C_D $ (finite, > 0).
+ * @param A - Reference area $ A $ in **m²** (finite, > 0).
+ * @returns Terminal speed $ v_t $ in **m/s**.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If any input is `<= 0`.
+ * @group Entry
+ *
+ * @example
+ * ```ts
+ * // A 4.9 t capsule under three 25.5 m canopies (Cd ≈ 0.8) at sea level
+ * const v = terminalVelocity(4932, 9.80665, 1.225, 0.8, 3 * Math.PI * 12.75 ** 2);
+ * // v ≈ 8.0 m/s
+ * ```
+ *
+ * @see {@link ballisticCoefficient}
+ * @see https://en.wikipedia.org/wiki/Terminal_velocity Terminal velocity
+ */
+export const terminalVelocity = (m, g, rho, Cd, A) => {
+    const inputs = [
+        ['m', m],
+        ['g', g],
+        ['rho', rho],
+        ['Cd', Cd],
+        ['A', A]
+    ];
+    assertFinite(inputs);
+    assertPositive(inputs);
+    return Math.sqrt((2 * m * g) / (rho * Cd * A));
+};
+//# sourceMappingURL=terminal-velocity.js.map

package/dist/categories/entry/terminal-velocity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-velocity.js","sourceRoot":"","sources":["../../../src/categories/entry/terminal-velocity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,CAAS,EACT,CAAS,EACT,GAAW,EACX,EAAU,EACV,CAAS,EACD,EAAE;IACV,MAAM,MAAM,GAAG;QACb,CAAC,GAAG,EAAE,CAAC,CAAC;QACR,CAAC,GAAG,EAAE,CAAC,CAAC;QACR,CAAC,KAAK,EAAE,GAAG,CAAC;QACZ,CAAC,IAAI,EAAE,EAAE,CAAC;QACV,CAAC,GAAG,EAAE,CAAC,CAAC;KACA,CAAC;IAEX,YAAY,CAAC,MAAM,CAAC,CAAC;IACrB,cAAc,CAAC,MAAM,CAAC,CAAC;IAEvB,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC,CAAC"}

package/dist/categories/entry/validate.d.ts

@@ -0,0 +1,7 @@
+/** Throw a TypeError for each non-finite input, named as in the caller's signature. */
+export declare const assertFinite: (inputs: readonly (readonly [string, number])[]) => void;
+/** Throw a RangeError for each input that isn't strictly positive. */
+export declare const assertPositive: (inputs: readonly (readonly [string, number])[]) => void;
+/** Throw a RangeError unless the flight-path angle is a descent or climb, not level or past vertical. */
+export declare const assertFlightPathAngle: (gamma: number) => void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/categories/entry/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/categories/entry/validate.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,eAAO,MAAM,YAAY,GACvB,QAAQ,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,SAM/C,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,cAAc,GACzB,QAAQ,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,SAK/C,CAAC;AAEF,yGAAyG;AACzG,eAAO,MAAM,qBAAqB,GAAI,OAAO,MAAM,SAKlD,CAAC"}

package/dist/categories/entry/validate.js

@@ -0,0 +1,20 @@
+/** Throw a TypeError for each non-finite input, named as in the caller's signature. */
+export const assertFinite = (inputs) => {
+    for (const [name, x] of inputs) {
+        if (!Number.isFinite(x))
+            throw new TypeError(`${name} must be a finite number. Received: ${x}`);
+    }
+};
+/** Throw a RangeError for each input that isn't strictly positive. */
+export const assertPositive = (inputs) => {
+    for (const [name, x] of inputs) {
+        if (x <= 0)
+            throw new RangeError(`${name} must be > 0. Received: ${x}`);
+    }
+};
+/** Throw a RangeError unless the flight-path angle is a descent or climb, not level or past vertical. */
+export const assertFlightPathAngle = (gamma) => {
+    if (gamma === 0 || Math.abs(gamma) > Math.PI / 2)
+        throw new RangeError(`gamma must be non-zero and within [-π/2, π/2]. Received: ${gamma}`);
+};
+//# sourceMappingURL=validate.js.map

package/dist/categories/entry/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/categories/entry/validate.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,MAA8C,EAC9C,EAAE;IACF,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC;QAC/B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YACrB,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,uCAAuC,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;AACH,CAAC,CAAC;AAEF,sEAAsE;AACtE,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,MAA8C,EAC9C,EAAE;IACF,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,2BAA2B,CAAC,EAAE,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC,CAAC;AAEF,yGAAyG;AACzG,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,KAAa,EAAE,EAAE;IACrD,IAAI,KAAK,KAAK,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,CAAC;QAC9C,MAAM,IAAI,UAAU,CAClB,4DAA4D,KAAK,EAAE,CACpE,CAAC;AACN,CAAC,CAAC"}

package/dist/categories/manoeuvres/cw-two-impulse-transfer.d.ts

@@ -0,0 +1,58 @@
+import type { CwState, Vector3DTupleType } from '@interstellar-tools/types';
+export interface CwTwoImpulseTransferInterface {
+    /** First burn, at the start, in m/s (LVLH). */
+    dv1: Vector3DTupleType;
+    /** Second burn, on arrival, in m/s (LVLH). */
+    dv2: Vector3DTupleType;
+}
+/**
+ * Compute the **two burns of a Clohessy–Wiltshire rendezvous**: from a relative state to a target state in a given time.
+ *
+ * $$
+ * \mathbf v_0^+ = \Phi_{rv}^{-1}\left(\mathbf r_f - \Phi_{rr}\,\mathbf r_0\right), \quad
+ * \Delta\mathbf v_1 = \mathbf v_0^+ - \mathbf v_0, \quad
+ * \Delta\mathbf v_2 = \mathbf v_f - \left(\Phi_{vr}\,\mathbf r_0 + \Phi_{vv}\,\mathbf v_0^+\right)
+ * $$
+ *
+ * with the blocks of $ \Phi(t) $ from {@link cwStateTransition}.
+ *
+ * **Units**
+ * - Inputs: states in **m** and **m/s**, `n` in **rad/s**, `t` in **s**.
+ * - Output: both burns in **m/s**, as vectors in the LVLH frame.
+ *
+ * ::: info Notes
+ *
+ * - The first burn puts the deputy on a path that reaches the target position after `t`; the second matches the target velocity there. For a rendezvous with the chief, the target state is all zeros.
+ * - Some transfer times can't be targeted: in the orbital plane, every whole number of orbits ($ nt = 2\pi k $), and out of plane, every half orbit, where the cross-track motion returns to $ \pm z_0 $ whatever the burn. At a half orbit the cross-track burn is zero if the target is already on that path, and otherwise the function throws.
+ * - Valid near a circular reference orbit, for small separations.
+ *
+ * :::
+ *
+ * @param state0 - Deputy's relative state before the first burn `[x, y, z, xDot, yDot, zDot]` (finite).
+ * @param target - State to arrive at `[x, y, z, xDot, yDot, zDot]` (finite); all zeros to rendezvous with the chief.
+ * @param n - Mean motion of the circular reference orbit in **rad/s** (finite, > 0).
+ * @param t - Transfer time in **s** (finite, > 0).
+ * @returns The two burns `dv1` and `dv2` in **m/s**.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `n <= 0`, `t <= 0`, or the transfer time can't be targeted.
+ * @group Manoeuvres
+ *
+ * @example
+ * ```ts
+ * import type { CwState } from '@interstellar-tools/types';
+ *
+ * // 1 km behind the chief, at rest: rendezvous in a quarter of an orbit
+ * const n = 0.00113;
+ * const { dv1, dv2 } = cwTwoImpulseTransfer(
+ *   [0, -1000, 0, 0, 0, 0],
+ *   [0, 0, 0, 0, 0, 0],
+ *   n,
+ *   Math.PI / 2 / n
+ * );
+ * ```
+ *
+ * @see {@link cwPropagate}
+ * @see https://en.wikipedia.org/wiki/Clohessy%E2%80%93Wiltshire_equations Clohessy–Wiltshire equations
+ */
+export declare const cwTwoImpulseTransfer: (state0: CwState, target: CwState, n: number, t: number) => CwTwoImpulseTransferInterface;
+//# sourceMappingURL=cw-two-impulse-transfer.d.ts.map

package/dist/categories/manoeuvres/cw-two-impulse-transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cw-two-impulse-transfer.d.ts","sourceRoot":"","sources":["../../../src/categories/manoeuvres/cw-two-impulse-transfer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAK5E,MAAM,WAAW,6BAA6B;IAC5C,+CAA+C;IAC/C,GAAG,EAAE,iBAAiB,CAAC;IACvB,8CAA8C;IAC9C,GAAG,EAAE,iBAAiB,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,OAAO,EACf,QAAQ,OAAO,EACf,GAAG,MAAM,EACT,GAAG,MAAM,KACR,6BA+DF,CAAC"}

package/dist/categories/manoeuvres/cw-two-impulse-transfer.js

@@ -0,0 +1,104 @@
+import { applyMatrix3 } from '../helpers/apply-matrix-3.js';
+import { cwStateTransition } from '../orbits/cw-state-transition.js';
+/**
+ * Compute the **two burns of a Clohessy–Wiltshire rendezvous**: from a relative state to a target state in a given time.
+ *
+ * $$
+ * \mathbf v_0^+ = \Phi_{rv}^{-1}\left(\mathbf r_f - \Phi_{rr}\,\mathbf r_0\right), \quad
+ * \Delta\mathbf v_1 = \mathbf v_0^+ - \mathbf v_0, \quad
+ * \Delta\mathbf v_2 = \mathbf v_f - \left(\Phi_{vr}\,\mathbf r_0 + \Phi_{vv}\,\mathbf v_0^+\right)
+ * $$
+ *
+ * with the blocks of $ \Phi(t) $ from {@link cwStateTransition}.
+ *
+ * **Units**
+ * - Inputs: states in **m** and **m/s**, `n` in **rad/s**, `t` in **s**.
+ * - Output: both burns in **m/s**, as vectors in the LVLH frame.
+ *
+ * ::: info Notes
+ *
+ * - The first burn puts the deputy on a path that reaches the target position after `t`; the second matches the target velocity there. For a rendezvous with the chief, the target state is all zeros.
+ * - Some transfer times can't be targeted: in the orbital plane, every whole number of orbits ($ nt = 2\pi k $), and out of plane, every half orbit, where the cross-track motion returns to $ \pm z_0 $ whatever the burn. At a half orbit the cross-track burn is zero if the target is already on that path, and otherwise the function throws.
+ * - Valid near a circular reference orbit, for small separations.
+ *
+ * :::
+ *
+ * @param state0 - Deputy's relative state before the first burn `[x, y, z, xDot, yDot, zDot]` (finite).
+ * @param target - State to arrive at `[x, y, z, xDot, yDot, zDot]` (finite); all zeros to rendezvous with the chief.
+ * @param n - Mean motion of the circular reference orbit in **rad/s** (finite, > 0).
+ * @param t - Transfer time in **s** (finite, > 0).
+ * @returns The two burns `dv1` and `dv2` in **m/s**.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `n <= 0`, `t <= 0`, or the transfer time can't be targeted.
+ * @group Manoeuvres
+ *
+ * @example
+ * ```ts
+ * import type { CwState } from '@interstellar-tools/types';
+ *
+ * // 1 km behind the chief, at rest: rendezvous in a quarter of an orbit
+ * const n = 0.00113;
+ * const { dv1, dv2 } = cwTwoImpulseTransfer(
+ *   [0, -1000, 0, 0, 0, 0],
+ *   [0, 0, 0, 0, 0, 0],
+ *   n,
+ *   Math.PI / 2 / n
+ * );
+ * ```
+ *
+ * @see {@link cwPropagate}
+ * @see https://en.wikipedia.org/wiki/Clohessy%E2%80%93Wiltshire_equations Clohessy–Wiltshire equations
+ */
+export const cwTwoImpulseTransfer = (state0, target, n, t) => {
+    for (const [name, state] of [
+        ['state0', state0],
+        ['target', target]
+    ]) {
+        for (const x of state)
+            if (!Number.isFinite(x))
+                throw new TypeError(`${name} must have finite components. Received: ${x}`);
+    }
+    if (!Number.isFinite(t))
+        throw new TypeError(`t must be a finite number. Received: ${t}`);
+    if (t <= 0)
+        throw new RangeError(`t must be > 0. Received: ${t}`);
+    const { rr, rv, vr, vv } = cwStateTransition(n, t);
+    const r0 = [state0[0], state0[1], state0[2]];
+    const v0 = [state0[3], state0[4], state0[5]];
+    const fromR0 = applyMatrix3(rr, r0);
+    // Position the first burn's velocity has to cover
+    const dx = target[0] - fromR0[0];
+    const dy = target[1] - fromR0[1];
+    const dz = target[2] - fromR0[2];
+    // In-plane: invert the 2×2 block of Φrv
+    const [[a, b], [c, d]] = rv;
+    const det = a * d - b * c;
+    if (Math.abs(det) * n * n <= 1e-10)
+        throw new RangeError(`The transfer time is a whole number of orbits (nt = 2πk), which can't be targeted in the orbital plane. Received: nt=${n * t}`);
+    const xDot = (d * dx - b * dy) / det;
+    const yDot = (-c * dx + a * dy) / det;
+    // Out of plane: z(t) = c z0 + (s / n) zDot0
+    const sOverN = rv[2][2];
+    let zDot;
+    if (Math.abs(sOverN) * n > 1e-10) {
+        zDot = dz / sOverN;
+    }
+    else if (Math.abs(dz) <= 1e-9 * Math.max(1, Math.abs(target[2]))) {
+        zDot = v0[2];
+    }
+    else {
+        throw new RangeError(`At a half orbit (nt = πk) the cross-track position can't be changed. Received: nt=${n * t}`);
+    }
+    const v0Plus = [xDot, yDot, zDot];
+    const fromR = applyMatrix3(vr, r0);
+    const fromV = applyMatrix3(vv, v0Plus);
+    return {
+        dv1: [xDot - v0[0], yDot - v0[1], zDot - v0[2]],
+        dv2: [
+            target[3] - (fromR[0] + fromV[0]),
+            target[4] - (fromR[1] + fromV[1]),
+            target[5] - (fromR[2] + fromV[2])
+        ]
+    };
+};
+//# sourceMappingURL=cw-two-impulse-transfer.js.map

package/dist/categories/manoeuvres/cw-two-impulse-transfer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cw-two-impulse-transfer.js","sourceRoot":"","sources":["../../../src/categories/manoeuvres/cw-two-impulse-transfer.ts"],"names":[],"mappings":"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"}

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