@interstellar-tools/equations 0.1.2 → 0.3.0

package/dist/categories/orbits/escape-speed.d.ts

@@ -0,0 +1,50 @@
+/**
+ * **Escape speed** ($ v_{\text{esc}} $) - minimum speed to escape a central body's gravity from radius ($ r $) (ignoring drag/perturbations).
+ *
+ * **Definition**
+ *
+ * $$
+ * v_{\text{esc}}=\sqrt{\frac{2\mu}{r}}
+ * $$
+ *
+ * where ($ \mu $) is the standard gravitational parameter and ($ r $) is the distance
+ * from the central body's center.
+ *
+ * **Units**
+ * - Inputs: ($ r $) in **meters (m)**, ($ \mu $) in **m³/s²**.
+ * - Output: ($ v_{\text{esc}} $) in **m/s**.
+ *
+ * ::: info
+ *
+ * - Relationship to circular speed ($ v_c $): ($ v_{\text{esc}}=\sqrt{2}\,v_c $).
+ * - This corresponds to **parabolic** specific energy (($ \varepsilon = 0 $)).
+ * - For general (non-escape) orbital speed use `visVivaSpeed(r, a, mu)`.
+ *
+ * :::
+ *
+ * @param {number} r  Radius ($ r $) (m), distance from the central body’s center (must be finite and **> 0**).
+ * @param {number} mu Gravitational parameter ($ \mu $) (m³/s²), must be finite and **≥ 0**.
+ * @returns {number} Escape speed ($ v_{\text{esc}} $) (m/s).
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error}
+ * If inputs are non-finite or out of domain.
+ *
+ * @example
+ * ```ts
+ * // Near Earth's surface (approx.)
+ * const muEarth = 3.986004418e14;     // m^3/s^2
+ * const rSurface = 6378e3;            // m
+ * const vEsc = escapeSpeed(rSurface, muEarth); // ≈ 11186 m/s
+ * ```
+ *
+ * @example
+ * ```ts
+ * // LEO ~400 km altitude: r = R_E + 400 km
+ * const muEarth = 3.986004418e14;
+ * const rLEO = 6378e3 + 400e3;
+ * const vEsc = escapeSpeed(rLEO, muEarth); // ≈ 10860 m/s
+ * ```
+ *
+ * @group Orbits
+ */
+export declare const escapeSpeed: (r: number, mu: number) => number;
+//# sourceMappingURL=escape-speed.d.ts.map

package/dist/categories/orbits/escape-speed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-speed.d.ts","sourceRoot":"","sources":["../../../src/categories/orbits/escape-speed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,WAAW,GAAI,GAAG,MAAM,EAAE,IAAI,MAAM,KAAG,MAUnD,CAAC"}

package/dist/categories/orbits/escape-speed.js

@@ -0,0 +1,58 @@
+/**
+ * **Escape speed** ($ v_{\text{esc}} $) - minimum speed to escape a central body's gravity from radius ($ r $) (ignoring drag/perturbations).
+ *
+ * **Definition**
+ *
+ * $$
+ * v_{\text{esc}}=\sqrt{\frac{2\mu}{r}}
+ * $$
+ *
+ * where ($ \mu $) is the standard gravitational parameter and ($ r $) is the distance
+ * from the central body's center.
+ *
+ * **Units**
+ * - Inputs: ($ r $) in **meters (m)**, ($ \mu $) in **m³/s²**.
+ * - Output: ($ v_{\text{esc}} $) in **m/s**.
+ *
+ * ::: info
+ *
+ * - Relationship to circular speed ($ v_c $): ($ v_{\text{esc}}=\sqrt{2}\,v_c $).
+ * - This corresponds to **parabolic** specific energy (($ \varepsilon = 0 $)).
+ * - For general (non-escape) orbital speed use `visVivaSpeed(r, a, mu)`.
+ *
+ * :::
+ *
+ * @param {number} r  Radius ($ r $) (m), distance from the central body’s center (must be finite and **> 0**).
+ * @param {number} mu Gravitational parameter ($ \mu $) (m³/s²), must be finite and **≥ 0**.
+ * @returns {number} Escape speed ($ v_{\text{esc}} $) (m/s).
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error}
+ * If inputs are non-finite or out of domain.
+ *
+ * @example
+ * ```ts
+ * // Near Earth's surface (approx.)
+ * const muEarth = 3.986004418e14;     // m^3/s^2
+ * const rSurface = 6378e3;            // m
+ * const vEsc = escapeSpeed(rSurface, muEarth); // ≈ 11186 m/s
+ * ```
+ *
+ * @example
+ * ```ts
+ * // LEO ~400 km altitude: r = R_E + 400 km
+ * const muEarth = 3.986004418e14;
+ * const rLEO = 6378e3 + 400e3;
+ * const vEsc = escapeSpeed(rLEO, muEarth); // ≈ 10860 m/s
+ * ```
+ *
+ * @group Orbits
+ */
+export const escapeSpeed = (r, mu) => {
+    if (!Number.isFinite(r) || r <= 0) {
+        throw new Error('r must be a finite, positive number (m).');
+    }
+    if (!Number.isFinite(mu) || mu < 0) {
+        throw new Error('mu must be a finite, non-negative number (m^3/s^2).');
+    }
+    return Math.sqrt((2 * mu) / r);
+};
+//# sourceMappingURL=escape-speed.js.map

