Documentation / @interstellar-tools/equations / gravitationalForce

Function: gravitationalForce()

function gravitationalForce(
  m1: number,
  m2: number,
  r1: Vector3DTupleType,
  r2: Vector3DTupleType,
  G?: number
): ForceResultInterface;

Defined in: gravity/gravitational-force.ts:98

Compute the Newtonian gravitational force on body 1 due to body 2.

Definitions

$$\mathbf{r}={\mathbf{r}}_2-{\mathbf{r}}_1,r=\Vert \mathbf{r}\Vert ,\hat{\mathbf{r}}=\frac{\mathbf{r}}{r}$$

Law & Decomposition

$${\mathbf{F}}_{1\leftarrow 2}=G\frac{m_1{m}_2}{r^2}\hat{\mathbf{r}}$$$$\Vert \mathbf{F}\Vert =G\frac{m_1{m}_2}{r^2},\mathbf{F}=⟨F_x,F_y,F_z⟩=\Vert \mathbf{F}\Vert \hat{\mathbf{r}}$$$$F_x=\Vert \mathbf{F}\Vert {\hat{r}}_x,F_y=\Vert \mathbf{F}\Vert {\hat{r}}_y,F_z=\Vert \mathbf{F}\Vert {\hat{r}}_z$$

Newton's 3rd law, for context

$${\mathbf{F}}_{1\leftarrow 2}=-{\mathbf{F}}_{2\leftarrow 1}$$

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

Parameters

Parameter	Type	Default value	Description
m1	number	undefined	Mass of body 1 (kg).
m2	number	undefined	Mass of body 2 (kg).
r1	Vector3DTupleType	undefined	Position of body 1 as a 3-tuple [x, y, z] in meters.
r2	Vector3DTupleType	undefined	Position of body 2 as a 3-tuple [x, y, z] in meters.
G?	number	G_SI	Gravitational constant (defaults to G_SI, m³·kg⁻¹·s⁻²).

Returns

ForceResultInterface

{ vector, magnitude, direction }.

Throws

Error If m1 or m2 are non-finite or negative.

Throws

Error If positions coincide (r = 0).

Throws

Error If G is non-finite or not positive.

Example

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)

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's_law_of_universal_gravitation