@interstellar-tools/equations 0.2.0 → 0.3.0

package/dist/categories/gravity/acceleration-on1-by2.d.ts

@@ -0,0 +1,66 @@
+import type { Vector3DTupleType } from '@interstellar-tools/types';
+/**
+ * Gravitational **acceleration** of body 1 due to body 2 (vector, m/s²).
+ *
+ * **Definitions**
+ *
+ * $$
+ * \mathbf r=\mathbf r_2-\mathbf r_1,\quad
+ * r=\lVert\mathbf r\rVert,\quad
+ * \hat{\mathbf r}=\frac{\mathbf r}{r}
+ * $$
+ *
+ * **Acceleration field**
+ *
+ * $$
+ * \mathbf a_{1\leftarrow2}
+ * = \frac{\mathbf F_{1\leftarrow2}}{m_1}
+ * = G\,\frac{m_2}{r^2}\,\hat{\mathbf r}
+ * $$
+ *
+ * **Units**
+ * - Inputs: masses in **kg**, positions in **m**, ($ G $) in **m³·kg⁻¹·s⁻²**.
+ * - Output: acceleration in **m/s²**.
+ *
+ * ::: info
+ *
+ * - Implemented via `gravitationalForce(1, m2, r1, r2, G)`, so the returned vector equals the force on a **1 kg** test mass (i.e., the acceleration).
+ * - Direction points **from body 1 toward body 2**: ($  \hat{\mathbf r}  $).
+ *
+ * :::
+ *
+ * **Invariants (within FP tolerance)**
+ * - `||a|| = G*m2/r^2`
+ * - `a = ||a|| * r̂`
+ *
+ * @param {number} m2 Mass of body 2 (kg).
+ * @param {Vector3DTupleType} r1 Position of body 1 `[x, y, z]` in meters.
+ * @param {Vector3DTupleType} r2 Position of body 2 `[x, y, z]` in meters.
+ * @param {number} [G=G_SI] Gravitational constant.
+ * @returns {Vector3DTupleType} Acceleration of body 1 due to body 2 (m/s²).
+ *
+ * @example
+ * ```ts
+ * // Acceleration of a satellite due to Earth at ~7000 km from Earth's center
+ * const mSat = 500;                       // kg (any value; a is independent of mSat)
+ * const mEarth = 5.972e24;                // kg
+ * const rSat:   [number, number, number] = [7.0e6, 0, 0]; // m
+ * const rEarth: [number, number, number] = [0, 0, 0];
+ *
+ * const a = accelerationOn1By2(mSat, mEarth, rSat, rEarth);
+ * // ≈ [-8.14, 0, 0] m/s² (toward Earth)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Derive force from acceleration (F = m1 * a)
+ * const m1 = 1200; // kg spacecraft
+ * const a = accelerationOn1By2(m1, mEarth, rSat, rEarth);
+ * const F: [number, number, number] = [a[0]*m1, a[1]*m1, a[2]*m1]; // newtons
+ * ```
+ *
+ * @see https://en.wikipedia.org/wiki/Newton%27s_law_of_universal_gravitation
+ * @group Gravity
+ */
+export declare const accelerationOn1By2: (m2: number, r1: Vector3DTupleType, r2: Vector3DTupleType, G?: number) => Vector3DTupleType;
+//# sourceMappingURL=acceleration-on1-by2.d.ts.map

package/dist/categories/gravity/acceleration-on1-by2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acceleration-on1-by2.d.ts","sourceRoot":"","sources":["../../../src/categories/gravity/acceleration-on1-by2.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAInE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,eAAO,MAAM,kBAAkB,GAC7B,IAAI,MAAM,EACV,IAAI,iBAAiB,EACrB,IAAI,iBAAiB,EACrB,IAAG,MAAa,KACf,iBASF,CAAC"}

package/dist/categories/gravity/acceleration-on1-by2.js