package/dist/categories/orbits/escape-speed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-speed.js","sourceRoot":"","sources":["../../../src/categories/orbits/escape-speed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAS,EAAE,EAAU,EAAU,EAAE;IAC3D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IAED,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC,CAAC"}

package/dist/categories/orbits/kepler-period.d.ts

@@ -0,0 +1,45 @@
+/**
+ * **Kepler's 3rd law** - orbital period ($ T $) from semi-major axis ($ a $) and gravitational parameter ($ \mu $).
+ *
+ * **Definition**
+ *
+ * $$
+ * T = 2\pi \sqrt{\frac{a^3}{\mu}}
+ * $$
+ *
+ * **Units**
+ * - Inputs: ($ a $) in **meters (m)**, ($ \mu $) in **m³/s²**.
+ * - Output: ($ T $) in **seconds (s)**.
+ *
+ * ::: info
+ *
+ * - Valid for **Keplerian (two-body) bound orbits** with ($ a>0 $) (ellipses). Not defined for parabolic/hyperbolic trajectories.
+ * - ($ \mu $) is the **standard gravitational parameter** of the central body (e.g., Earth ($ \approx 3.986004418\times10^{14}\ \text{m}^3/\text{s}^2 $)).
+ *
+ * :::
+ *
+ * @param {number} a  Semi-major axis (m), must be finite and **> 0**.
+ * @param {number} mu Gravitational parameter (m³/s²), must be finite and **> 0**.
+ * @returns {number} Orbital period ($ T $) (s).
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If inputs are non-finite or out of domain.
+ *
+ * @example
+ * ```ts
+ * // GEO: a ≈ 42,164 km → T ≈ 86,164 s (one sidereal day)
+ * const a = 42164e3;                 // m
+ * const muEarth = 3.986004418e14;    // m^3/s^2
+ * const T = keplerPeriod(a, muEarth); // ≈ 86164 s
+ * ```
+ *
+ * @example
+ * ```ts
+ * // LEO-ish circular: a ≈ Earth radius + 400 km
+ * const a = 6378e3 + 400e3;          // m
+ * const muEarth = 3.986004418e14;    // m^3/s^2
+ * const T = keplerPeriod(a, muEarth); // ≈ 5550 s (~92.5 min)
+ * ```
+ *
+ * @group Orbits
+ */
+export declare const keplerPeriod: (a: number, mu: number) => number;
+//# sourceMappingURL=kepler-period.d.ts.map

package/dist/categories/orbits/kepler-period.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kepler-period.d.ts","sourceRoot":"","sources":["../../../src/categories/orbits/kepler-period.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,MAAM,EAAE,IAAI,MAAM,KAAG,MAYpD,CAAC"}

package/dist/categories/orbits/kepler-period.js

