@interstellar-tools/equations 0.1.1 → 0.2.0

package/dist/vis-viva-speed.d.ts

@@ -0,0 +1,42 @@
+/**
+ * **Vis-viva (orbital speed)** - compute speed magnitude ($ v $) from ($ r $), ($ a $), and ($ \mu $).
+ *
+ * **Definition**
+ *
+ * $$
+ * v = \sqrt{\mu\!\left(\frac{2}{r}-\frac{1}{a}\right)}
+ * $$
+ *
+ * - ($ r $): current distance from the focus (m)
+ * - ($ a $): semi-major axis (m). Elliptic ($ a>0 $), parabolic ($ a\to\infty $), hyperbolic ($ a<0 $)
+ * - ($ \mu $): gravitational parameter (m³/s²)
+ *
+ * **Units**
+ * - Inputs: ($ r $) in **m**, ($ a $) in **m**, ($ \mu $) in **m³/s²**.
+ * - Output: ($ v $) in **m/s**.
+ *
+ * ::: tip
+ *
+ * - For circular orbits (($ a=r $)): ($ v=\sqrt{\mu/r} $).
+ * - For parabolic trajectories, pass `a = Infinity` (so ($ 1/a=0 $)): ($ v=\sqrt{2\mu/r} $).
+ *
+ * :::
+ *
+ * @param {number} r  Radius ($ r $) (m), distance to the attracting body.
+ * @param {number} a  Semi-major axis ($ a $) (m). Use `Infinity` for parabolic, negative for hyperbolic.
+ * @param {number} mu Gravitational parameter ($ \mu $) (m³/s²).
+ * @returns {number} Speed magnitude ($ v $) (m/s).
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If inputs are non-finite / out of domain, or the radicand becomes negative.
+ *
+ * @example
+ * ```ts
+ * // LEO (~400 km): a ≈ r for near-circular
+ * const muEarth = 3.986004418e14; // m^3/s^2
+ * const r = 6378e3 + 400e3;       // m
+ * const a = r;                    // circular
+ * const v = visVivaSpeed(r, a, muEarth); // ≈ 7670 m/s
+ * ```
+ * @category Dynamics
+ */
+export declare const visVivaSpeed: (r: number, a: number, mu: number) => number;
+//# sourceMappingURL=vis-viva-speed.d.ts.map

package/dist/vis-viva-speed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vis-viva-speed.d.ts","sourceRoot":"","sources":["../src/vis-viva-speed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,IAAI,MAAM,KAAG,MAsC/D,CAAC"}

package/dist/vis-viva-speed.js

@@ -0,0 +1,70 @@
+/**
+ * **Vis-viva (orbital speed)** - compute speed magnitude ($ v $) from ($ r $), ($ a $), and ($ \mu $).
+ *
+ * **Definition**
+ *
+ * $$
+ * v = \sqrt{\mu\!\left(\frac{2}{r}-\frac{1}{a}\right)}
+ * $$
+ *
+ * - ($ r $): current distance from the focus (m)
+ * - ($ a $): semi-major axis (m). Elliptic ($ a>0 $), parabolic ($ a\to\infty $), hyperbolic ($ a<0 $)
+ * - ($ \mu $): gravitational parameter (m³/s²)
+ *
+ * **Units**
+ * - Inputs: ($ r $) in **m**, ($ a $) in **m**, ($ \mu $) in **m³/s²**.
+ * - Output: ($ v $) in **m/s**.
+ *
+ * ::: tip
+ *
+ * - For circular orbits (($ a=r $)): ($ v=\sqrt{\mu/r} $).
+ * - For parabolic trajectories, pass `a = Infinity` (so ($ 1/a=0 $)): ($ v=\sqrt{2\mu/r} $).
+ *
+ * :::
+ *
+ * @param {number} r  Radius ($ r $) (m), distance to the attracting body.
+ * @param {number} a  Semi-major axis ($ a $) (m). Use `Infinity` for parabolic, negative for hyperbolic.
+ * @param {number} mu Gravitational parameter ($ \mu $) (m³/s²).
+ * @returns {number} Speed magnitude ($ v $) (m/s).
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If inputs are non-finite / out of domain, or the radicand becomes negative.
+ *
+ * @example
+ * ```ts
+ * // LEO (~400 km): a ≈ r for near-circular
+ * const muEarth = 3.986004418e14; // m^3/s^2
+ * const r = 6378e3 + 400e3;       // m
+ * const a = r;                    // circular
+ * const v = visVivaSpeed(r, a, muEarth); // ≈ 7670 m/s
+ * ```
+ * @category Dynamics
+ */
+export const visVivaSpeed = (r, a, 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).');
+    }
+    if (!Number.isFinite(a)) {
+        // Allow Infinity (parabolic); disallow NaN/-Infinity for clarity
+        if (a === Infinity) {
+            // v = sqrt(2mu/r)
+            return Math.sqrt((2 * mu) / r);
+        }
+        throw new Error('a must be finite (or +Infinity for parabolic) in meters.');
+    }
+    if (a === 0) {
+        throw new Error('a must be non-zero (m). Use a→∞ for parabolic.');
+    }
+    const invA = 1 / a; // works for a>0 (elliptic) and a<0 (hyperbolic)
+    const radicand = mu * (2 / r - invA);
+    // Numerical guard: tiny negative due to FP → clamp; otherwise throw
+    if (radicand < 0) {
+        const tol = Math.abs((1e-14 * mu) / r);
+        if (radicand > -tol)
+            return 0; // effectively zero speed
+        throw new Error(`Invalid state: μ*(2/r - 1/a) < 0 (μ=${mu}, r=${r}, a=${a}).`);
+    }
+    return Math.sqrt(radicand);
+};
+//# sourceMappingURL=vis-viva-speed.js.map