@@ -0,0 +1,75 @@
+import { G_SI } from '@interstellar-tools/constants';
+import { gravitationalForce } from './gravitational-force';
+/**
+ * Gravitational **acceleration** of body 1 due to body 2 (vector, m/s²).
+ *
+ * **Definitions**
+ *
+ * $$
+ * \mathbf r=\mathbf r_2-\mathbf r_1,\quad
+ * r=\lVert\mathbf r\rVert,\quad
+ * \hat{\mathbf r}=\frac{\mathbf r}{r}
+ * $$
+ *
+ * **Acceleration field**
+ *
+ * $$
+ * \mathbf a_{1\leftarrow2}
+ * = \frac{\mathbf F_{1\leftarrow2}}{m_1}
+ * = G\,\frac{m_2}{r^2}\,\hat{\mathbf r}
+ * $$
+ *
+ * **Units**
+ * - Inputs: masses in **kg**, positions in **m**, ($ G $) in **m³·kg⁻¹·s⁻²**.
+ * - Output: acceleration in **m/s²**.
+ *
+ * ::: info
+ *
+ * - Implemented via `gravitationalForce(1, m2, r1, r2, G)`, so the returned vector equals the force on a **1 kg** test mass (i.e., the acceleration).
+ * - Direction points **from body 1 toward body 2**: ($  \hat{\mathbf r}  $).
+ *
+ * :::
+ *
+ * **Invariants (within FP tolerance)**
+ * - `||a|| = G*m2/r^2`
+ * - `a = ||a|| * r̂`
+ *
+ * @param {number} m2 Mass of body 2 (kg).
+ * @param {Vector3DTupleType} r1 Position of body 1 `[x, y, z]` in meters.
+ * @param {Vector3DTupleType} r2 Position of body 2 `[x, y, z]` in meters.
+ * @param {number} [G=G_SI] Gravitational constant.
+ * @returns {Vector3DTupleType} Acceleration of body 1 due to body 2 (m/s²).
+ *
+ * @example
+ * ```ts
+ * // Acceleration of a satellite due to Earth at ~7000 km from Earth's center
+ * const mSat = 500;                       // kg (any value; a is independent of mSat)
+ * const mEarth = 5.972e24;                // kg
+ * const rSat:   [number, number, number] = [7.0e6, 0, 0]; // m
+ * const rEarth: [number, number, number] = [0, 0, 0];
+ *
+ * const a = accelerationOn1By2(mSat, mEarth, rSat, rEarth);
+ * // ≈ [-8.14, 0, 0] m/s² (toward Earth)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Derive force from acceleration (F = m1 * a)
+ * const m1 = 1200; // kg spacecraft
+ * const a = accelerationOn1By2(m1, mEarth, rSat, rEarth);
+ * const F: [number, number, number] = [a[0]*m1, a[1]*m1, a[2]*m1]; // newtons
+ * ```
+ *
+ * @see https://en.wikipedia.org/wiki/Newton%27s_law_of_universal_gravitation
+ * @group Gravity
+ */
+export const accelerationOn1By2 = (m2, r1, r2, G = G_SI) => {
+    const { direction, magnitude } = gravitationalForce(1, m2, r1, r2, G); // |F| on 1 kg == |a|
+    const a = [
+        direction[0] * magnitude,
+        direction[1] * magnitude,
+        direction[2] * magnitude
+    ];
+    return a;
+};
+//# sourceMappingURL=acceleration-on1-by2.js.map

package/dist/categories/gravity/acceleration-on1-by2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acceleration-on1-by2.js","sourceRoot":"","sources":["../../../src/categories/gravity/acceleration-on1-by2.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,+BAA+B,CAAC;AAGrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,EAAU,EACV,EAAqB,EACrB,EAAqB,EACrB,IAAY,IAAI,EACG,EAAE;IACrB,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,kBAAkB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,qBAAqB;IAC5F,MAAM,CAAC,GAAsB;QAC3B,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS;QACxB,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS;QACxB,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS;KACzB,CAAC;IAEF,OAAO,CAAC,CAAC;AACX,CAAC,CAAC"}

package/dist/categories/gravity/force-on1-by2.d.ts