@@ -0,0 +1,54 @@
+/**
+ * **Kepler's 3rd law** - orbital period ($ T $) from semi-major axis ($ a $) and gravitational parameter ($ \mu $).
+ *
+ * **Definition**
+ *
+ * $$
+ * T = 2\pi \sqrt{\frac{a^3}{\mu}}
+ * $$
+ *
+ * **Units**
+ * - Inputs: ($ a $) in **meters (m)**, ($ \mu $) in **m³/s²**.
+ * - Output: ($ T $) in **seconds (s)**.
+ *
+ * ::: info
+ *
+ * - Valid for **Keplerian (two-body) bound orbits** with ($ a>0 $) (ellipses). Not defined for parabolic/hyperbolic trajectories.
+ * - ($ \mu $) is the **standard gravitational parameter** of the central body (e.g., Earth ($ \approx 3.986004418\times10^{14}\ \text{m}^3/\text{s}^2 $)).
+ *
+ * :::
+ *
+ * @param {number} a  Semi-major axis (m), must be finite and **> 0**.
+ * @param {number} mu Gravitational parameter (m³/s²), must be finite and **> 0**.
+ * @returns {number} Orbital period ($ T $) (s).
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If inputs are non-finite or out of domain.
+ *
+ * @example
+ * ```ts
+ * // GEO: a ≈ 42,164 km → T ≈ 86,164 s (one sidereal day)
+ * const a = 42164e3;                 // m
+ * const muEarth = 3.986004418e14;    // m^3/s^2
+ * const T = keplerPeriod(a, muEarth); // ≈ 86164 s
+ * ```
+ *
+ * @example
+ * ```ts
+ * // LEO-ish circular: a ≈ Earth radius + 400 km
+ * const a = 6378e3 + 400e3;          // m
+ * const muEarth = 3.986004418e14;    // m^3/s^2
+ * const T = keplerPeriod(a, muEarth); // ≈ 5550 s (~92.5 min)
+ * ```
+ *
+ * @group Orbits
+ */
+export const keplerPeriod = (a, mu) => {
+    if (!Number.isFinite(a) || a <= 0) {
+        throw new Error('a must be a finite, positive number (meters).');
+    }
+    if (!Number.isFinite(mu) || mu <= 0) {
+        throw new Error('mu must be a finite, positive number (m^3/s^2).');
+    }
+    const a3 = a * a * a; // a^3
+    return 2 * Math.PI * Math.sqrt(a3 / mu);
+};
+//# sourceMappingURL=kepler-period.js.map

package/dist/categories/orbits/kepler-period.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kepler-period.js","sourceRoot":"","sources":["../../../src/categories/orbits/kepler-period.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAS,EAAE,EAAU,EAAU,EAAE;IAC5D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM;IAE5B,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;AAC1C,CAAC,CAAC"}

package/dist/categories/orbits/peri-apoapsis-radii.d.ts

@@ -0,0 +1,46 @@
+import { PeriApoRadiiType } from '@interstellar-tools/types';
+/**
+ * **Peri/apoapsis radii** from semi-major axis ($ a $) and eccentricity ($ e $).
+ *
+ * **Definitions**
+ *
+ * $$
+ * r_p = a(1-e),\qquad r_a = a(1+e)
+ * $$
+ *
+ * **Conic validity**
+ * - **Elliptic / circular**: ($ a>0,\; 0\le e<1 $) → ($ r_p>0 $) and ($ r_a>0 $).
+ * - **Hyperbolic**: ($ a<0,\; e>1 $) → ($ r_p = a(1-e) = |a|(e-1) > 0 $), **no apoapsis** (unbounded), so ($ r_a = null $).
+ * - **Parabolic**: ($ e=1 $) is **not** defined with finite ($ a $). Use the parabolic form (e.g. ($ r_p = \tfrac{p}{2} $)) or state vectors.
+ *
+ * **Units**
+ * - Inputs: ($ a $) in **meters (m)**, ($ e $) dimensionless.
+ * - Output: ($ r_p, r_a $) in **meters (m)**.
+ *
+ * @param {number} a Semi-major axis ($ a $) (m). Must be finite and **≠ 0**.
+ * @param {number} e Eccentricity ($ e $) (dimensionless). Must be finite and **≥ 0**.
+ * @returns {{ rp: number; ra: number | null }} Object with periapsis `rp` and apoapsis `ra` (or `null` if undefined for hyperbolic).
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error}
+ * If inputs are invalid or the ($ (a,e) $) pair does not correspond to an ellipse/circle or hyperbola with finite ($ a $).
+ *
+ * @example
+ * ```ts
+ * // Elliptic example (LEO-like)
+ * const a = 7000e3;  // m
+ * const e = 0.01;
+ * const { rp, ra } = periApoapsisRadii(a, e); // rp ≈ 6930 km, ra ≈ 7070 km
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Hyperbolic flyby (no apoapsis)
+ * const a = -50_000e3; // m
+ * const e = 1.2;
+ * const { rp, ra } = periApoapsisRadii(a, e); // rp = |a|(e-1) = 10,000 km, ra = null
+ * ```
+ *
+ * @group Orbits
+ */
+export declare const periApoapsisRadii: (a: number, e: number) => PeriApoRadiiType;
+//# sourceMappingURL=peri-apoapsis-radii.d.ts.map

