Skip to content

Gravity

Gravity force models: point-mass and spherical harmonics.

Provides gravitational acceleration due to point-mass central bodies and spherical harmonic gravity field models (e.g. EGM2008, GGM05S, JGM3). All inputs and outputs use SI base units (metres, metres/second squared).

References
  1. O. Montenbruck and E. Gill, Satellite Orbits: Models, Methods and Applications, 2012, p. 56-68.

GravityModel

Spherical harmonic gravity field model.

Stores Stokes coefficients (C_nm, S_nm) parsed from ICGEM GFC format files. The coefficient matrix layout follows the Montenbruck & Gill convention:

  • data[n, m] stores the C coefficient for degree n, order m
  • data[m-1, n] stores the S coefficient for m > 0

This is a plain Python class (not a JAX pytree) since it holds static configuration data that does not participate in differentiation.

Parameters:

Name Type Description Default
model_name str

Human-readable name of the gravity model.

 required
gm float

Gravitational parameter [m3/s2].

 required
radius float

Reference radius [m].

 required
n_max int

Maximum degree of the model.

 required
m_max int

Maximum order of the model.

 required
data Array

Coefficient matrix, shape (n_max+1, m_max+1).

 required
tide_system str

Tide system convention (e.g. "tide_free").

 'unknown'
normalization str

Normalization convention (e.g. "fully_normalized").

 'fully_normalized'

Examples:

from astrojax.orbit_dynamics.gravity import GravityModel
model = GravityModel.from_type("JGM3")
c20, s20 = model.get(2, 0)

is_normalized property

Whether the coefficients are fully normalized.

from_file(filepath) classmethod

Load a gravity model from a GFC format file.

Parameters:

Name Type Description Default
filepath str | Path

Path to the .gfc file.

 required

Returns:

Name Type Description
GravityModel GravityModel

Loaded gravity model.

Raises:

Type Description
FileNotFoundError

If the file does not exist.
ValueError

If required header fields are missing.

from_type(model_type) classmethod

Load a packaged gravity model by name.

Available models:

  • "EGM2008_360" — truncated 360x360 EGM2008
  • "GGM05S" — full 180x180 GGM05S
  • "JGM3" — full 70x70 JGM3

Parameters:

Name Type Description Default
model_type str

One of the packaged model names.

 required

Returns:

Name Type Description
GravityModel GravityModel

Loaded gravity model.

Raises:

Type Description
ValueError

If the model type is not recognized.

get(n, m)

Retrieve the (C_nm, S_nm) coefficients for degree n, order m.

Parameters:

Name Type Description Default
n int

Degree of the harmonic.

 required
m int

Order of the harmonic.

 required

Returns:

Type Description
tuple[float, float]

tuple[float, float]: (C_nm, S_nm) coefficient pair.

Raises:

Type Description
ValueError

If (n, m) exceeds the model bounds.

set_max_degree_order(n, m)

Truncate the model to a smaller degree and order.

Coefficients beyond the new limits are discarded. This is irreversible.

Parameters:

Name Type Description Default
n int

New maximum degree (must be <= current n_max).

 required
m int

New maximum order (must be <= n and <= current m_max).

 required

Raises:

Type Description
ValueError

If validation fails.

accel_gravity(r_object)

Acceleration due to Earth's point-mass gravity.

Convenience wrapper for :func:accel_point_mass with Earth's gravitational parameter and the central body at the origin.

Parameters:

Name Type Description Default
r_object ArrayLike

Position of the object in ECI [m]. Shape (3,) or (6,) (only first 3 elements used).

 required

Returns:

Type Description
Array

Acceleration vector [m/s^2], shape (3,).

Examples:

import jax.numpy as jnp
from astrojax.constants import R_EARTH
from astrojax.orbit_dynamics import accel_gravity
r = jnp.array([R_EARTH, 0.0, 0.0])
a = accel_gravity(r)

accel_gravity_spherical_harmonics(r_eci, R_eci_to_ecef, gravity_model, n_max, m_max)

Acceleration from spherical harmonic gravity field expansion.

Computes the gravitational acceleration using recursively-computed associated Legendre functions (V/W matrix method). The position is transformed to the body-fixed frame, the acceleration is computed there, and transformed back to ECI.

Parameters:

Name Type Description Default
r_eci ArrayLike

Position in ECI frame [m]. Shape (3,) or (6,) (only first 3 elements used).

 required
R_eci_to_ecef ArrayLike

Rotation matrix from ECI to ECEF, shape (3, 3).

 required
gravity_model GravityModel

Loaded gravity model with Stokes coefficients.

 required
n_max int

Maximum degree for evaluation (must be <= model's n_max).

 required
m_max int

Maximum order for evaluation (must be <= n_max and <= model's m_max).

 required

Returns:

Type Description
Array

Acceleration in ECI frame [m/s^2], shape (3,).

Examples:

import jax.numpy as jnp
from astrojax.orbit_dynamics.gravity import (
    GravityModel, accel_gravity_spherical_harmonics,
)
model = GravityModel.from_type("JGM3")
r = jnp.array([6878e3, 0.0, 0.0])
R = jnp.eye(3)
a = accel_gravity_spherical_harmonics(r, R, model, 20, 20)

accel_point_mass(r_object, r_body, gm)

Acceleration due to point-mass gravity.

Computes the gravitational acceleration on r_object due to a body at r_body with gravitational parameter gm. When the central body is at the origin (r_body = [0, 0, 0]), the standard two-body expression -gm * r / |r|^3 is used. Otherwise the indirect (third-body) form is applied.

Parameters:

Name Type Description Default
r_object ArrayLike

Position of the object [m]. Shape (3,) or (6,) (only first 3 elements used).

 required
r_body ArrayLike

Position of the attracting body [m]. Shape (3,).

 required
gm float

Gravitational parameter of the attracting body [m3/s2].

 required

Returns:

Type Description
Array

Acceleration vector [m/s^2], shape (3,).

Examples:

import jax.numpy as jnp
from astrojax.constants import R_EARTH, GM_EARTH
from astrojax.orbit_dynamics import accel_point_mass
r = jnp.array([R_EARTH, 0.0, 0.0])
a = accel_point_mass(r, jnp.zeros(3), GM_EARTH)