ssapy_toolkit.Orbital_Mechanics.keplerian

Keplerian orbital element conversions and utilities.

This module provides functions for converting between Keplerian orbital elements and Cartesian state vectors, as well as computing various orbital parameters.

Functions

a_from_periap(rp, ra)	Compute semi-major axis (a) from perigee (rp) and apogee (ra) distances.
ae_from_periap(rp, ra)	Compute both semi-major axis and eccentricity from apsides.
apapsis_from_a_rp(a, rp)	Calculate apoapsis from semi-major axis and periapsis.
apoapsis(a, e)	Calculate apoapsis distance from semi-major axis and eccentricity.
calculate_orbital_elements(r_, v_[, ...])	Calculate classical orbital elements from position and velocity.
e_from_periap(rp, ra)	Compute eccentricity (e) from perigee (rp) and apogee (ra) distances.
get_chance_radius(v, time_step)	Calculate the chance radius based on the velocity vector.
hkoe(kElements_or_a[, e, i, pa, raan, nu])	Convert human-readable Keplerian Orbital Elements (KOE) to SSAPy format.
j2000_orbitals([planet, Teph])	Calculate JPL orbital elements using J2000 approximations.
kepler_to_parametric(a, e, i, omega, pa, theta)	Convert Keplerian elements to parametric coordinates.
kepler_to_state([a, e, i, pa, raan, nu, mu])	Convert Keplerian orbital elements to state vectors using broadcasting.
kepler_to_state_loop([a, e, i, pa, raan, nu, mu])	Convert Keplerian orbital elements to state vectors using loop.
mean_longitude(longitude_of_ascending_node, ...)	Calculate mean longitude from orbital angles.
peri_apo_apsis_from_rv(r, v)	Compute periapsis and apoapsis from state vectors.
peri_apo_from_rv(perigee, apogee)	Compute semi-major axis and eccentricity from apsides.
periapsis(a, e)	Calculate periapsis distance from semi-major axis and eccentricity.
period(a[, mu_barycenter])	Calculate the orbital period from the semi-major axis using Kepler's law.
rebound_orbital_elements([planet, time, format])	Get orbital elements for planets using REBOUND.
state_to_kepler(r, v[, mu])	Convert state vector (position and velocity) to Keplerian elements.
true_anomaly([eccentricity, ...])	Calculate true anomaly from various orbital parameters.
v_periapsis(a, rp, mu)	Calculate velocity at periapsis.
vcircular([r, mu_])	Calculate circular orbital velocity.
vis_viva(a, r, mu)	Calculate orbital velocity using vis-viva equation.

ssapy_toolkit.Orbital_Mechanics.keplerian.a_from_periap(rp, ra)

Compute semi-major axis (a) from perigee (rp) and apogee (ra) distances.

Parameters:

• rp (float) – Perigee distance (m), measured from center of the body.

• ra (float) – Apogee distance (m), measured from center of the body.

Returns:

• float – Semi-major axis (a) in meters.

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.ae_from_periap(rp, ra)

Compute both semi-major axis and eccentricity from apsides.

Parameters:

• rp (float) – Perigee distance (m).

• ra (float) – Apogee distance (m).

Returns:

• tuple – (a, e) - semi-major axis and eccentricity.

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.apapsis_from_a_rp(a, rp)

Calculate apoapsis from semi-major axis and periapsis.

Parameters:

• a (float) – Semi-major axis (m).

• rp (float) – Periapsis distance (m).

Returns:

• float – Apoapsis distance (m).

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.apoapsis(a, e)

Calculate apoapsis distance from semi-major axis and eccentricity.

Parameters:

• a (float) – Semi-major axis (m).

• e (float) – Eccentricity.

Returns:

• float – Apoapsis distance (m).

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.calculate_orbital_elements(r_, v_, mu_barycenter=398600441800000.0)

Calculate classical orbital elements from position and velocity.

Parameters:

• r (array-like) – Position vector(s) in Cartesian coordinates (m). Can be single vector or array of vectors.

• v (array-like) – Velocity vector(s) in Cartesian coordinates (m/s). Can be single vector or array of vectors.

• mu_barycenter (float, optional) – Gravitational parameter (m^3/s^2). Defaults to EARTH_MU.

Returns:

• dict – Dictionary containing the following orbital elements: - ‘a’ : ndarray - Semi-major axis (m). - ‘e’ : ndarray - Eccentricity (dimensionless). - ‘i’ : ndarray - Inclination (rad). - ‘tl’ : ndarray - True longitude (rad). - ‘pa’ : ndarray - Argument of periapsis (rad). - ‘raan’ : ndarray - Longitude of ascending node (rad). - ‘ta’ : ndarray - True anomaly (rad). - ‘L’ : ndarray - Specific angular momentum magnitude (m^2/s).

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.e_from_periap(rp, ra)

Compute eccentricity (e) from perigee (rp) and apogee (ra) distances.

Parameters:

• rp (float) – Perigee distance (m), measured from center of the body.

• ra (float) – Apogee distance (m), measured from center of the body.

Returns:

• float – Eccentricity (e), unitless (0 <= e < 1 for an ellipse).

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.get_chance_radius(v, time_step)

Calculate the chance radius based on the velocity vector.

Parameters:

• v (np.ndarray) – The velocity vector of the object at the final time step.

• time_step (float) – The time step between checks in seconds.

Returns:

• float – The calculated chance radius in meters.

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.hkoe(kElements_or_a, e=None, i=None, pa=None, raan=None, nu=None)

Convert human-readable Keplerian Orbital Elements (KOE) to SSAPy format.

Parameters:

• kElements_or_a (list, array, or float) – If a 6-element iterable [a, e, i, pa, raan, nu], it’s treated as the full set of elements. If a float, it’s treated as the semimajor axis (a), followed by 5 more positional arguments. Elements are: - a: semimajor axis (meters) - e: eccentricity (unitless) - i: inclination (degrees) - pa: argument of periapsis (degrees) - raan: right ascension of ascending node (degrees) - nu: true anomaly (degrees)

• e (float, optional) – Remaining elements if 6 positional arguments are provided (degrees).

• i (float, optional) – Remaining elements if 6 positional arguments are provided (degrees).

• pa (float, optional) – Remaining elements if 6 positional arguments are provided (degrees).

• raan (float, optional) – Remaining elements if 6 positional arguments are provided (degrees).

• nu (float, optional) – Remaining elements if 6 positional arguments are provided (degrees).

Returns:

Array of [a, e, i_rad, ap_rad, raan_rad, nu_rad] with angles in radians. Can be unpacked into individual variables or used as array.

Return type:

numpy.ndarray

Raises:

• ValueError – If arguments don’t match expected patterns (6-element iterable or 6 positional args).

• Author –

• ------ –

• Travis Yeager (yeager7@llnl.gov) –

ssapy_toolkit.Orbital_Mechanics.keplerian.j2000_orbitals(planet='earth', Teph=2451545.0)

Calculate JPL orbital elements using J2000 approximations.

Reference: https://ssd.jpl.nasa.gov/planets/approx_pos.html Valid for time interval 1800 AD - 2050 AD.

Parameters:

• planet (str, optional) – Planet name (default: ‘earth’).

• Teph (float, optional) – Epoch in Julian Date (default: 2451545.0 = J2000.0).

Returns:

• dict – Dictionary with keys: ‘a’, ‘e’, ‘i’, ‘mean_longitude’, ‘longitude_of_perihelion’, ‘longitude_of_the_ascending_node’.

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.kepler_to_parametric(a, e, i, omega, pa, theta)

Convert Keplerian elements to parametric coordinates.

Parameters:

• a (float) – Semi-major axis.

• e (float) – Eccentricity.

• i (float) – Inclination (degrees).

• omega (float) – Longitude of ascending node (degrees).

• pa (float) – Argument of periapsis (degrees).

• theta (float) – True anomaly (degrees).

Returns:

• tuple – (x_final, y_final, z_final) parametric coordinates.

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.kepler_to_state(a=1, e=0, i=0, pa=0, raan=0, nu=0, mu=398600441800000.0)

Convert Keplerian orbital elements to state vectors using broadcasting.

If any inputs are invalid (e.g., NaN or out-of-range values), the corresponding output is replaced with the average of the surrounding valid outputs.

Parameters:

• a (float or array-like) – Semi-major axis (m). Can be a single value or an array of values.

• e (float or array-like) – Eccentricity (dimensionless). Must be in [0, 1).

• i (float or array-like) – Inclination (rad). Must be in [0, π].

• raan (float or array-like) – Right ascension of the ascending node (rad). Must be in [0, 2π].

• pa (float or array-like) – Argument of perigee (rad). Must be in [0, 2π].

• nu (float or array-like) – True anomaly (rad). Must be in [0, 2π].

• mu (float, optional) – Gravitational parameter (m^3/s^2). Defaults to EARTH_MU.

Returns:

A tuple containing: - r : ndarray

Position vector(s) in inertial frame (m). Shape is (3,) for single set of orbital elements or (N, 3) for multiple sets.

• vndarray

  Velocity vector(s) in inertial frame (m/s). Shape is (3,) for single set of orbital elements or (N, 3) for multiple sets.

Return type:

tuple

Notes

• This function supports both single sets and arrays of orbital elements.

• Invalid inputs (NaN or out-of-range) are handled by replacing with average of surrounding valid outputs.

• Assumes all input values are in the same inertial reference frame.

Author

Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.kepler_to_state_loop(a=1, e=0, i=0, pa=0, raan=0, nu=0, mu=398600441800000.0)

Convert Keplerian orbital elements to state vectors using loop.

Parameters:

• a (float or array-like) – Semi-major axis (m).

• e (float or array-like) – Eccentricity (dimensionless).

• i (float or array-like) – Inclination (rad).

• raan (float or array-like) – Right ascension of the ascending node (rad).

• pa (float or array-like) – Argument of perigee (rad).

• nu (float or array-like) – True anomaly (rad).

• mu (float, optional) – Gravitational parameter (m^3/s^2). Defaults to EARTH_MU.