package/dist/categories/orbits/peri-apoapsis-radii.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peri-apoapsis-radii.d.ts","sourceRoot":"","sources":["../../../src/categories/orbits/peri-apoapsis-radii.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,eAAO,MAAM,iBAAiB,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,gBAsDxD,CAAC"}

package/dist/categories/orbits/peri-apoapsis-radii.js

@@ -0,0 +1,85 @@
+/* node:coverage disable */
+/**
+ * **Peri/apoapsis radii** from semi-major axis ($ a $) and eccentricity ($ e $).
+ *
+ * **Definitions**
+ *
+ * $$
+ * r_p = a(1-e),\qquad r_a = a(1+e)
+ * $$
+ *
+ * **Conic validity**
+ * - **Elliptic / circular**: ($ a>0,\; 0\le e<1 $) → ($ r_p>0 $) and ($ r_a>0 $).
+ * - **Hyperbolic**: ($ a<0,\; e>1 $) → ($ r_p = a(1-e) = |a|(e-1) > 0 $), **no apoapsis** (unbounded), so ($ r_a = null $).
+ * - **Parabolic**: ($ e=1 $) is **not** defined with finite ($ a $). Use the parabolic form (e.g. ($ r_p = \tfrac{p}{2} $)) or state vectors.
+ *
+ * **Units**
+ * - Inputs: ($ a $) in **meters (m)**, ($ e $) dimensionless.
+ * - Output: ($ r_p, r_a $) in **meters (m)**.
+ *
+ * @param {number} a Semi-major axis ($ a $) (m). Must be finite and **≠ 0**.
+ * @param {number} e Eccentricity ($ e $) (dimensionless). Must be finite and **≥ 0**.
+ * @returns {{ rp: number; ra: number | null }} Object with periapsis `rp` and apoapsis `ra` (or `null` if undefined for hyperbolic).
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error}
+ * If inputs are invalid or the ($ (a,e) $) pair does not correspond to an ellipse/circle or hyperbola with finite ($ a $).
+ *
+ * @example
+ * ```ts
+ * // Elliptic example (LEO-like)
+ * const a = 7000e3;  // m
+ * const e = 0.01;
+ * const { rp, ra } = periApoapsisRadii(a, e); // rp ≈ 6930 km, ra ≈ 7070 km
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Hyperbolic flyby (no apoapsis)
+ * const a = -50_000e3; // m
+ * const e = 1.2;
+ * const { rp, ra } = periApoapsisRadii(a, e); // rp = |a|(e-1) = 10,000 km, ra = null
+ * ```
+ *
+ * @group Orbits
+ */
+/* node:coverage enable */
+export const periApoapsisRadii = (a, e) => {
+    if (!Number.isFinite(a) || a === 0) {
+        throw new Error('a must be finite and non-zero (meters).');
+    }
+    if (!Number.isFinite(e) || e < 0) {
+        throw new Error('e must be finite and ≥ 0.');
+    }
+    // Elliptic / circular
+    if (a > 0) {
+        if (e >= 1) {
+            if (e === 1) {
+                throw new Error('Parabolic (e=1) is not defined with finite a. Use parabolic relations (e.g., rp = p/2) or state vectors.');
+            }
+            throw new Error('For a>0 (elliptic/circular), eccentricity must satisfy 0 ≤ e < 1.');
+        }
+        const rp = a * (1 - e);
+        const ra = a * (1 + e);
+        // Both must be positive for a valid ellipse
+        if (!(rp > 0 && ra > 0)) {
+            throw new Error('Computed radii are non-physical for the given (a,e).');
+        }
+        return { rp, ra };
+    }
+    // Hyperbolic
+    // a < 0 requires e > 1 for a valid hyperbola
+    if (e <= 1) {
+        throw new Error('For a<0 (hyperbolic), eccentricity must satisfy e > 1.');
+    }
+    const rp = a * (1 - e); // = |a|(e-1) > 0
+    if (!(rp > 0)) {
+        // tiny negatives due to FP?
+        const tol = Math.abs(1e-14 * Math.abs(a));
+        if (rp > -tol) {
+            return { rp: 0, ra: null };
+        }
+        throw new Error('Computed periapsis radius is non-physical (≤ 0).');
+    }
+    return { rp, ra: null };
+};
+//# sourceMappingURL=peri-apoapsis-radii.js.map