@@ -0,0 +1,87 @@
+import type { Vector3DTupleType } from '@interstellar-tools/types';
+/**
+ * Gravitational **force vector** on body 1 due to body 2 (newtons, N).
+ *
+ * **Definitions**
+ *
+ * $$
+ * \mathbf r=\mathbf r_2-\mathbf r_1,\quad
+ * r=\lVert\mathbf r\rVert,\quad
+ * \hat{\mathbf r}=\frac{\mathbf r}{r}
+ * $$
+ *
+ * **Newton's law (vector form)**
+ *
+ * $$
+ * \mathbf F_{1\leftarrow2}
+ * = G\,\frac{m_1 m_2}{r^2}\,\hat{\mathbf r}
+ * $$
+ *
+ * **Magnitude & Components**
+ *
+ * $$
+ * \lVert\mathbf F\rVert=G\,\frac{m_1 m_2}{r^2},\qquad
+ * \mathbf F=\langle F_x,F_y,F_z\rangle=\lVert\mathbf F\rVert\,\hat{\mathbf r}
+ * $$
+ *
+ * $$
+ * F_x=\lVert\mathbf F\rVert\,\hat r_x,\quad
+ * F_y=\lVert\mathbf F\rVert\,\hat r_y,\quad
+ * F_z=\lVert\mathbf F\rVert\,\hat r_z
+ * $$
+ *
+ * **Newton's 3rd law (context)**
+ *
+ * $$
+ * \mathbf F_{1\leftarrow2}=-\,\mathbf F_{2\leftarrow1}
+ * $$
+ *
+ * **Units**
+ * - Inputs: masses in **kg**, positions in **m**, ($ G $) in **m³·kg⁻¹·s⁻²**.
+ * - Output: force vector in **newtons (N)**.
+ *
+ * ::: info
+ *
+ * - The returned vector points **from body 1 toward body 2** (i.e., along ($  \hat{\mathbf r}  $)).
+ * - Internally delegates to `gravitationalForce(m1, m2, r1, r2, G)` and returns its
+ *   direction-scaled magnitude as a 3-tuple.
+ * - For acceleration instead of force, use `accelerationOn1By2` or compute ($  \mathbf a=\mathbf F/m_1  $).
+ *
+ * :::
+ *
+ * **Invariants (within FP tolerance)**
+ * - `||F|| = G*m1*m2/r^2`
+ * - `F = ||F|| * r̂`
+ *
+ * @param {number} m1 Mass of body 1 (kg).
+ * @param {number} m2 Mass of body 2 (kg).
+ * @param {Vector3DTupleType} r1 Position of body 1 `[x, y, z]` in meters.
+ * @param {Vector3DTupleType} r2 Position of body 2 `[x, y, z]` in meters.
+ * @param {number} [G=G_SI] Gravitational constant.
+ * @returns {Vector3DTupleType} Force on body 1 due to body 2, in newtons `[Fx, Fy, Fz]`.
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} Propagated from `gravitationalForce` if inputs are invalid (non-finite/negative masses, coincident positions ($ r=0 $), or non-positive ($ G $)).
+ *
+ * @example
+ * ```ts
+ * // Earth–Sun at ~1 AU (force on Earth due to Sun)
+ * const mEarth = 5.972e24;  // kg
+ * const mSun   = 1.9885e30; // kg
+ * const rEarth: [number, number, number] = [0, 0, 0];
+ * const rSun  : [number, number, number] = [1.495978707e11, 0, 0]; // m
+ *
+ * const F = forceOn1By2(mEarth, mSun, rEarth, rSun); // N
+ * const Fmag = Math.hypot(F[0], F[1], F[2]); // ≈ 3.54e22 N
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Derive acceleration from the returned force: a = F / m1
+ * const a: [number, number, number] = [F[0]/mEarth, F[1]/mEarth, F[2]/mEarth]; // m/s^2
+ * ```
+ *
+ * @see https://en.wikipedia.org/wiki/Newton%27s_law_of_universal_gravitation
+ * @group Gravity
+ */
+export declare const forceOn1By2: (m1: number, m2: number, r1: Vector3DTupleType, r2: Vector3DTupleType, G?: number) => Vector3DTupleType;
+//# sourceMappingURL=force-on1-by2.d.ts.map

package/dist/categories/gravity/force-on1-by2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"force-on1-by2.d.ts","sourceRoot":"","sources":["../../../src/categories/gravity/force-on1-by2.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAInE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,eAAO,MAAM,WAAW,GACtB,IAAI,MAAM,EACV,IAAI,MAAM,EACV,IAAI,iBAAiB,EACrB,IAAI,iBAAiB,EACrB,IAAG,MAAa,KACf,iBASF,CAAC"}

package/dist/categories/gravity/force-on1-by2.js

