@interstellar-tools/equations 1.0.0 → 1.1.0

package/dist/categories/manoeuvres/rocket-thrust.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Compute the **thrust** of a rocket engine from its exhaust, including the pressure term.
+ *
+ * $$
+ * F = \dot m\, v_e + (p_e - p_a)\, A_e
+ * $$
+ *
+ * Where:
+ * - $ \dot m $ is the mass flow rate (kg/s)
+ * - $ v_e $ is the exhaust velocity at the nozzle exit (m/s)
+ * - $ p_e $ is the pressure at the nozzle exit (Pa)
+ * - $ p_a $ is the ambient pressure (Pa), 0 in vacuum
+ * - $ A_e $ is the nozzle exit area (m²)
+ *
+ * **Units**
+ * - Inputs: `mDot` in **kg/s**, `ve` in **m/s**, `pe` and `pa` in **Pa**, `Ae` in **m²**.
+ * - Output: $ F $ in **N**.
+ *
+ * ::: info Notes
+ *
+ * - The same engine gives more thrust in vacuum than at sea level: $ p_a $ pushes back on the nozzle exit.
+ * - A nozzle with $ p_e < p_a $ is over-expanded, and the pressure term reduces the thrust.
+ * - With $ p_e = p_a $ the thrust is $ \dot m\, v_e $, and $ v_e $ equals $ I_{sp}\, g_0 $.
+ *
+ * :::
+ *
+ * @param mDot - Mass flow rate $ \dot m $ in **kg/s** (finite, >= 0).
+ * @param ve - Exhaust velocity $ v_e $ in **m/s** (finite, >= 0).
+ * @param pe - Nozzle exit pressure $ p_e $ in **Pa** (finite, >= 0).
+ * @param pa - Ambient pressure $ p_a $ in **Pa** (finite, >= 0).
+ * @param Ae - Nozzle exit area $ A_e $ in **m²** (finite, >= 0).
+ * @returns Thrust $ F $ in **N**. Can be negative for a badly over-expanded nozzle with little flow.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If any input is negative.
+ * @group Manoeuvres
+ *
+ * @example
+ * ```ts
+ * // 250 kg/s at 3000 m/s, exit at 70 kPa through a 1.2 m² nozzle
+ * const vacuum = rocketThrust(250, 3000, 70_000, 0, 1.2); // 834 000 N
+ * const seaLevel = rocketThrust(250, 3000, 70_000, 101_325, 1.2); // ≈ 712 410 N
+ * ```
+ *
+ * @see {@link massFlowRate}
+ * @see https://en.wikipedia.org/wiki/Rocket_engine_nozzle Rocket engine nozzle (thrust equation)
+ */
+export declare const rocketThrust: (mDot: number, ve: number, pe: number, pa: number, Ae: number) => number;
+//# sourceMappingURL=rocket-thrust.d.ts.map

package/dist/categories/manoeuvres/rocket-thrust.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rocket-thrust.d.ts","sourceRoot":"","sources":["../../../src/categories/manoeuvres/rocket-thrust.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,YAAY,GACvB,MAAM,MAAM,EACZ,IAAI,MAAM,EACV,IAAI,MAAM,EACV,IAAI,MAAM,EACV,IAAI,MAAM,KACT,MAeF,CAAC"}

package/dist/categories/manoeuvres/rocket-thrust.js