package/dist/categories/orbits/peri-apoapsis-radii.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peri-apoapsis-radii.js","sourceRoot":"","sources":["../../../src/categories/orbits/peri-apoapsis-radii.ts"],"names":[],"mappings":"AAEA,2BAA2B;AAC3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,0BAA0B;AAC1B,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAS,EAAE,CAAS,EAAoB,EAAE;IAC1E,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC7D,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IAED,sBAAsB;IACtB,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACV,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CACb,0GAA0G,CAC3G,CAAC;YACJ,CAAC;YAED,MAAM,IAAI,KAAK,CACb,mEAAmE,CACpE,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACvB,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAEvB,4CAA4C;QAC5C,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,CAAC;QAED,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;IACpB,CAAC;IAED,aAAa;IACb,6CAA6C;IAC7C,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IAED,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,iBAAiB;IAEzC,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;QACd,4BAA4B;QAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAE1C,IAAI,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC;YACd,OAAO,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;QAC7B,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC,CAAC"}

package/dist/categories/orbits/specific-angular-momentum-from-elements.d.ts

@@ -0,0 +1,60 @@
+/**
+ * **Specific angular momentum** ($ h $) from **orbital elements**.
+ *
+ * **Definition**
+ *
+ * $$
+ * h=\sqrt{\mu\,a\,(1-e^2)}
+ * $$
+ *
+ * where ($ a $) is the semi-major axis, ($ e $) the eccentricity, and ($ \mu $) the gravitational parameter.
+ *
+ * **Validity by conic**
+ * - **Elliptic**: ($ a>0,\; 0\le e<1 $) → ($ 1-e^2>0 $) ⇒ radicand ($ >0 $).
+ * - **Hyperbolic**: ($ a<0,\; e>1 $) → ($ 1-e^2<0 $) and ($ a<0 $) ⇒ product still ($ >0 $).
+ * - **Parabolic**: ($ e=1 $) is not represented by finite ($ a $). Use state vectors or
+ *   ($ h=\sqrt{2\mu r_p} $) (with periapsis radius ($ r_p $)).
+ *
+ * **Units**
+ * - Inputs: ($ a $) in **m**, ($ e $) dimensionless, ($ \mu $) in **m³/s²**.
+ * - Output: ($ h $) in **m²/s**.
+ *
+ * ::: info
+ *
+ * - This returns the **magnitude** of ($ \mathbf h = \mathbf r \times \mathbf v $).
+ * - For numerical robustness, tiny negative radicands from FP cancellation are clamped to zero.
+ *
+ * :::
+ *
+ * @param {number} a  Semi-major axis ($ a $) (m). Must be finite and **≠ 0** (elliptic ($ a>0 $), hyperbolic ($ a<0 $)).
+ * @param {number} e  Eccentricity ($ e $) (dimensionless). Must be finite and **≥ 0**.
+ * @param {number} mu Gravitational parameter ($ \mu $) (m³/s²). Must be finite and **≥ 0**.
+ * @returns {number} Specific angular momentum ($ h $) (m²/s).
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error}
+ * If ($ a $) is non-finite or zero; if ($ e $) is non-finite or negative; if ($ \mu $) is non-finite or negative; or if
+ * ($ \mu\,a\,(1-e^2) < 0 $) beyond a tiny FP tolerance (invalid element set for this formula).
+ *
+ * @example
+ * ```ts
+ * // Near-circular LEO-like elements
+ * const muEarth = 3.986004418e14; // m^3/s^2
+ * const a = 6778e3;               // m
+ * const e = 0.001;
+ * const h = specificAngularMomentumFromElements(a, e, muEarth); // ≈ sqrt(μ a)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Hyperbolic flyby example
+ * const muEarth = 3.986004418e14; // m^3/s^2
+ * const a = -50000e3;             // m (negative for hyperbola)
+ * const e = 1.2;
+ * const h = specificAngularMomentumFromElements(a, e, muEarth);
+ * ```
+ *
+ * @see {@link specificAngularMomentum} - compute ($ h $) from state vectors ($ (\mathbf r,\mathbf v) $).
+ * @group Orbits
+ */
+export declare const specificAngularMomentumFromElements: (a: number, e: number, mu: number) => number;
+//# sourceMappingURL=specific-angular-momentum-from-elements.d.ts.map

