Skip to content

Keplerian

Keplerian orbital mechanics functions for Earth-centric orbits.

This module provides functions for computing orbital parameters from Keplerian elements, including orbital period, mean motion, semi-major axis, velocities at apsides, distances, altitudes, anomaly conversions, and special orbits (sun-synchronous, geostationary).

All functions use JAX operations and are compatible with jax.jit, jax.vmap, and jax.grad. Inputs are coerced to the configured float dtype (see :func:astrojax.config.set_dtype).

The anomaly conversion functions include a Newton-Raphson Kepler equation solver implemented with jax.lax.fori_loop for JAX traceability.

anomaly_eccentric_to_mean(anm_ecc, e, use_degrees=False)

Convert eccentric anomaly to mean anomaly.

Applies Kepler's equation: M = E - e * sin(E).

Parameters:

Name Type Description Default
anm_ecc ArrayLike

Eccentric anomaly. Units: rad or deg

 required
e ArrayLike

Eccentricity. Dimensionless.

 required
use_degrees bool

If True, input and output are in degrees.

 False

Returns:

Type Description
Array

Mean anomaly. Units: rad or deg
References

O. Montenbruck, and E. Gill, Satellite Orbits: Models, Methods and Applications, 2012. Eq. 2.65.

Examples:

from astrojax.orbits import anomaly_eccentric_to_mean
M = anomaly_eccentric_to_mean(90.0, 0.1, use_degrees=True)

anomaly_eccentric_to_true(anm_ecc, e, use_degrees=False)

Convert eccentric anomaly to true anomaly.

Parameters:

Name Type Description Default
anm_ecc ArrayLike

Eccentric anomaly. Units: rad or deg

 required
e ArrayLike

Eccentricity. Dimensionless.

 required
use_degrees bool

If True, input and output are in degrees.

 False

Returns:

Type Description
Array

True anomaly. Units: rad or deg
References

D. Vallado, Fundamentals of Astrodynamics and Applications (4th Ed.), pp. 47, eq. 2-9, 2010.

Examples:

from astrojax.orbits import anomaly_eccentric_to_true
nu = anomaly_eccentric_to_true(90.0, 0.1, use_degrees=True)

anomaly_mean_to_eccentric(anm_mean, e, use_degrees=False)

Convert mean anomaly to eccentric anomaly.

Solves Kepler's equation M = E - e * sin(E) for E using Newton-Raphson iteration implemented with jax.lax.fori_loop for JAX traceability.

Parameters:

Name Type Description Default
anm_mean ArrayLike

Mean anomaly. Units: rad or deg

 required
e ArrayLike

Eccentricity. Dimensionless.

 required
use_degrees bool

If True, input and output are in degrees.

 False

Returns:

Type Description
Array

Eccentric anomaly. Units: rad or deg

Examples:

from astrojax.orbits import anomaly_mean_to_eccentric
E = anomaly_mean_to_eccentric(84.27, 0.1, use_degrees=True)

anomaly_mean_to_true(anm_mean, e, use_degrees=False)

Convert mean anomaly to true anomaly.

Composite conversion: mean -> eccentric -> true.

Parameters:

Name Type Description Default
anm_mean ArrayLike

Mean anomaly. Units: rad or deg

 required
e ArrayLike

Eccentricity. Dimensionless.

 required
use_degrees bool

If True, input and output are in degrees.

 False

Returns:

Type Description
Array

True anomaly. Units: rad or deg

Examples:

from astrojax.orbits import anomaly_mean_to_true
nu = anomaly_mean_to_true(90.0, 0.1, use_degrees=True)

anomaly_true_to_eccentric(anm_true, e, use_degrees=False)

Convert true anomaly to eccentric anomaly.

Parameters:

Name Type Description Default
anm_true ArrayLike

True anomaly. Units: rad or deg

 required
e ArrayLike

Eccentricity. Dimensionless.

 required
use_degrees bool

If True, input and output are in degrees.

 False

Returns:

Type Description
Array

Eccentric anomaly. Units: rad or deg
References

D. Vallado, Fundamentals of Astrodynamics and Applications (4th Ed.), pp. 47, eq. 2-9, 2010.

Examples:

from astrojax.orbits import anomaly_true_to_eccentric
E = anomaly_true_to_eccentric(90.0, 0.1, use_degrees=True)

anomaly_true_to_mean(anm_true, e, use_degrees=False)

Convert true anomaly to mean anomaly.

Composite conversion: true -> eccentric -> mean.

Parameters:

Name Type Description Default
anm_true ArrayLike

True anomaly. Units: rad or deg

 required
e ArrayLike

Eccentricity. Dimensionless.

 required
use_degrees bool

If True, input and output are in degrees.

 False

Returns:

Type Description
Array

Mean anomaly. Units: rad or deg

Examples:

from astrojax.orbits import anomaly_true_to_mean
M = anomaly_true_to_mean(90.0, 0.1, use_degrees=True)

apoapsis_distance(a, e)

Compute the distance at apoapsis.

Parameters:

Name Type Description Default
a ArrayLike

Semi-major axis. Units: m

 required
e ArrayLike

Eccentricity. Dimensionless.

 required

Returns:

Type Description
Array

Apoapsis distance. Units: m

Examples:

from astrojax.orbits import apoapsis_distance
ra = apoapsis_distance(500e3, 0.1)

apogee_altitude(a, e)

Compute altitude above Earth's surface at apogee.

Parameters:

Name Type Description Default
a ArrayLike

Semi-major axis. Units: m

 required
e ArrayLike

Eccentricity. Dimensionless.

 required

Returns:

Type Description
Array

Apogee altitude. Units: m

Examples:

from astrojax.constants import R_EARTH
from astrojax.orbits import apogee_altitude
alt = apogee_altitude(R_EARTH + 500e3, 0.01)

apogee_velocity(a, e)

Compute velocity at apogee for an Earth orbit.

Parameters:

Name Type Description Default
a ArrayLike

Semi-major axis. Units: m

 required
e ArrayLike

Eccentricity. Dimensionless.

 required

Returns:

Type Description
Array

Apogee velocity magnitude. Units: m/s

Examples:

from astrojax.constants import R_EARTH
from astrojax.orbits import apogee_velocity
va = apogee_velocity(R_EARTH + 500e3, 0.001)

geo_sma()

Compute the semi-major axis for a geostationary orbit around Earth.

Returns:

Type Description
Array

Geostationary semi-major axis. Units: m

Examples:

from astrojax.orbits import geo_sma
a_geo = geo_sma()

mean_motion(a, use_degrees=False)

Compute the mean motion of an object orbiting Earth.

Parameters:

Name Type Description Default
a ArrayLike

Semi-major axis. Units: m

 required
use_degrees bool

If True, return mean motion in degrees per second.

 False

Returns:

Type Description
Array

Mean motion. Units: rad/s or deg/s

Examples:

from astrojax.constants import R_EARTH
from astrojax.orbits import mean_motion
n = mean_motion(R_EARTH + 500e3)

orbital_period(a)

Compute the orbital period of an object around Earth.

Parameters:

Name Type Description Default
a ArrayLike

Semi-major axis. Units: m

 required

Returns:

Type Description
Array

Orbital period. Units: s

Examples:

from astrojax.constants import R_EARTH
from astrojax.orbits import orbital_period
T = orbital_period(R_EARTH + 500e3)

orbital_period_from_state(state_eci)

Compute orbital period from an ECI state vector using the vis-viva equation.

Derives the semi-major axis from the state vector's position and velocity magnitudes, then computes the corresponding orbital period.

Parameters:

Name Type Description Default
state_eci ArrayLike

ECI state vector [x, y, z, vx, vy, vz]. Units: m and m/s

 required

Returns:

Type Description
Array

Orbital period. Units: s

Examples:

import jax.numpy as jnp
from astrojax.constants import R_EARTH, GM_EARTH
from astrojax.orbits import orbital_period_from_state
r = R_EARTH + 500e3
v = jnp.sqrt(GM_EARTH / r)
state = jnp.array([r, 0.0, 0.0, 0.0, v, 0.0])
T = orbital_period_from_state(state)

periapsis_distance(a, e)

Compute the distance at periapsis.

Parameters:

Name Type Description Default
a ArrayLike

Semi-major axis. Units: m

 required
e ArrayLike

Eccentricity. Dimensionless.

 required

Returns:

Type Description
Array

Periapsis distance. Units: m

Examples:

from astrojax.orbits import periapsis_distance
rp = periapsis_distance(500e3, 0.1)

perigee_altitude(a, e)

Compute altitude above Earth's surface at perigee.

Parameters:

Name Type Description Default
a ArrayLike

Semi-major axis. Units: m

 required
e ArrayLike

Eccentricity. Dimensionless.

 required

Returns:

Type Description
Array

Perigee altitude. Units: m

Examples:

from astrojax.constants import R_EARTH
from astrojax.orbits import perigee_altitude
alt = perigee_altitude(R_EARTH + 500e3, 0.01)

perigee_velocity(a, e)

Compute velocity at perigee for an Earth orbit.

Parameters:

Name Type Description Default
a ArrayLike

Semi-major axis. Units: m

 required
e ArrayLike

Eccentricity. Dimensionless.

 required

Returns:

Type Description
Array

Perigee velocity magnitude. Units: m/s

Examples:

from astrojax.constants import R_EARTH
from astrojax.orbits import perigee_velocity
vp = perigee_velocity(R_EARTH + 500e3, 0.001)

semimajor_axis(n, use_degrees=False)

Compute semi-major axis from mean motion around Earth.

Parameters:

Name Type Description Default
n ArrayLike

Mean motion. Units: rad/s or deg/s

 required
use_degrees bool

If True, interpret n as degrees per second.

 False

Returns:

Type Description
Array

Semi-major axis. Units: m

Examples:

from astrojax.orbits import semimajor_axis
a = semimajor_axis(0.001106784)

semimajor_axis_from_orbital_period(period)

Compute semi-major axis from orbital period around Earth.

Parameters:

Name Type Description Default
period ArrayLike

Orbital period. Units: s

 required

Returns:

Type Description
Array

Semi-major axis. Units: m

Examples:

from astrojax.orbits import semimajor_axis_from_orbital_period
a = semimajor_axis_from_orbital_period(5676.977)

sun_synchronous_inclination(a, e, use_degrees=False)

Compute the inclination for a Sun-synchronous orbit around Earth.

Uses the J2 gravitational perturbation to compute the inclination required for the RAAN precession rate to match Earth's mean motion around the Sun (one revolution per year).

Parameters:

Name Type Description Default
a ArrayLike

Semi-major axis. Units: m

 required
e ArrayLike

Eccentricity. Dimensionless.

 required
use_degrees bool

If True, return inclination in degrees.

 False

Returns:

Type Description
Array

Sun-synchronous inclination. Units: rad or deg

Examples:

from astrojax.constants import R_EARTH
from astrojax.orbits import sun_synchronous_inclination
inc = sun_synchronous_inclination(R_EARTH + 500e3, 0.001, use_degrees=True)