@interstellar-tools/equations 1.0.0 → 1.2.0

package/dist/categories/orbits/hyperbolic-time-of-flight.js

@@ -0,0 +1,86 @@
+import { trueToHyperbolicAnomaly } from '../anomalies/true-to-hyperbolic-anomaly.js';
+/**
+ * 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 const hyperbolicTimeOfFlight = (nu1, nu2, e, a, mu) => {
+    for (const [name, x] of [
+        ['nu1', nu1],
+        ['nu2', nu2],
+        ['e', e],
+        ['a', a],
+        ['mu', mu]
+    ]) {
+        if (!Number.isFinite(x))
+            throw new TypeError(`${name} must be a finite number. Received: ${x}`);
+    }
+    if (e <= 1)
+        throw new RangeError(`e must be > 1. Received: ${e}`);
+    if (a >= 0)
+        throw new RangeError(`a must be < 0 for a hyperbola. Received: ${a}`);
+    if (mu <= 0)
+        throw new RangeError(`mu must be > 0. Received: ${mu}`);
+    const meanAnomaly = (nu) => {
+        const F = trueToHyperbolicAnomaly(nu, e);
+        return e * Math.sinh(F) - F;
+    };
+    return Math.sqrt((-a * a * a) / mu) * (meanAnomaly(nu2) - meanAnomaly(nu1));
+};
+//# sourceMappingURL=hyperbolic-time-of-flight.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hyperbolic-time-of-flight.js","sourceRoot":"","sources":["../../../src/categories/orbits/hyperbolic-time-of-flight.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,GAAY,EACZ,GAAY,EACZ,CAAS,EACT,CAAS,EACT,EAAU,EACF,EAAE;IACV,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI;QACtB,CAAC,KAAK,EAAE,GAAG,CAAC;QACZ,CAAC,KAAK,EAAE,GAAG,CAAC;QACZ,CAAC,GAAG,EAAE,CAAC,CAAC;QACR,CAAC,GAAG,EAAE,CAAC,CAAC;QACR,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,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,4BAA4B,CAAC,EAAE,CAAC,CAAC;IAElE,IAAI,CAAC,IAAI,CAAC;QACR,MAAM,IAAI,UAAU,CAAC,4CAA4C,CAAC,EAAE,CAAC,CAAC;IAExE,IAAI,EAAE,IAAI,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,6BAA6B,EAAE,EAAE,CAAC,CAAC;IAErE,MAAM,WAAW,GAAG,CAAC,EAAW,EAAE,EAAE;QAClC,MAAM,CAAC,GAAG,uBAAuB,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAEzC,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC,CAAC;IAEF,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;AAC9E,CAAC,CAAC"}

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

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

@@ -0,0 +1,87 @@
+import { norm2pi } from '../helpers/misc.js';
+/**
+ * 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 const launchAzimuthForInclination = (lat, i) => {
+    for (const [name, v] of [
+        ['lat', lat],
+        ['i', i]
+    ]) {
+        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}`);
+    if (i < 0 || i > Math.PI)
+        throw new RangeError(`i must be in [0, π]. Received: ${i}`);
+    const sinBeta = Math.cos(i) / Math.cos(lat);
+    // Allow rounding at the edge, where i = |lat| exactly
+    const tolerance = 1e-12;
+    if (Math.abs(sinBeta) > 1 + tolerance)
+        throw new RangeError(`i can't be reached from lat: it must be in [|lat|, π - |lat|]. Received: i=${i}, lat=${lat}`);
+    const beta = Math.asin(Math.min(1, Math.max(-1, sinBeta)));
+    return {
+        northbound: norm2pi(beta),
+        southbound: norm2pi(Math.PI - beta)
+    };
+};
+//# sourceMappingURL=launch-azimuth-for-inclination.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"launch-azimuth-for-inclination.js","sourceRoot":"","sources":["../../../src/categories/orbits/launch-azimuth-for-inclination.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAS7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CACzC,GAAY,EACZ,CAAU,EACe,EAAE;IAC3B,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI;QACtB,CAAC,KAAK,EAAE,GAAG,CAAC;QACZ,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,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,EAAE,GAAG,CAAC;QAC9B,MAAM,IAAI,UAAU,CAAC,yCAAyC,GAAG,EAAE,CAAC,CAAC;IAEvE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE;QACtB,MAAM,IAAI,UAAU,CAAC,kCAAkC,CAAC,EAAE,CAAC,CAAC;IAE9D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5C,sDAAsD;IACtD,MAAM,SAAS,GAAG,KAAK,CAAC;IAExB,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,SAAS;QACnC,MAAM,IAAI,UAAU,CAClB,8EAA8E,CAAC,SAAS,GAAG,EAAE,CAC9F,CAAC;IAEJ,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAE3D,OAAO;QACL,UAAU,EAAE,OAAO,CAAC,IAAI,CAAY;QACpC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAY;KAC/C,CAAC;AACJ,CAAC,CAAC"}

package/dist/categories/orbits/rotating-launch-azimuth.d.ts

@@ -0,0 +1,49 @@
+import type { Radians } from '@interstellar-tools/types';
+/**
+ * Compute the **azimuth over the ground** for an inertial launch azimuth, on a rotating body.
+ *
+ * $$
+ * \tan\beta_\text{rot} = \frac{v \sin\beta - v_\text{rot}}{v \cos\beta}
+ * $$
+ *
+ * Where:
+ * - $ \beta $ is the inertial azimuth, clockwise from north (rad)
+ * - $ v $ is the inertial speed to reach, e.g. the orbital speed at insertion (m/s)
+ * - $ v_\text{rot} $ is the pad's eastward speed from the body's rotation (m/s)
+ *
+ * **Units**
+ * - Inputs: `azimuth` in **radians**, `v` and `vRot` in **m/s**.
+ * - Output: $ \beta_\text{rot} $ in **radians**, in [0, 2π).
+ *
+ * ::: info Notes
+ *
+ * - The pad is already moving east, so the rocket only has to add the difference: it steers a little further from east than the inertial azimuth.
+ * - Get $ v_\text{rot} $ from {@link surfaceRotationSpeed} and $ \beta $ from {@link launchAzimuthForInclination}.
+ * - Uses a flat, local approximation: good for the azimuth at launch, not for the whole ascent.
+ *
+ * :::
+ *
+ * @param azimuth - Inertial azimuth $ \beta $ in **radians**, clockwise from north (finite).
+ * @param v - Inertial speed $ v $ in **m/s** (finite, > 0).
+ * @param vRot - Eastward surface speed $ v_\text{rot} $ in **m/s** (finite).
+ * @returns Azimuth over the ground $ \beta_\text{rot} $ in **radians**, in [0, 2π).
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `v <= 0`, or the speed over the ground is zero (the target velocity equals the pad's).
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * import type { Radians } from '@interstellar-tools/types';
+ *
+ * const toRad = (deg: number) => ((deg * Math.PI) / 180) as Radians;
+ *
+ * // Due north inertially at 7.8 km/s, from a pad moving east at 409 m/s
+ * const beta = rotatingLaunchAzimuth(toRad(0), 7800, 409);
+ * // beta ≈ 357.0°: aim slightly west of north to cancel the pad's eastward speed
+ * ```
+ *
+ * @see {@link launchAzimuthForInclination}
+ * @see {@link surfaceRotationSpeed}
+ */
+export declare const rotatingLaunchAzimuth: (azimuth: Radians, v: number, vRot: number) => Radians;
+//# sourceMappingURL=rotating-launch-azimuth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rotating-launch-azimuth.d.ts","sourceRoot":"","sources":["../../../src/categories/orbits/rotating-launch-azimuth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAIzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,qBAAqB,GAChC,SAAS,OAAO,EAChB,GAAG,MAAM,EACT,MAAM,MAAM,KACX,OAqBF,CAAC"}