package/dist/categories/orbits/specific-angular-momentum-from-elements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specific-angular-momentum-from-elements.d.ts","sourceRoot":"","sources":["../../../src/categories/orbits/specific-angular-momentum-from-elements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,eAAO,MAAM,mCAAmC,GAC9C,GAAG,MAAM,EACT,GAAG,MAAM,EACT,IAAI,MAAM,KACT,MAwBF,CAAC"}

package/dist/categories/orbits/specific-angular-momentum-from-elements.js

@@ -0,0 +1,76 @@
+/**
+ * **Specific angular momentum** ($ h $) from **orbital elements**.
+ *
+ * **Definition**
+ *
+ * $$
+ * h=\sqrt{\mu\,a\,(1-e^2)}
+ * $$
+ *
+ * where ($ a $) is the semi-major axis, ($ e $) the eccentricity, and ($ \mu $) the gravitational parameter.
+ *
+ * **Validity by conic**
+ * - **Elliptic**: ($ a>0,\; 0\le e<1 $) → ($ 1-e^2>0 $) ⇒ radicand ($ >0 $).
+ * - **Hyperbolic**: ($ a<0,\; e>1 $) → ($ 1-e^2<0 $) and ($ a<0 $) ⇒ product still ($ >0 $).
+ * - **Parabolic**: ($ e=1 $) is not represented by finite ($ a $). Use state vectors or
+ *   ($ h=\sqrt{2\mu r_p} $) (with periapsis radius ($ r_p $)).
+ *
+ * **Units**
+ * - Inputs: ($ a $) in **m**, ($ e $) dimensionless, ($ \mu $) in **m³/s²**.
+ * - Output: ($ h $) in **m²/s**.
+ *
+ * ::: info
+ *
+ * - This returns the **magnitude** of ($ \mathbf h = \mathbf r \times \mathbf v $).
+ * - For numerical robustness, tiny negative radicands from FP cancellation are clamped to zero.
+ *
+ * :::
+ *
+ * @param {number} a  Semi-major axis ($ a $) (m). Must be finite and **≠ 0** (elliptic ($ a>0 $), hyperbolic ($ a<0 $)).
+ * @param {number} e  Eccentricity ($ e $) (dimensionless). Must be finite and **≥ 0**.
+ * @param {number} mu Gravitational parameter ($ \mu $) (m³/s²). Must be finite and **≥ 0**.
+ * @returns {number} Specific angular momentum ($ h $) (m²/s).
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error}
+ * If ($ a $) is non-finite or zero; if ($ e $) is non-finite or negative; if ($ \mu $) is non-finite or negative; or if
+ * ($ \mu\,a\,(1-e^2) < 0 $) beyond a tiny FP tolerance (invalid element set for this formula).
+ *
+ * @example
+ * ```ts
+ * // Near-circular LEO-like elements
+ * const muEarth = 3.986004418e14; // m^3/s^2
+ * const a = 6778e3;               // m
+ * const e = 0.001;
+ * const h = specificAngularMomentumFromElements(a, e, muEarth); // ≈ sqrt(μ a)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Hyperbolic flyby example
+ * const muEarth = 3.986004418e14; // m^3/s^2
+ * const a = -50000e3;             // m (negative for hyperbola)
+ * const e = 1.2;
+ * const h = specificAngularMomentumFromElements(a, e, muEarth);
+ * ```
+ *
+ * @see {@link specificAngularMomentum} - compute ($ h $) from state vectors ($ (\mathbf r,\mathbf v) $).
+ * @group Orbits
+ */
+export const specificAngularMomentumFromElements = (a, e, mu) => {
+    if (!Number.isFinite(a) || a === 0)
+        throw new Error('a must be finite and non-zero (meters).');
+    if (!Number.isFinite(e) || e < 0)
+        throw new Error('e must be finite and ≥ 0.');
+    if (!Number.isFinite(mu) || mu < 0)
+        throw new Error('mu must be finite and ≥ 0 (m^3/s^2).');
+    const radicand = mu * a * (1 - e * e);
+    if (radicand < 0) {
+        // Allow tiny negatives due to FP cancellation
+        const tol = Math.abs(1e-14 * mu * Math.abs(a));
+        if (radicand > -tol)
+            return 0;
+        throw new Error(`Invalid (a,e) for this formula: μ·a·(1-e²) < 0 (μ=${mu}, a=${a}, e=${e}).`);
+    }
+    return Math.sqrt(radicand);
+};
+//# sourceMappingURL=specific-angular-momentum-from-elements.js.map

