@interstellar-tools/equations 0.1.2 → 0.2.0

package/dist/law-of-gravitation.d.ts

@@ -0,0 +1,243 @@
+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
+ * @category Dynamics
+ */
+export declare const gravitationalForce: (m1: number, m2: number, r1: Vector3DTupleType, r2: Vector3DTupleType, G?: number) => ForceResultInterface;
+/**
+ * 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 = gravitationalAccelerationOn1By2(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 = gravitationalAccelerationOn1By2(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
+ * @category Dynamics
+ */
+export declare const gravitationalAccelerationOn1By2: (m2: number, r1: Vector3DTupleType, r2: Vector3DTupleType, G?: number) => Vector3DTupleType;
+/**
+ * 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 `gravitationalAccelerationOn1By2` 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 = gravitationalForceOn1By2(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
+ * @category Dynamics
+ */
+export declare const gravitationalForceOn1By2: (m1: number, m2: number, r1: Vector3DTupleType, r2: Vector3DTupleType, G?: number) => Vector3DTupleType;
+//# sourceMappingURL=law-of-gravitation.d.ts.map

package/dist/law-of-gravitation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"law-of-gravitation.d.ts","sourceRoot":"","sources":["../src/law-of-gravitation.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;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,eAAO,MAAM,+BAA+B,GAC1C,IAAI,MAAM,EACV,IAAI,iBAAiB,EACrB,IAAI,iBAAiB,EACrB,IAAG,MAAa,KACf,iBASF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,eAAO,MAAM,wBAAwB,GACnC,IAAI,MAAM,EACV,IAAI,MAAM,EACV,IAAI,iBAAiB,EACrB,IAAI,iBAAiB,EACrB,IAAG,MAAa,KACf,iBASF,CAAC"}

package/dist/law-of-gravitation.js

@@ -0,0 +1,284 @@
+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
+ * @category Dynamics
+ */
+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 };
+};
+/**
+ * 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 = gravitationalAccelerationOn1By2(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 = gravitationalAccelerationOn1By2(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
+ * @category Dynamics
+ */
+export const gravitationalAccelerationOn1By2 = (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;
+};
+/**
+ * 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 `gravitationalAccelerationOn1By2` 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 = gravitationalForceOn1By2(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
+ * @category Dynamics
+ */
+export const gravitationalForceOn1By2 = (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=law-of-gravitation.js.map

package/dist/law-of-gravitation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"law-of-gravitation.js","sourceRoot":"","sources":["../src/law-of-gravitation.ts"],"names":[],"mappings":"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"}

package/dist/specific-mechanical-energy.d.ts

@@ -0,0 +1,49 @@
+/**
+ * **Specific mechanical energy** ($  \varepsilon  $) of a point mass in a central gravity field.
+ *
+ * **Definition**
+ *
+ * $$
+ * \varepsilon = \frac{v^2}{2} - \frac{\mu}{r}
+ * $$
+ *
+ * where ($ v $) is the speed, ($ r $) the distance to the central body, and ($ \mu $) the gravitational parameter.
+ *
+ * **Units**
+ * - Inputs: ($ v $) in **m/s**, ($ r $) in **m**, ($ \mu $) in **m³/s²**.
+ * - Output: ($ \varepsilon $) in **J/kg** (i.e., m²/s²).
+ *
+ * **Orbit-type by sign**
+ * - ($ \varepsilon < 0 $) → **elliptic** (bound)
+ * - ($ \varepsilon = 0 $) → **parabolic**
+ * - ($ \varepsilon > 0 $) → **hyperbolic**
+ *
+ * ::: tip
+ *
+ * - For circular orbits ($ v = \sqrt{\mu/r} $), so ($  \varepsilon = -\mu/(2r)  $).
+ * - If you have the semi-major axis ($ a $), then ($  \varepsilon = -\mu/(2a)  $).
+ *
+ * :::
+ *
+ * @param {number} v  Speed magnitude ($ v $) (m/s).
+ * @param {number} r  Radius ($ r=\|\mathbf r\| $) from the central body (m).
+ * @param {number} mu Gravitational parameter ($ \mu $) (m³/s²).
+ * @returns {number} Specific mechanical energy ($ \varepsilon $) (J/kg).
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If `v` is not finite or negative.
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If `r` is not finite or non-positive.
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If `mu` is not finite or negative.
+ *
+ * @example
+ * ```ts
+ * // LEO example around Earth (~400 km altitude)
+ * const muEarth = 3.986004418e14; // m^3/s^2
+ * const r = 6378e3 + 400e3;       // Earth radius + 400 km
+ * const v = Math.sqrt(muEarth / r); // near-circular speed
+ * const eps = specificMechanicalEnergy(v, r, muEarth);
+ * // eps ≈ -mu/(2r)
+ * ```
+ * @category Dynamics
+ */
+export declare const specificMechanicalEnergy: (v: number, r: number, mu: number) => number;
+//# sourceMappingURL=specific-mechanical-energy.d.ts.map