@@ -0,0 +1,62 @@
+/**
+ * Compute the **thrust** of a rocket engine from its exhaust, including the pressure term.
+ *
+ * $$
+ * F = \dot m\, v_e + (p_e - p_a)\, A_e
+ * $$
+ *
+ * Where:
+ * - $ \dot m $ is the mass flow rate (kg/s)
+ * - $ v_e $ is the exhaust velocity at the nozzle exit (m/s)
+ * - $ p_e $ is the pressure at the nozzle exit (Pa)
+ * - $ p_a $ is the ambient pressure (Pa), 0 in vacuum
+ * - $ A_e $ is the nozzle exit area (m²)
+ *
+ * **Units**
+ * - Inputs: `mDot` in **kg/s**, `ve` in **m/s**, `pe` and `pa` in **Pa**, `Ae` in **m²**.
+ * - Output: $ F $ in **N**.
+ *
+ * ::: info Notes
+ *
+ * - The same engine gives more thrust in vacuum than at sea level: $ p_a $ pushes back on the nozzle exit.
+ * - A nozzle with $ p_e < p_a $ is over-expanded, and the pressure term reduces the thrust.
+ * - With $ p_e = p_a $ the thrust is $ \dot m\, v_e $, and $ v_e $ equals $ I_{sp}\, g_0 $.
+ *
+ * :::
+ *
+ * @param mDot - Mass flow rate $ \dot m $ in **kg/s** (finite, >= 0).
+ * @param ve - Exhaust velocity $ v_e $ in **m/s** (finite, >= 0).
+ * @param pe - Nozzle exit pressure $ p_e $ in **Pa** (finite, >= 0).
+ * @param pa - Ambient pressure $ p_a $ in **Pa** (finite, >= 0).
+ * @param Ae - Nozzle exit area $ A_e $ in **m²** (finite, >= 0).
+ * @returns Thrust $ F $ in **N**. Can be negative for a badly over-expanded nozzle with little flow.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If any input is negative.
+ * @group Manoeuvres
+ *
+ * @example
+ * ```ts
+ * // 250 kg/s at 3000 m/s, exit at 70 kPa through a 1.2 m² nozzle
+ * const vacuum = rocketThrust(250, 3000, 70_000, 0, 1.2); // 834 000 N
+ * const seaLevel = rocketThrust(250, 3000, 70_000, 101_325, 1.2); // ≈ 712 410 N
+ * ```
+ *
+ * @see {@link massFlowRate}
+ * @see https://en.wikipedia.org/wiki/Rocket_engine_nozzle Rocket engine nozzle (thrust equation)
+ */
+export const rocketThrust = (mDot, ve, pe, pa, Ae) => {
+    for (const [name, v] of [
+        ['mDot', mDot],
+        ['ve', ve],
+        ['pe', pe],
+        ['pa', pa],
+        ['Ae', Ae]
+    ]) {
+        if (!Number.isFinite(v))
+            throw new TypeError(`${name} must be a finite number. Received: ${v}`);
+        if (v < 0)
+            throw new RangeError(`${name} must be >= 0. Received: ${v}`);
+    }
+    return mDot * ve + (pe - pa) * Ae;
+};
+//# sourceMappingURL=rocket-thrust.js.map

package/dist/categories/manoeuvres/rocket-thrust.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rocket-thrust.js","sourceRoot":"","sources":["../../../src/categories/manoeuvres/rocket-thrust.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,IAAY,EACZ,EAAU,EACV,EAAU,EACV,EAAU,EACV,EAAU,EACF,EAAE;IACV,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI;QACtB,CAAC,MAAM,EAAE,IAAI,CAAC;QACd,CAAC,IAAI,EAAE,EAAE,CAAC;QACV,CAAC,IAAI,EAAE,EAAE,CAAC;QACV,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;QAEzE,IAAI,CAAC,GAAG,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,4BAA4B,CAAC,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,OAAO,IAAI,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC;AACpC,CAAC,CAAC"}

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/inclination-from-launch-azimuth.d.ts