package/dist/categories/orbits/specific-angular-momentum-from-elements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specific-angular-momentum-from-elements.js","sourceRoot":"","sources":["../../../src/categories/orbits/specific-angular-momentum-from-elements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,CACjD,CAAS,EACT,CAAS,EACT,EAAU,EACF,EAAE;IACV,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAE7D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAE/C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAE1D,MAAM,QAAQ,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAEtC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,8CAA8C;QAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAE/C,IAAI,QAAQ,GAAG,CAAC,GAAG;YAAE,OAAO,CAAC,CAAC;QAE9B,MAAM,IAAI,KAAK,CACb,qDAAqD,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAC5E,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AAC7B,CAAC,CAAC"}

package/dist/categories/orbits/specific-angular-momentum.d.ts

@@ -0,0 +1,55 @@
+import { Vector3DTupleType } from '@interstellar-tools/types';
+/**
+ * **Specific angular momentum** ($ h $) (scalar magnitude).
+ *
+ * **Definitions**
+ *
+ * $$
+ * h = \lVert \mathbf r \times \mathbf v \rVert
+ * $$
+ *
+ * Useful identities:
+ *
+ * $$
+ * h = r\,v_{\perp},\qquad
+ * \text{(circular)}\ \ v_\perp=\sqrt{\mu/r}\Rightarrow h=\sqrt{\mu r}
+ * $$
+ *
+ * (For orbital elements, one also has ($ h=\sqrt{\mu\,a\,(1-e^2)} $), not used here.)
+ *
+ * **Units**
+ * - Inputs: ($ \mathbf r $) in **meters (m)**, ($ \mathbf v $) in **m/s**.
+ * - Output: ($ h $) in **m²/s**.
+ *
+ * ::: info
+ *
+ * - Returns the **magnitude** of ($ \mathbf h = \mathbf r \times \mathbf v $) (not the vector).
+ * - ($ h = 0 $) iff ($ \mathbf r \parallel \mathbf v $) (purely radial motion) or ($ \mathbf v=\mathbf 0 $).
+ * - In a two-body Keplerian model, ($ h $) is constant along the orbit.
+ *
+ * :::
+ *
+ * **Invariants (floating-point tolerance aside)**
+ * - ($ h \ge 0 $)
+ * - ($ \mathbf h \perp \mathbf r $) and ($ \mathbf h \perp \mathbf v $) (directional property; this function returns only ($ \lVert\mathbf h\rVert $)).
+ *
+ * @param {Vector3DTupleType} r Inertial position vector ($ \mathbf r=[x,y,z] $) (m).
+ * @param {Vector3DTupleType} v Inertial velocity vector ($ \mathbf v=[v_x,v_y,v_z] $) (m/s).
+ * @returns {number} Specific angular momentum ($ h $) (m²/s).
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If any component of `r`/`v` is non-finite; if `r` has zero length; or if `v` is invalid (NaN).
+ *
+ * @example
+ * ```ts
+ * // LEO-like state: r ⟂ v
+ * const r: [number, number, number] = [6778e3, 0, 0]; // m
+ * const v: [number, number, number] = [0, 7.67e3, 0]; // m/s
+ * const h = specificAngularMomentum(r, v);            // ≈ 5.20e10 m^2/s
+ * ```
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Specific_angular_momentum}
+ * @see {@link specificAngularMomentumFromElements} (if you compute from ($ a,e,\mu $))
+ * @group Orbits
+ */
+export declare const specificAngularMomentum: (r: Vector3DTupleType, v: Vector3DTupleType) => number;
+//# sourceMappingURL=specific-angular-momentum.d.ts.map

package/dist/categories/orbits/specific-angular-momentum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specific-angular-momentum.d.ts","sourceRoot":"","sources":["../../../src/categories/orbits/specific-angular-momentum.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAG9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,eAAO,MAAM,uBAAuB,GAClC,GAAG,iBAAiB,EACpB,GAAG,iBAAiB,KACnB,MAqBF,CAAC"}

package/dist/categories/orbits/specific-angular-momentum.js