@@ -0,0 +1,96 @@
+import { G_SI } from '@interstellar-tools/constants';
+import { gravitationalForce } from './gravitational-force';
+/**
+ * Gravitational **force vector** on body 1 due to body 2 (newtons, N).
+ *
+ * **Definitions**
+ *
+ * $$
+ * \mathbf r=\mathbf r_2-\mathbf r_1,\quad
+ * r=\lVert\mathbf r\rVert,\quad
+ * \hat{\mathbf r}=\frac{\mathbf r}{r}
+ * $$
+ *
+ * **Newton's law (vector form)**
+ *
+ * $$
+ * \mathbf F_{1\leftarrow2}
+ * = G\,\frac{m_1 m_2}{r^2}\,\hat{\mathbf r}
+ * $$
+ *
+ * **Magnitude & Components**
+ *
+ * $$
+ * \lVert\mathbf F\rVert=G\,\frac{m_1 m_2}{r^2},\qquad
+ * \mathbf F=\langle F_x,F_y,F_z\rangle=\lVert\mathbf F\rVert\,\hat{\mathbf r}
+ * $$
+ *
+ * $$
+ * F_x=\lVert\mathbf F\rVert\,\hat r_x,\quad
+ * F_y=\lVert\mathbf F\rVert\,\hat r_y,\quad
+ * F_z=\lVert\mathbf F\rVert\,\hat r_z
+ * $$
+ *
+ * **Newton's 3rd law (context)**
+ *
+ * $$
+ * \mathbf F_{1\leftarrow2}=-\,\mathbf F_{2\leftarrow1}
+ * $$
+ *
+ * **Units**
+ * - Inputs: masses in **kg**, positions in **m**, ($ G $) in **m³·kg⁻¹·s⁻²**.
+ * - Output: force vector in **newtons (N)**.
+ *
+ * ::: info
+ *
+ * - The returned vector points **from body 1 toward body 2** (i.e., along ($  \hat{\mathbf r}  $)).
+ * - Internally delegates to `gravitationalForce(m1, m2, r1, r2, G)` and returns its
+ *   direction-scaled magnitude as a 3-tuple.
+ * - For acceleration instead of force, use `accelerationOn1By2` or compute ($  \mathbf a=\mathbf F/m_1  $).
+ *
+ * :::
+ *
+ * **Invariants (within FP tolerance)**
+ * - `||F|| = G*m1*m2/r^2`
+ * - `F = ||F|| * r̂`
+ *
+ * @param {number} m1 Mass of body 1 (kg).
+ * @param {number} m2 Mass of body 2 (kg).
+ * @param {Vector3DTupleType} r1 Position of body 1 `[x, y, z]` in meters.
+ * @param {Vector3DTupleType} r2 Position of body 2 `[x, y, z]` in meters.
+ * @param {number} [G=G_SI] Gravitational constant.
+ * @returns {Vector3DTupleType} Force on body 1 due to body 2, in newtons `[Fx, Fy, Fz]`.
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} Propagated from `gravitationalForce` if inputs are invalid (non-finite/negative masses, coincident positions ($ r=0 $), or non-positive ($ G $)).
+ *
+ * @example
+ * ```ts
+ * // Earth–Sun at ~1 AU (force on Earth due to Sun)
+ * const mEarth = 5.972e24;  // kg
+ * const mSun   = 1.9885e30; // kg
+ * const rEarth: [number, number, number] = [0, 0, 0];
+ * const rSun  : [number, number, number] = [1.495978707e11, 0, 0]; // m
+ *
+ * const F = forceOn1By2(mEarth, mSun, rEarth, rSun); // N
+ * const Fmag = Math.hypot(F[0], F[1], F[2]); // ≈ 3.54e22 N
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Derive acceleration from the returned force: a = F / m1
+ * const a: [number, number, number] = [F[0]/mEarth, F[1]/mEarth, F[2]/mEarth]; // m/s^2
+ * ```
+ *
+ * @see https://en.wikipedia.org/wiki/Newton%27s_law_of_universal_gravitation
+ * @group Gravity
+ */
+export const forceOn1By2 = (m1, m2, r1, r2, G = G_SI) => {
+    const { direction, magnitude } = gravitationalForce(m1, m2, r1, r2, G); // |F|
+    const F = [
+        direction[0] * magnitude,
+        direction[1] * magnitude,
+        direction[2] * magnitude
+    ];
+    return F;
+};
+//# sourceMappingURL=force-on1-by2.js.map

package/dist/categories/gravity/force-on1-by2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"force-on1-by2.js","sourceRoot":"","sources":["../../../src/categories/gravity/force-on1-by2.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,+BAA+B,CAAC;AAGrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,EAAU,EACV,EAAU,EACV,EAAqB,EACrB,EAAqB,EACrB,IAAY,IAAI,EACG,EAAE;IACrB,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,kBAAkB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM;IAC9E,MAAM,CAAC,GAAsB;QAC3B,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS;QACxB,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS;QACxB,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS;KACzB,CAAC;IAEF,OAAO,CAAC,CAAC;AACX,CAAC,CAAC"}

package/dist/categories/gravity/gravitational-force.d.ts