package/dist/categories/orbits/rotating-launch-azimuth.js

@@ -0,0 +1,65 @@
+import { norm2pi } from '../helpers/misc.js';
+/**
+ * Compute the **azimuth over the ground** for an inertial launch azimuth, on a rotating body.
+ *
+ * $$
+ * \tan\beta_\text{rot} = \frac{v \sin\beta - v_\text{rot}}{v \cos\beta}
+ * $$
+ *
+ * Where:
+ * - $ \beta $ is the inertial azimuth, clockwise from north (rad)
+ * - $ v $ is the inertial speed to reach, e.g. the orbital speed at insertion (m/s)
+ * - $ v_\text{rot} $ is the pad's eastward speed from the body's rotation (m/s)
+ *
+ * **Units**
+ * - Inputs: `azimuth` in **radians**, `v` and `vRot` in **m/s**.
+ * - Output: $ \beta_\text{rot} $ in **radians**, in [0, 2π).
+ *
+ * ::: info Notes
+ *
+ * - The pad is already moving east, so the rocket only has to add the difference: it steers a little further from east than the inertial azimuth.
+ * - Get $ v_\text{rot} $ from {@link surfaceRotationSpeed} and $ \beta $ from {@link launchAzimuthForInclination}.
+ * - Uses a flat, local approximation: good for the azimuth at launch, not for the whole ascent.
+ *
+ * :::
+ *
+ * @param azimuth - Inertial azimuth $ \beta $ in **radians**, clockwise from north (finite).
+ * @param v - Inertial speed $ v $ in **m/s** (finite, > 0).
+ * @param vRot - Eastward surface speed $ v_\text{rot} $ in **m/s** (finite).
+ * @returns Azimuth over the ground $ \beta_\text{rot} $ in **radians**, in [0, 2π).
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `v <= 0`, or the speed over the ground is zero (the target velocity equals the pad's).
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * import type { Radians } from '@interstellar-tools/types';
+ *
+ * const toRad = (deg: number) => ((deg * Math.PI) / 180) as Radians;
+ *
+ * // Due north inertially at 7.8 km/s, from a pad moving east at 409 m/s
+ * const beta = rotatingLaunchAzimuth(toRad(0), 7800, 409);
+ * // beta ≈ 357.0°: aim slightly west of north to cancel the pad's eastward speed
+ * ```
+ *
+ * @see {@link launchAzimuthForInclination}
+ * @see {@link surfaceRotationSpeed}
+ */
+export const rotatingLaunchAzimuth = (azimuth, v, vRot) => {
+    for (const [name, x] of [
+        ['azimuth', azimuth],
+        ['v', v],
+        ['vRot', vRot]
+    ]) {
+        if (!Number.isFinite(x))
+            throw new TypeError(`${name} must be a finite number. Received: ${x}`);
+    }
+    if (v <= 0)
+        throw new RangeError(`v must be > 0. Received: ${v}`);
+    const east = v * Math.sin(azimuth) - vRot;
+    const north = v * Math.cos(azimuth);
+    if (Math.hypot(east, north) <= 1e-12 * v)
+        throw new RangeError('The speed over the ground is zero, so the azimuth is undefined.');
+    return norm2pi(Math.atan2(east, north));
+};
+//# sourceMappingURL=rotating-launch-azimuth.js.map