@@ -0,0 +1,64 @@
+import type { Radians } from '@interstellar-tools/types';
+/**
+ * Compute the **inclination** of the orbit reached by launching from a latitude on an azimuth.
+ *
+ * $$
+ * \cos i = \cos\varphi \,\sin\beta
+ * $$
+ *
+ * Where:
+ * - $ i $ is the orbit's inclination (rad)
+ * - $ \varphi $ is the geocentric latitude of the point (rad)
+ * - $ \beta $ is the inertial azimuth or heading at that point, clockwise from north (rad)
+ *
+ * **Units**
+ * - Inputs: `lat` and `azimuth` in **radians**.
+ * - Output: $ i $ in **radians**, in [0, π].
+ *
+ * ::: info Notes
+ *
+ * - `lat` is the **geocentric** latitude. Published latitudes are usually geodetic, which on Earth differ by up to 0.19°, and the inclination by about as much. Convert first (see [#186](https://github.com/phun-ky/interstellar-tools/issues/186)).
+ * - The relation holds at every point of the ground track, not only at launch: an orbit never reaches a latitude higher than its inclination.
+ * - Launching due east ($ \beta = 90° $) gives the lowest inclination a site can reach without a plane change: its own latitude.
+ * - Azimuths between 180° and 360° head west, into retrograde orbits ($ i > 90° $).
+ * - `azimuth` is inertial. A rocket's azimuth over the ground differs, because the pad is moving east; see {@link rotatingLaunchAzimuth}.
+ *
+ * :::
+ *
+ * ::: practice Apollo 11, entering Earth orbit
+ *
+ * **32.52°**
+ *
+ * _At orbit insertion: 32.497° N geocentric, heading 88.848°_
+ *
+ * The flown parking orbit was inclined 32.521°. Apollo 11 entered orbit near the northernmost point of its track, heading almost due east. With the published geodetic latitude, 32.672°, the result would be 32.69°.
+ *
+ * ```ts
+ * inclinationFromLaunchAzimuth(toRad(32.497), toRad(88.848)); // ≈ 32.52°
+ * ```
+ *
+ * :::
+ *
+ * @param lat - Geocentric latitude $ \varphi $ in **radians** (finite, in [-π/2, π/2]).
+ * @param azimuth - Inertial azimuth $ \beta $ in **radians**, clockwise from north (finite).
+ * @returns Inclination $ i $ in **radians**, in [0, π].
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `lat` is outside [-π/2, π/2].
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * import type { Radians } from '@interstellar-tools/types';
+ *
+ * const toRad = (deg: number) => ((deg * Math.PI) / 180) as Radians;
+ *
+ * // Baikonur (45.97° N), launching north-east at 63°
+ * const i = inclinationFromLaunchAzimuth(toRad(45.97), toRad(63));
+ * // i ≈ 51.7°
+ * ```
+ *
+ * @see {@link launchAzimuthForInclination}
+ * @see https://en.wikipedia.org/wiki/Launch_azimuth Launch azimuth
+ */
+export declare const inclinationFromLaunchAzimuth: (lat: Radians, azimuth: Radians) => Radians;
+//# sourceMappingURL=inclination-from-launch-azimuth.d.ts.map

package/dist/categories/orbits/inclination-from-launch-azimuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inclination-from-launch-azimuth.d.ts","sourceRoot":"","sources":["../../../src/categories/orbits/inclination-from-launch-azimuth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,eAAO,MAAM,4BAA4B,GACvC,KAAK,OAAO,EACZ,SAAS,OAAO,KACf,OAgBF,CAAC"}

package/dist/categories/orbits/inclination-from-launch-azimuth.js