@@ -0,0 +1,94 @@
+import type { ForceResultInterface, Vector3DTupleType } from '@interstellar-tools/types';
+/**
+ * Compute the Newtonian **gravitational force** on body 1 due to body 2.
+ *
+ * **Definitions**
+ *
+ * $$
+ * \mathbf r=\mathbf r_2-\mathbf r_1,\quad
+ * r=\lVert\mathbf r\rVert,\quad
+ * \hat{\mathbf r}=\frac{\mathbf r}{r}
+ * $$
+ *
+ * **Law & Decomposition**
+ *
+ * $$
+ * \mathbf F_{1\leftarrow2}
+ * = G\,\frac{m_1 m_2}{r^2}\,\hat{\mathbf r}
+ * $$
+ *
+ * $$
+ * \lVert\mathbf F\rVert
+ * = G\,\frac{m_1 m_2}{r^2},\qquad
+ * \mathbf F=\langle F_x,F_y,F_z\rangle
+ * = \lVert\mathbf F\rVert\,\hat{\mathbf r}
+ * $$
+ *
+ * $$
+ * F_x=\lVert\mathbf F\rVert\,\hat r_x,\quad
+ * F_y=\lVert\mathbf F\rVert\,\hat r_y,\quad
+ * F_z=\lVert\mathbf F\rVert\,\hat r_z
+ * $$
+ *
+ * **Newton's 3rd law, for context**
+ *
+ * $$
+ * \mathbf F_{1\leftarrow2}=-\,\mathbf F_{2\leftarrow1}
+ * $$
+ *
+ * **Conventions & units**
+ * - Input masses in **kilograms (kg)**; positions in **meters (m)**.
+ * - Output force in **newtons (N)**.
+ * - Returned `vector` and `direction` point **from body 1 toward body 2**; i.e., `direction = \hat{\mathbf r}`.
+ *
+ * **Invariants (within numerical tolerance)**
+ * - `vector = magnitude * direction`
+ * - `magnitude = sqrt(Fx² + Fy² + Fz²)`
+ * - `||direction|| = 1`
+ *
+ *
+ * @param {number} m1 Mass of body 1 (kg).
+ * @param {number} m2 Mass of body 2 (kg).
+ * @param {Vector3DTupleType} r1 Position of body 1 as a 3-tuple `[x, y, z]` in meters.
+ * @param {Vector3DTupleType} r2 Position of body 2 as a 3-tuple `[x, y, z]` in meters.
+ * @param {number} [G]  Gravitational constant (defaults to `G_SI`, m³·kg⁻¹·s⁻²).
+ * @returns {ForceResultInterface} `{ vector, magnitude, direction }`.
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If `m1` or `m2` are non-finite or negative.
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If positions coincide (`r = 0`).
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If `G` is non-finite or not positive.
+ *
+ * @example
+ * ```ts
+ * import { gravitationalForce } from "@interstellar-tools/equations";
+ * import { G_SI } from "@interstellar-tools/constants";
+ *
+ * // Earth–Sun at ~1 AU
+ * const mEarth = 5.972e24;     // kg
+ * const mSun   = 1.9885e30;    // kg
+ * const rEarth: [number, number, number] = [0, 0, 0];
+ * const rSun  : [number, number, number] = [1.495978707e11, 0, 0]; // m
+ *
+ * const F = gravitationalForce(mEarth, mSun, rEarth, rSun, G_SI);
+ * console.log(F.magnitude.toExponential(3)); // ≈ "3.542e+22" N
+ * console.log(F.vector); // Points from Earth toward Sun (−x here)
+ * ```
+ *
+ * **Get F directly (recommended)**
+ *
+ * ```ts
+ * import { gravitationalForce } from "@interstellar-tools/equations";
+ * import type { Vector3DTupleType, ForceResultInterface } from "@interstellar-tools/types";
+ *
+ * const m1 = 5.972e24; // kg
+ * const m2 = 1.9885e30; // kg
+ * const r1: Vector3DTupleType = [0, 0, 0];                 // m
+ * const r2: Vector3DTupleType = [1.495978707e11, 0, 0];    // m
+ *
+ * const { vector: F, magnitude, direction }: ForceResultInterface = gravitationalForce(m1, m2, r1, r2);
+ * ```
+ *
+ * @see https://en.wikipedia.org/wiki/Newton%27s_law_of_universal_gravitation
+ * @group Gravity
+ */
+export declare const gravitationalForce: (m1: number, m2: number, r1: Vector3DTupleType, r2: Vector3DTupleType, G?: number) => ForceResultInterface;
+//# sourceMappingURL=gravitational-force.d.ts.map