package/dist/categories/orbits/rotating-launch-azimuth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotating-launch-azimuth.js","sourceRoot":"","sources":["../../../src/categories/orbits/rotating-launch-azimuth.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,OAAgB,EAChB,CAAS,EACT,IAAY,EACH,EAAE;IACX,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI;QACtB,CAAC,SAAS,EAAE,OAAO,CAAC;QACpB,CAAC,GAAG,EAAE,CAAC,CAAC;QACR,CAAC,MAAM,EAAE,IAAI,CAAC;KACN,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,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1C,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAEpC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;QACtC,MAAM,IAAI,UAAU,CAClB,iEAAiE,CAClE,CAAC;IAEJ,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAY,CAAC;AACrD,CAAC,CAAC"}

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

@@ -0,0 +1,82 @@
+import type { ClassicalElementsInterface, Vector3DTupleType } from '@interstellar-tools/types';
+/**
+ * Convert a **state vector** (position and velocity) to the six **classical orbital elements**.
+ *
+ * $$
+ * \mathbf h = \mathbf r \times \mathbf v, \quad
+ * \mathbf e = \frac{\mathbf v \times \mathbf h}{\mu} - \frac{\mathbf r}{r}, \quad
+ * \mathbf n = \hat{\mathbf k} \times \mathbf h, \quad
+ * a = -\frac{\mu}{2\varepsilon}, \quad
+ * \varepsilon = \frac{v^2}{2} - \frac{\mu}{r}
+ * $$
+ *
+ * $$
+ * i = \arccos\frac{h_z}{h}, \quad
+ * \Omega = \operatorname{atan2}(n_y, n_x), \quad
+ * \omega = \angle(\mathbf n, \mathbf e), \quad
+ * \nu = \angle(\mathbf e, \mathbf r)
+ * $$
+ *
+ * where each angle $ \angle $ is measured in the direction of motion, about $ \mathbf h $.
+ *
+ * **Units**
+ * - Inputs: `r` in **m**, `v` in **m/s**, `mu` in **m³/s²**.
+ * - Output: `a` in **m**, `e` dimensionless, angles in **radians**.
+ *
+ * ::: info Notes
+ *
+ * - Works for elliptic and hyperbolic orbits. A hyperbolic orbit has a negative `a`, and `nu` in [0, 2π) like the others: the incoming branch is just below 2π.
+ * - Some angles are undefined for special orbits. Below `tolerance`, the function uses these conventions, which {@link elementsToState} reverses:
+ *   - **circular** ($ e \approx 0 $): `argp = 0`, and `nu` is measured from the ascending node (the argument of latitude);
+ *   - **equatorial** ($ i \approx 0 $ or $ \pi $): `raan = 0`, and `argp` is measured from the x axis (the longitude of periapsis);
+ *   - **circular and equatorial**: `raan = argp = 0`, and `nu` is measured from the x axis (the true longitude).
+ * - The frame is whatever inertial frame `r` and `v` are given in, centred on the body with parameter `mu`; the reference plane is its xy plane.
+ *
+ * :::
+ *
+ * ::: practice Apollo 11, leaving for the Moon
+ *
+ * **e = 0.977**
+ *
+ * _From the flown state at trans-lunar injection: 6 712.6 km from Earth's centre, 10 834.3 m/s, 7.367° above the horizontal_
+ *
+ * The AS-506 flight evaluation report gives 0.97696; the inputs here are rounded. An orbit that stretched reaches far beyond the Moon, but the Moon's gravity takes over long before.
+ *
+ * ```ts
+ * const r = 6_712_602; // m
+ * const v = 10_834.3; // m/s
+ * const gamma = toRad(7.367);
+ * stateToElements(
+ *   [r, 0, 0],
+ *   [v * Math.sin(gamma), v * Math.cos(gamma), 0],
+ *   3.986004418e14
+ * ).e; // ≈ 0.97715
+ * ```
+ *
+ * :::
+ *
+ * @param r - Position vector in **m** (finite components, not zero).
+ * @param v - Velocity vector in **m/s** (finite components).
+ * @param mu - Gravitational parameter $ \mu $ in **m³/s²** (finite, > 0).
+ * @param tolerance - Below this, `e` counts as circular and $ \sin i $ as equatorial. Defaults to `1e-10`.
+ * @returns The classical orbital elements.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `mu <= 0`, `tolerance < 0`, `r` is zero, or the motion is straight up or down (no angular momentum).
+ * @group Orbits
+ *
+ * @example
+ * ```ts
+ * // Curtis, Orbital Mechanics for Engineering Students, in km and km/s
+ * const { a, e, i, raan, argp, nu } = stateToElements(
+ *   [-6045e3, -3490e3, 2500e3],
+ *   [-3.457e3, 6.618e3, 2.533e3],
+ *   398_600e9
+ * );
+ * // e ≈ 0.1712, i ≈ 153.2°, raan ≈ 255.3°, argp ≈ 20.07°, nu ≈ 28.45°
+ * ```
+ *
+ * @see {@link elementsToState}
+ * @see https://en.wikipedia.org/wiki/Orbital_elements Orbital elements
+ */
+export declare const stateToElements: (r: Vector3DTupleType, v: Vector3DTupleType, mu: number, tolerance?: number) => ClassicalElementsInterface;
+//# sourceMappingURL=state-to-elements.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state-to-elements.d.ts","sourceRoot":"","sources":["../../../src/categories/orbits/state-to-elements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAE1B,iBAAiB,EAClB,MAAM,2BAA2B,CAAC;AAInC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,eAAO,MAAM,eAAe,GAC1B,GAAG,iBAAiB,EACpB,GAAG,iBAAiB,EACpB,IAAI,MAAM,EACV,kBAAiB,KAChB,0BA6DF,CAAC"}