package/dist/vis-viva-speed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vis-viva-speed.js","sourceRoot":"","sources":["../src/vis-viva-speed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,EAAU,EAAU,EAAE;IACvE,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,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACxB,iEAAiE;QACjE,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;YACnB,kBAAkB;YAClB,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACjC,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,gDAAgD;IACpE,MAAM,QAAQ,GAAG,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAErC,oEAAoE;IACpE,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAEvC,IAAI,QAAQ,GAAG,CAAC,GAAG;YAAE,OAAO,CAAC,CAAC,CAAC,yBAAyB;QAExD,MAAM,IAAI,KAAK,CACb,uCAAuC,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAC9D,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AAC7B,CAAC,CAAC"}

package/package.json

@@ -1,9 +1,81 @@
 {
   "name": "@interstellar-tools/equations",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "equations",
   "keywords": [
-    "equations"
+    "interstellar",
+    "tools",
+    "near",
+    "earth",
+    "objects",
+    "planets",
+    "orbit",
+    "rotation",
+    "stars",
+    "star",
+    "sun",
+    "planet",
+    "earth",
+    "moon",
+    "mercury",
+    "venus",
+    "mars",
+    "tellus",
+    "gaia",
+    "jupiter",
+    "saturn",
+    "neptune",
+    "pluto",
+    "dwarf",
+    "planets",
+    "trajectory",
+    "asteroids",
+    "comets",
+    "collision",
+    "satellite",
+    "satellites",
+    "sky map",
+    "nasa",
+    "jpl",
+    "esa",
+    "astrodynamics",
+    "orbital-mechanics",
+    "celestial-mechanics",
+    "two-body",
+    "n-body",
+    "gravity",
+    "newtonian-gravity",
+    "newtons-law-of-gravitation",
+    "gravitational-constant",
+    "G_SI",
+    "standard-gravitational-parameter",
+    "gravitational-parameter",
+    "mu",
+    "gravitational-force",
+    "gravitational-acceleration",
+    "specific-mechanical-energy",
+    "vis-viva",
+    "kepler-period",
+    "keplers-third-law",
+    "orbital-speed",
+    "trajectory",
+    "orbit",
+    "satellite",
+    "simulation",
+    "numerics",
+    "si-units",
+    "vector3",
+    "vec3",
+    "vector-math",
+    "typescript",
+    "javascript",
+    "interstellar-tools",
+    "spaceflight",
+    "space-dynamics",
+    "heliocentric",
+    "leo",
+    "geo",
+    "earth-sun"
   ],
   "homepage": "https://phun-ky.net/projects/interstellar-tools",
   "bugs": {
@@ -38,8 +110,8 @@
   },
   "dependencies": {
     "@interstellar-tools/temporal": "^0.1.0",
-    "@interstellar-tools/types": "^0.1.0",
-    "@interstellar-tools/constants": "^0.1.0"
+    "@interstellar-tools/types": "^0.1.2",
+    "@interstellar-tools/constants": "^0.1.2"
   },
   "devDependencies": {
     "@types/node": "^24.0.3",