package/dist/categories/gravity/gravitational-force.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gravitational-force.d.ts","sourceRoot":"","sources":["../../../src/categories/gravity/gravitational-force.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,eAAO,MAAM,kBAAkB,GAC7B,IAAI,MAAM,EACV,IAAI,MAAM,EACV,IAAI,iBAAiB,EACrB,IAAI,iBAAiB,EACrB,IAAG,MAAa,KACf,oBAgCF,CAAC"}

package/dist/categories/gravity/gravitational-force.js

@@ -0,0 +1,119 @@
+import { G_SI } from '@interstellar-tools/constants';
+/**
+ * Compute the Newtonian **gravitational force** on body 1 due to body 2.
+ *
+ * **Definitions**
+ *
+ * $$
+ * \mathbf r=\mathbf r_2-\mathbf r_1,\quad
+ * r=\lVert\mathbf r\rVert,\quad
+ * \hat{\mathbf r}=\frac{\mathbf r}{r}
+ * $$
+ *
+ * **Law & Decomposition**
+ *
+ * $$
+ * \mathbf F_{1\leftarrow2}
+ * = G\,\frac{m_1 m_2}{r^2}\,\hat{\mathbf r}
+ * $$
+ *
+ * $$
+ * \lVert\mathbf F\rVert
+ * = G\,\frac{m_1 m_2}{r^2},\qquad
+ * \mathbf F=\langle F_x,F_y,F_z\rangle
+ * = \lVert\mathbf F\rVert\,\hat{\mathbf r}
+ * $$
+ *
+ * $$
+ * F_x=\lVert\mathbf F\rVert\,\hat r_x,\quad
+ * F_y=\lVert\mathbf F\rVert\,\hat r_y,\quad
+ * F_z=\lVert\mathbf F\rVert\,\hat r_z
+ * $$
+ *
+ * **Newton's 3rd law, for context**
+ *
+ * $$
+ * \mathbf F_{1\leftarrow2}=-\,\mathbf F_{2\leftarrow1}
+ * $$
+ *
+ * **Conventions & units**
+ * - Input masses in **kilograms (kg)**; positions in **meters (m)**.
+ * - Output force in **newtons (N)**.
+ * - Returned `vector` and `direction` point **from body 1 toward body 2**; i.e., `direction = \hat{\mathbf r}`.
+ *
+ * **Invariants (within numerical tolerance)**
+ * - `vector = magnitude * direction`
+ * - `magnitude = sqrt(Fx² + Fy² + Fz²)`
+ * - `||direction|| = 1`
+ *
+ *
+ * @param {number} m1 Mass of body 1 (kg).
+ * @param {number} m2 Mass of body 2 (kg).
+ * @param {Vector3DTupleType} r1 Position of body 1 as a 3-tuple `[x, y, z]` in meters.
+ * @param {Vector3DTupleType} r2 Position of body 2 as a 3-tuple `[x, y, z]` in meters.
+ * @param {number} [G]  Gravitational constant (defaults to `G_SI`, m³·kg⁻¹·s⁻²).
+ * @returns {ForceResultInterface} `{ vector, magnitude, direction }`.
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If `m1` or `m2` are non-finite or negative.
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If positions coincide (`r = 0`).
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If `G` is non-finite or not positive.
+ *
+ * @example
+ * ```ts
+ * import { gravitationalForce } from "@interstellar-tools/equations";
+ * import { G_SI } from "@interstellar-tools/constants";
+ *
+ * // Earth–Sun at ~1 AU
+ * const mEarth = 5.972e24;     // kg
+ * const mSun   = 1.9885e30;    // kg
+ * const rEarth: [number, number, number] = [0, 0, 0];
+ * const rSun  : [number, number, number] = [1.495978707e11, 0, 0]; // m
+ *
+ * const F = gravitationalForce(mEarth, mSun, rEarth, rSun, G_SI);
+ * console.log(F.magnitude.toExponential(3)); // ≈ "3.542e+22" N
+ * console.log(F.vector); // Points from Earth toward Sun (−x here)
+ * ```
+ *
+ * **Get F directly (recommended)**
+ *
+ * ```ts
+ * import { gravitationalForce } from "@interstellar-tools/equations";
+ * import type { Vector3DTupleType, ForceResultInterface } from "@interstellar-tools/types";
+ *
+ * const m1 = 5.972e24; // kg
+ * const m2 = 1.9885e30; // kg
+ * const r1: Vector3DTupleType = [0, 0, 0];                 // m
+ * const r2: Vector3DTupleType = [1.495978707e11, 0, 0];    // m
+ *
+ * const { vector: F, magnitude, direction }: ForceResultInterface = gravitationalForce(m1, m2, r1, r2);
+ * ```
+ *
+ * @see https://en.wikipedia.org/wiki/Newton%27s_law_of_universal_gravitation
+ * @group Gravity
+ */
+export const gravitationalForce = (m1, m2, r1, r2, G = G_SI) => {
+    if (!Number.isFinite(m1) || !Number.isFinite(m2) || m1 < 0 || m2 < 0) {
+        throw new Error('m1 and m2 must be finite, non-negative numbers (kg).');
+    }
+    if (!Number.isFinite(G) || G <= 0) {
+        throw new Error('G must be a finite, positive number (m^3·kg^-1·s^-2).');
+    }
+    const rx = r2[0] - r1[0];
+    const ry = r2[1] - r1[1];
+    const rz = r2[2] - r1[2];
+    const r2mag = rx * rx + ry * ry + rz * rz;
+    if (r2mag === 0) {
+        throw new Error('Bodies are at the same position: gravitational force is singular (r = 0).');
+    }
+    const invR = 1 / Math.sqrt(r2mag);
+    const dir = [rx * invR, ry * invR, rz * invR];
+    // |F| = G m1 m2 / r^2
+    const magnitude = (G * m1 * m2) / r2mag;
+    // Vector points from body 1 toward body 2.
+    const Fx = dir[0] * magnitude;
+    const Fy = dir[1] * magnitude;
+    const Fz = dir[2] * magnitude;
+    // Ensure the tuple type is preserved for callers.
+    const vector = [Fx, Fy, Fz];
+    return { vector, magnitude, direction: dir };
+};
+//# sourceMappingURL=gravitational-force.js.map