@@ -0,0 +1,76 @@
+/* node:coverage disable */
+/**
+ * **Specific angular momentum** ($ h $) (scalar magnitude).
+ *
+ * **Definitions**
+ *
+ * $$
+ * h = \lVert \mathbf r \times \mathbf v \rVert
+ * $$
+ *
+ * Useful identities:
+ *
+ * $$
+ * h = r\,v_{\perp},\qquad
+ * \text{(circular)}\ \ v_\perp=\sqrt{\mu/r}\Rightarrow h=\sqrt{\mu r}
+ * $$
+ *
+ * (For orbital elements, one also has ($ h=\sqrt{\mu\,a\,(1-e^2)} $), not used here.)
+ *
+ * **Units**
+ * - Inputs: ($ \mathbf r $) in **meters (m)**, ($ \mathbf v $) in **m/s**.
+ * - Output: ($ h $) in **m²/s**.
+ *
+ * ::: info
+ *
+ * - Returns the **magnitude** of ($ \mathbf h = \mathbf r \times \mathbf v $) (not the vector).
+ * - ($ h = 0 $) iff ($ \mathbf r \parallel \mathbf v $) (purely radial motion) or ($ \mathbf v=\mathbf 0 $).
+ * - In a two-body Keplerian model, ($ h $) is constant along the orbit.
+ *
+ * :::
+ *
+ * **Invariants (floating-point tolerance aside)**
+ * - ($ h \ge 0 $)
+ * - ($ \mathbf h \perp \mathbf r $) and ($ \mathbf h \perp \mathbf v $) (directional property; this function returns only ($ \lVert\mathbf h\rVert $)).
+ *
+ * @param {Vector3DTupleType} r Inertial position vector ($ \mathbf r=[x,y,z] $) (m).
+ * @param {Vector3DTupleType} v Inertial velocity vector ($ \mathbf v=[v_x,v_y,v_z] $) (m/s).
+ * @returns {number} Specific angular momentum ($ h $) (m²/s).
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If any component of `r`/`v` is non-finite; if `r` has zero length; or if `v` is invalid (NaN).
+ *
+ * @example
+ * ```ts
+ * // LEO-like state: r ⟂ v
+ * const r: [number, number, number] = [6778e3, 0, 0]; // m
+ * const v: [number, number, number] = [0, 7.67e3, 0]; // m/s
+ * const h = specificAngularMomentum(r, v);            // ≈ 5.20e10 m^2/s
+ * ```
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Specific_angular_momentum}
+ * @see {@link specificAngularMomentumFromElements} (if you compute from ($ a,e,\mu $))
+ * @group Orbits
+ */
+/* node:coverage enable */
+export const specificAngularMomentum = (r, v) => {
+    // Validate inputs
+    for (const x of r)
+        if (!Number.isFinite(x))
+            throw new Error('r must be finite (meters).');
+    for (const x of v)
+        if (!Number.isFinite(x))
+            throw new Error('v must be finite (m/s).');
+    const r2 = r[0] * r[0] + r[1] * r[1] + r[2] * r[2];
+    const v2 = v[0] * v[0] + v[1] * v[1] + v[2] * v[2];
+    if (!(r2 > 0))
+        throw new Error('r must be non-zero (meters).');
+    if (!(v2 >= 0))
+        throw new Error('v must be valid (m/s).');
+    // h⃗ = r × v
+    const hx = r[1] * v[2] - r[2] * v[1];
+    const hy = r[2] * v[0] - r[0] * v[2];
+    const hz = r[0] * v[1] - r[1] * v[0];
+    const h = Math.hypot(hx, hy, hz); // m^2/s
+    return h;
+};
+//# sourceMappingURL=specific-angular-momentum.js.map

package/dist/categories/orbits/specific-angular-momentum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specific-angular-momentum.js","sourceRoot":"","sources":["../../../src/categories/orbits/specific-angular-momentum.ts"],"names":[],"mappings":"AAEA,2BAA2B;AAC3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,0BAA0B;AAC1B,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,CAAoB,EACpB,CAAoB,EACZ,EAAE;IACV,kBAAkB;IAClB,KAAK,MAAM,CAAC,IAAI,CAAC;QACf,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IACzE,KAAK,MAAM,CAAC,IAAI,CAAC;QACf,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAEtE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACnD,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAEnD,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAE/D,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAE1D,aAAa;IACb,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ;IAE1C,OAAO,CAAC,CAAC;AACX,CAAC,CAAC"}