Returns:

• tuple – A tuple containing: - r : ndarray

  Position vector(s) in inertial frame (m).

  • vndarray

    Velocity vector(s) in inertial frame (m/s).

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.mean_longitude(longitude_of_ascending_node, argument_of_periapsis, mean_anomaly)

Calculate mean longitude from orbital angles.

Parameters:

• longitude_of_ascending_node (float) – Longitude of ascending node (radians).

• argument_of_periapsis (float) – Argument of periapsis (radians).

• mean_anomaly (float) – Mean anomaly (radians).

Returns:

• float – Mean longitude (radians).

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.peri_apo_apsis_from_rv(r, v)

Compute periapsis and apoapsis from state vectors.

Parameters:

• r (array-like) – Position vector (m).

• v (array-like) – Velocity vector (m/s).

Returns:

• dict – Dictionary with keys ‘periapsis’ and ‘apoapsis’.

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.peri_apo_from_rv(perigee, apogee)

Compute semi-major axis and eccentricity from apsides.

Parameters:

• perigee (float) – Perigee distance (m).

• apogee (float) – Apogee distance (m).

Returns:

• dict – Dictionary with keys ‘a’ and ‘e’.

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.periapsis(a, e)

Calculate periapsis distance from semi-major axis and eccentricity.

Parameters:

• a (float) – Semi-major axis (m).

• e (float) – Eccentricity.

Returns:

• float – Periapsis distance (m).

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.period(a, mu_barycenter=398600441800000.0)

Calculate the orbital period from the semi-major axis using Kepler’s law.

This function computes the orbital period for a satellite orbiting a central body, based on the semi-major axis of the orbit and the gravitational parameter of the body (default is Earth).

Parameters:

• a (float or np.ndarray) – Semi-major axis (in meters) of the orbit.

• mu_barycenter (float, optional) – Gravitational parameter of the central body (default is Earth’s gravitational parameter in m^3/s^2).

Returns:

• float or np.ndarray – Orbital period(s) in seconds.

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.rebound_orbital_elements(planet='earth', time='2000-1-1', format='utc')

Get orbital elements for planets using REBOUND.

Parameters:

• planet (str, optional) – Planet name or “all” for all planets (default: ‘earth’).

• time (str, optional) – Time string (default: “2000-1-1”).

• format (str, optional) – Time format (default: ‘utc’).

Returns:

• dict – Dictionary of orbital elements.

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.state_to_kepler(r, v, mu=398600441800000.0)

Convert state vector (position and velocity) to Keplerian elements.

Parameters:

• r (array-like) – Position vector in inertial frame (m). Can be single vector (3,) or array of vectors (N, 3).

• v (array-like) – Velocity vector in inertial frame (m/s). Can be single vector (3,) or array of vectors (N, 3).

• mu (float, optional) – Gravitational parameter (m^3/s^2). Defaults to EARTH_MU.

Returns:

• tuple – A tuple containing Keplerian orbital elements: - a : float or ndarray - Semi-major axis (m). - e : float or ndarray - Eccentricity (dimensionless). - i : float or ndarray - Inclination (rad). - pa : float or ndarray - Argument of perigee (rad). - raan : float or ndarray - RAAN (rad). - nu : float or ndarray - True anomaly (rad).

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.true_anomaly(eccentricity=None, eccentric_anomaly=None, mean_anomaly=None, true_longitude=None, argument_of_periapsis=None, longitude_of_ascending_node=None)

Calculate true anomaly from various orbital parameters.

Parameters:

• eccentricity (float, optional) – Orbital eccentricity.

• eccentric_anomaly (float, optional) – Eccentric anomaly (radians).

• mean_anomaly (float, optional) – Mean anomaly (radians).

• true_longitude (float, optional) – True longitude (radians).

• argument_of_periapsis (float, optional) – Argument of periapsis (radians).

• longitude_of_ascending_node (float, optional) – Longitude of ascending node (radians).

Returns:

• float – True anomaly (radians).

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.v_periapsis(a, rp, mu)

Calculate velocity at periapsis.

Parameters:

• a (float) – Semi-major axis (m).

• rp (float) – Periapsis distance (m).

• mu (float) – Gravitational parameter (m^3/s^2).

Returns:

• float – Velocity at periapsis (m/s).

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.vcircular(r=149597870700, mu_=1.32712786909e+20)

Calculate circular orbital velocity.

Parameters:

• r (float, optional) – Orbital radius (m). Defaults to 1 AU.

• mu (float, optional) – Gravitational parameter (m^3/s^2). Defaults to solar system total.

Returns:

• float – Circular orbital velocity (m/s).

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)

ssapy_toolkit.Orbital_Mechanics.keplerian.vis_viva(a, r, mu)

Calculate orbital velocity using vis-viva equation.

Parameters:

• a (float) – Semi-major axis (m).

• r (float) – Current orbital radius (m).

• mu (float) – Gravitational parameter (m^3/s^2).

Returns:

• float – Orbital velocity (m/s).

• Author

• ——

• Travis Yeager (yeager7@llnl.gov)