@@ -0,0 +1,76 @@
+/**
+ * Compute the **inclination** of the orbit reached by launching from a latitude on an azimuth.
+ *
+ * $$
+ * \cos i = \cos\varphi \,\sin\beta
+ * $$
+ *
+ * Where:
+ * - $ i $ is the orbit's inclination (rad)
+ * - $ \varphi $ is the geocentric latitude of the point (rad)
+ * - $ \beta $ is the inertial azimuth or heading at that point, clockwise from north (rad)
+ *
+ * **Units**
+ * - Inputs: `lat` and `azimuth` in **radians**.
+ * - Output: $ i $ in **radians**, in [0, π].
+ *
+ * ::: info Notes
+ *
+ * - `lat` is the **geocentric** latitude. Published latitudes are usually geodetic, which on Earth differ by up to 0.19°, and the inclination by about as much. Convert first (see [#186](https://github.com/phun-ky/interstellar-tools/issues/186)).
+ * - The relation holds at every point of the ground track, not only at launch: an orbit never reaches a latitude higher than its inclination.
+ * - Launching due east ($ \beta = 90° $) gives the lowest inclination a site can reach without a plane change: its own latitude.
+ * - Azimuths between 180° and 360° head west, into retrograde orbits ($ i > 90° $).
+ * - `azimuth` is inertial. A rocket's azimuth over the ground differs, because the pad is moving east; see {@link rotatingLaunchAzimuth}.
+ *
+ * :::
+ *
+ * ::: practice Apollo 11, entering Earth orbit
+ *
+ * **32.52°**
+ *
+ * _At orbit insertion: 32.497° N geocentric, heading 88.848°_
+ *
+ * The flown parking orbit was inclined 32.521°. Apollo 11 entered orbit near the northernmost point of its track, heading almost due east. With the published geodetic latitude, 32.672°, the result would be 32.69°.
+ *
+ * ```ts
+ * inclinationFromLaunchAzimuth(toRad(32.497), toRad(88.848)); // ≈ 32.52°
+ * ```
+ *
+ * :::
+ *
+ * @param lat - Geocentric latitude $ \varphi $ in **radians** (finite, in [-π/2, π/2]).
+ * @param azimuth - Inertial azimuth $ \beta $ in **radians**, clockwise from north (finite).
+ * @returns Inclination $ i $ in **radians**, in [0, π].
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `lat` is outside [-π/2, π/2].
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * import type { Radians } from '@interstellar-tools/types';
+ *
+ * const toRad = (deg: number) => ((deg * Math.PI) / 180) as Radians;
+ *
+ * // Baikonur (45.97° N), launching north-east at 63°
+ * const i = inclinationFromLaunchAzimuth(toRad(45.97), toRad(63));
+ * // i ≈ 51.7°
+ * ```
+ *
+ * @see {@link launchAzimuthForInclination}
+ * @see https://en.wikipedia.org/wiki/Launch_azimuth Launch azimuth
+ */
+export const inclinationFromLaunchAzimuth = (lat, azimuth) => {
+    for (const [name, v] of [
+        ['lat', lat],
+        ['azimuth', azimuth]
+    ]) {
+        if (!Number.isFinite(v))
+            throw new TypeError(`${name} must be a finite number. Received: ${v}`);
+    }
+    if (Math.abs(lat) > Math.PI / 2)
+        throw new RangeError(`lat must be in [-π/2, π/2]. Received: ${lat}`);
+    // Clamp against rounding just outside [-1, 1]
+    const cosI = Math.min(1, Math.max(-1, Math.cos(lat) * Math.sin(azimuth)));
+    return Math.acos(cosI);
+};
+//# sourceMappingURL=inclination-from-launch-azimuth.js.map

package/dist/categories/orbits/inclination-from-launch-azimuth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inclination-from-launch-azimuth.js","sourceRoot":"","sources":["../../../src/categories/orbits/inclination-from-launch-azimuth.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAC1C,GAAY,EACZ,OAAgB,EACP,EAAE;IACX,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI;QACtB,CAAC,KAAK,EAAE,GAAG,CAAC;QACZ,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,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,CAAC;QAC7B,MAAM,IAAI,UAAU,CAAC,yCAAyC,GAAG,EAAE,CAAC,CAAC;IAEvE,8CAA8C;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAE1E,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAY,CAAC;AACpC,CAAC,CAAC"}

package/dist/categories/orbits/launch-azimuth-for-inclination.d.ts