package/dist/categories/gravity/gravitational-force.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gravitational-force.js","sourceRoot":"","sources":["../../../src/categories/gravity/gravitational-force.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,+BAA+B,CAAC;AAMrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,EAAU,EACV,EAAU,EACV,EAAqB,EACrB,EAAqB,EACrB,IAAY,IAAI,EACM,EAAE;IACxB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IACzB,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IACzB,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IACzB,MAAM,KAAK,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IAE1C,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACb,2EAA2E,CAC5E,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,GAAG,GAAsB,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;IACjE,sBAAsB;IACtB,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,KAAK,CAAC;IACxC,2CAA2C;IAC3C,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAC9B,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAC9B,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAC9B,kDAAkD;IAClD,MAAM,MAAM,GAAsB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAE/C,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;AAC/C,CAAC,CAAC"}

package/dist/{gravitational-parameter.d.ts → categories/gravity/gravitational-parameter.d.ts}

@@ -43,7 +43,7 @@
  * // Earth–Moon system (two-body μ)
  * const muEarthMoon = gravitationalParameter(5.97219e24, 7.342e22);
  * ```
- * @category Dynamics
+ * @group Gravity
  */
 export declare const gravitationalParameter: (M: number, m?: number, G?: number) => number;
 //# sourceMappingURL=gravitational-parameter.d.ts.map

package/dist/categories/gravity/gravitational-parameter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gravitational-parameter.d.ts","sourceRoot":"","sources":["../../../src/categories/gravity/gravitational-parameter.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,sBAAsB,GACjC,GAAG,MAAM,EACT,IAAG,MAAU,EACb,IAAG,MAAa,KACf,MAcF,CAAC"}

package/dist/{gravitational-parameter.js → categories/gravity/gravitational-parameter.js}

@@ -44,7 +44,7 @@ import { G_SI } from '@interstellar-tools/constants';
  * // Earth–Moon system (two-body μ)
  * const muEarthMoon = gravitationalParameter(5.97219e24, 7.342e22);
  * ```