package/dist/specific-mechanical-energy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specific-mechanical-energy.d.ts","sourceRoot":"","sources":["../src/specific-mechanical-energy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,wBAAwB,GACnC,GAAG,MAAM,EACT,GAAG,MAAM,EACT,IAAI,MAAM,KACT,MAWF,CAAC"}

package/dist/specific-mechanical-energy.js

@@ -0,0 +1,57 @@
+/**
+ * **Specific mechanical energy** ($  \varepsilon  $) of a point mass in a central gravity field.
+ *
+ * **Definition**
+ *
+ * $$
+ * \varepsilon = \frac{v^2}{2} - \frac{\mu}{r}
+ * $$
+ *
+ * where ($ v $) is the speed, ($ r $) the distance to the central body, and ($ \mu $) the gravitational parameter.
+ *
+ * **Units**
+ * - Inputs: ($ v $) in **m/s**, ($ r $) in **m**, ($ \mu $) in **m³/s²**.
+ * - Output: ($ \varepsilon $) in **J/kg** (i.e., m²/s²).
+ *
+ * **Orbit-type by sign**
+ * - ($ \varepsilon < 0 $) → **elliptic** (bound)
+ * - ($ \varepsilon = 0 $) → **parabolic**
+ * - ($ \varepsilon > 0 $) → **hyperbolic**
+ *
+ * ::: tip
+ *
+ * - For circular orbits ($ v = \sqrt{\mu/r} $), so ($  \varepsilon = -\mu/(2r)  $).
+ * - If you have the semi-major axis ($ a $), then ($  \varepsilon = -\mu/(2a)  $).
+ *
+ * :::
+ *
+ * @param {number} v  Speed magnitude ($ v $) (m/s).
+ * @param {number} r  Radius ($ r=\|\mathbf r\| $) from the central body (m).
+ * @param {number} mu Gravitational parameter ($ \mu $) (m³/s²).
+ * @returns {number} Specific mechanical energy ($ \varepsilon $) (J/kg).
+ *
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If `v` is not finite or negative.
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If `r` is not finite or non-positive.
+ * @throws {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error} If `mu` is not finite or negative.
+ *
+ * @example
+ * ```ts
+ * // LEO example around Earth (~400 km altitude)
+ * const muEarth = 3.986004418e14; // m^3/s^2
+ * const r = 6378e3 + 400e3;       // Earth radius + 400 km
+ * const v = Math.sqrt(muEarth / r); // near-circular speed
+ * const eps = specificMechanicalEnergy(v, r, muEarth);
+ * // eps ≈ -mu/(2r)
+ * ```
+ * @category Dynamics
+ */
+export const specificMechanicalEnergy = (v, r, mu) => {
+    if (!Number.isFinite(v) || v < 0)
+        throw new Error('v must be a finite, non-negative number (m/s).');
+    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 0.5 * v * v - mu / r;
+};
+//# sourceMappingURL=specific-mechanical-energy.js.map

package/dist/specific-mechanical-energy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specific-mechanical-energy.js","sourceRoot":"","sources":["../src/specific-mechanical-energy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACtC,CAAS,EACT,CAAS,EACT,EAAU,EACF,EAAE;IACV,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IAEpE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAE9D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IAEzE,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAC9B,CAAC,CAAC"}