@@ -0,0 +1,71 @@
+import type { Radians } from '@interstellar-tools/types';
+export interface LaunchAzimuthsInterface {
+    /** Azimuth for the ascending pass: heading north, in [0, π/2] or [3π/2, 2π) */
+    northbound: Radians;
+    /** Azimuth for the descending pass: heading south, in [π/2, 3π/2] */
+    southbound: Radians;
+}
+/**
+ * Compute the **inertial launch azimuths** that reach an inclination from a latitude.
+ *
+ * $$
+ * \sin\beta = \frac{\cos i}{\cos\varphi}
+ * $$
+ *
+ * Where:
+ * - $ \beta $ is the inertial azimuth, clockwise from north (rad)
+ * - $ i $ is the target inclination (rad)
+ * - $ \varphi $ is the geocentric launch latitude (rad)
+ *
+ * Two azimuths reach every reachable inclination: one heading north ($ \beta $) and one heading south ($ \pi - \beta $).
+ *
+ * **Units**
+ * - Inputs: `lat` and `i` in **radians**.
+ * - Output: both azimuths in **radians**, in [0, 2π).
+ *
+ * ::: info Notes
+ *
+ * - `lat` is the **geocentric** latitude. Published latitudes are usually geodetic, which on Earth differ by up to 0.19°, and the inclination by about as much. Convert first (see [#186](https://github.com/phun-ky/interstellar-tools/issues/186)).
+ * - A site can only reach inclinations between $ |\varphi| $ and $ \pi - |\varphi| $ directly. Anything else needs a plane change, or a dogleg during ascent.
+ * - The azimuths are inertial. Over the ground, the rocket flies a slightly different heading; see {@link rotatingLaunchAzimuth}.
+ * - At $ i = |\varphi| $ the two solutions meet, due east (or due west for retrograde orbits).
+ *
+ * :::
+ *
+ * ::: practice To the ISS from Cape Canaveral
+ *
+ * **44.9°**
+ *
+ * _Inertial azimuth from Pad 39A, 28.447° N geocentric, to an orbit inclined 51.64°_
+ *
+ * Over the ground the rocket flies 42.7°, because the pad is already moving east at 409 m/s.
+ *
+ * ```ts
+ * launchAzimuthForInclination(toRad(28.447), toRad(51.64)).northbound; // ≈ 44.9°
+ * ```
+ *
+ * :::
+ *
+ * @param lat - Geocentric launch latitude $ \varphi $ in **radians** (finite, in (-π/2, π/2)).
+ * @param i - Target inclination $ i $ in **radians** (finite, in [0, π]).
+ * @returns The northbound and southbound inertial azimuths, in **radians**.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `lat` is not in (-π/2, π/2), `i` is not in [0, π], or `i` can't be reached from `lat` (`i < |lat|` or `i > π - |lat|`).
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * import type { Radians } from '@interstellar-tools/types';
+ *
+ * const toRad = (deg: number) => ((deg * Math.PI) / 180) as Radians;
+ *
+ * // A sun-synchronous orbit (97.8°) from Vandenberg (34.7° N)
+ * const { southbound } = launchAzimuthForInclination(toRad(34.7), toRad(97.8));
+ * // southbound ≈ 189.5°: south, slightly west
+ * ```
+ *
+ * @see {@link inclinationFromLaunchAzimuth}
+ * @see https://en.wikipedia.org/wiki/Launch_azimuth Launch azimuth
+ */
+export declare const launchAzimuthForInclination: (lat: Radians, i: Radians) => LaunchAzimuthsInterface;
+//# sourceMappingURL=launch-azimuth-for-inclination.d.ts.map

package/dist/categories/orbits/launch-azimuth-for-inclination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch-azimuth-for-inclination.d.ts","sourceRoot":"","sources":["../../../src/categories/orbits/launch-azimuth-for-inclination.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAIzD,MAAM,WAAW,uBAAuB;IACtC,+EAA+E;IAC/E,UAAU,EAAE,OAAO,CAAC;IACpB,qEAAqE;IACrE,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,eAAO,MAAM,2BAA2B,GACtC,KAAK,OAAO,EACZ,GAAG,OAAO,KACT,uBA8BF,CAAC"}