- * @category Dynamics
+ * @group Gravity
  */
 export const gravitationalParameter = (M, m = 0, G = G_SI) => {
     if (!Number.isFinite(M) || M < 0) {

package/dist/categories/gravity/gravitational-parameter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gravitational-parameter.js","sourceRoot":"","sources":["../../../src/categories/gravity/gravitational-parameter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,+BAA+B,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,CAAS,EACT,IAAY,CAAC,EACb,IAAY,IAAI,EACR,EAAE;IACV,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AACrB,CAAC,CAAC"}

package/dist/{solve-kepler-bisection.d.ts → categories/kepler/solve-kepler-bisection.d.ts}

@@ -69,7 +69,7 @@ import { Radians } from '@interstellar-tools/types';
  *
  * @see [Kepler's Equation (Wikipedia)](https://en.wikipedia.org/wiki/Kepler%27s_equation)
  * @see [Bisection Method (Wikipedia)](https://en.wikipedia.org/wiki/Bisection_method)
- * @category Solve for Kepler
+ * @group Kepler Solvers
  */
 export declare const solveKeplerBisection: (M: Radians, e: number, maxIter: number, tolerance: number) => Radians;
 //# sourceMappingURL=solve-kepler-bisection.d.ts.map

package/dist/categories/kepler/solve-kepler-bisection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solve-kepler-bisection.d.ts","sourceRoot":"","sources":["../../../src/categories/kepler/solve-kepler-bisection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,eAAO,MAAM,oBAAoB,GAC/B,GAAG,OAAO,EACV,GAAG,MAAM,EACT,SAAS,MAAM,EACf,WAAW,MAAM,KAChB,OAwBF,CAAC"}

package/dist/{solve-kepler-bisection.js → categories/kepler/solve-kepler-bisection.js}

@@ -68,7 +68,7 @@
  *
  * @see [Kepler's Equation (Wikipedia)](https://en.wikipedia.org/wiki/Kepler%27s_equation)
  * @see [Bisection Method (Wikipedia)](https://en.wikipedia.org/wiki/Bisection_method)
- * @category Solve for Kepler
+ * @group Kepler Solvers
  */
 export const solveKeplerBisection = (M, e, maxIter, tolerance) => {
     let E_low = 0;

package/dist/categories/kepler/solve-kepler-bisection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solve-kepler-bisection.js","sourceRoot":"","sources":["../../../src/categories/kepler/solve-kepler-bisection.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,CAAU,EACV,CAAS,EACT,OAAe,EACf,SAAiB,EACR,EAAE;IACX,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IACrB,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,IAAI,GAAG,CAAC,CAAC;IAEb,OAAO,IAAI,GAAG,OAAO,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,EAAE,CAAC;YAC5B,OAAO,CAAC,CAAC,CAAC,YAAY;QACxB,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACV,MAAM,GAAG,CAAC,CAAC;QACb,CAAC;aAAM,CAAC;YACN,KAAK,GAAG,CAAC,CAAC;QACZ,CAAC;QAED,CAAC,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,EAAE,CAAC;IACT,CAAC;IAED,OAAO,CAAC,CAAC,CAAC,qBAAqB;AACjC,CAAC,CAAC"}

package/dist/{solve-kepler-high-eccentricity.d.ts → categories/kepler/solve-kepler-high-eccentricity.d.ts}

@@ -3,8 +3,6 @@ import { Radians } from '@interstellar-tools/types';
  * Solves **Kepler's Equation** for the **Eccentric Anomaly** ($E$) in highly eccentric orbits
  * ($e > 0.9$) using an iterative numerical approach.
  *
- * ---
- *
  * **Mathematical Explanation:**
  *
  * Kepler's equation for eccentric anomaly ($E$) is:
@@ -55,13 +53,11 @@ import { Radians } from '@interstellar-tools/types';
  * 3. **Angle Wrapping (Elliptical Only):**
  *    - The result is wrapped using `wrapAngle()` for consistency.
  *
- * ---
  *
  * **Performance Considerations:**
  * - **Typically converges in fewer than 10 iterations for $e > 0.9$.**
  * - **Time complexity:** $O(1)$ for standard convergence.
  *
- * ---
  *
  * @param {Radians} M - Mean anomaly ($M$) in **radians**.
  * @param {number} e - Orbital eccentricity ($e > 0.9$ for high-eccentricity orbits).
@@ -69,7 +65,6 @@ import { Radians } from '@interstellar-tools/types';
  * @param {number} [tolerance=1e-9] - Convergence criterion for stopping the iteration.
  * @returns {Radians} The **eccentric anomaly** ($E$) in **radians** (wrapped to $[-\pi, \pi]$ for elliptical orbits).
  *
- * ---
  *
  * @example
  * ```ts
@@ -89,11 +84,10 @@ import { Radians } from '@interstellar-tools/types';
  * console.log(solveKeplerHighEccentricity(M_hyperbolic, e_hyperbolic));
  * ```
  *
- * ---
- *
  * @see [Kepler's Equation (Wikipedia)](https://en.wikipedia.org/wiki/Kepler%27s_equation)
  * @see [Hyperbolic Anomaly (Wikipedia)](https://en.wikipedia.org/wiki/Hyperbolic_trajectory#Hyperbolic_anomaly)
- * @category Solve for Kepler
+ * @group Kepler Solvers
+ *
  */
 export declare const solveKeplerHighEccentricity: (M: Radians, e: number, maxIter?: number, tolerance?: number) => Radians;
 //# sourceMappingURL=solve-kepler-high-eccentricity.d.ts.map