Skip to content

Keplerian Orbital Elements

kepler

Represent Keplerian element sets and convert between cartesian

Notes
  • This class is used to represent Keplerian elements and convert between Cartesian coordinates
  • The class uses the semi-major axis (a), not the semiparameter
  • Elements are osculating and expressed in the frame of the input state (normally GCRF); the class does no frame handling
  • Each element set carries the gravitational parameter of its central body, mu (m^3/s^2); Earth's (satkit.consts.mu_earth) unless given, so lunar or heliocentric elements are supported by passing mu=satkit.consts.mu_moon / mu_sun
  • Only closed orbits are supported (0 <= eccen < 1); the constructor, from_pv and every element setter — the anomaly setters included — raise ValueError for an element outside its domain or a non-finite value, so an element set can never hold NaN
  • All angle units are radians
  • All length units are meters
  • All velocity units are meters / second

See the "Theory: Keplerian Elements" guide page for details.

mean_motion property

Mean motion, radians / second

true_anomaly property

True anomaly, radians

eccentric_anomaly property writable

Eccentric anomaly, radians

mean_anomaly property writable

Mean anomaly, radians

period property

Orbital period, seconds

semiparameter property

Semiparameter (semi-latus rectum) p = a (1 - e^2), meters

periapsis property

Radius of periapsis a (1 - e), meters

apoapsis property

Radius of apoapsis a (1 + e), meters

specific_energy property

Specific orbital energy -mu / (2 a), J/kg (m^2/s^2)

angular_momentum property

Magnitude of the specific angular momentum sqrt(mu p), m^2/s

flight_path_angle property

Flight-path angle, radians

atan2(e sin nu, 1 + e cos nu): the angle of the velocity above the local horizontal — zero at periapsis and apoapsis, positive while climbing.

argument_of_latitude property

Argument of latitude u = argp + nu, radians in [0, 2 pi)

Well defined for circular orbits, where argp and nu separately are not.

true_longitude property

True longitude raan + argp + nu, radians in [0, 2 pi)

Well defined for circular equatorial orbits, where raan, argp and nu separately are not.

mu property writable

Gravitational parameter of the central body, m^3/s^2

Setting it re-targets the dynamics (period, mean motion, propagate, to_pv) at another body while keeping the six geometric elements. Must be positive and finite (ValueError).

a property writable

Semi-major axis, meters (> 0; ValueError otherwise)

eccen property writable

Eccentricity, unitless (0 <= eccen < 1; ValueError otherwise)

inclination property writable

Inclination, radians (0 <= incl <= pi; ValueError otherwise)

raan property writable

Right ascension of ascending node, radians (finite; ValueError otherwise)

nu property writable

True anomaly, radians (finite; ValueError otherwise)

argp property writable

Argument of periapsis, radians (finite; ValueError otherwise)

w property writable

Argument of periapsis, radians — deprecated alias of argp

Kept indefinitely for compatibility; reading or assigning it emits DeprecationWarning. Validated like argp.

__init__(a, eccen, incl, raan, argp=None, nu=None, *, w=None, true_anomaly=None, eccentric_anomaly=None, mean_anomaly=None, mu=None)

Create Keplerian element set object from input elements

Parameters:

Name Type Description Default
a float

Semi-major axis, meters (> 0)

 required
eccen float

Eccentricity, unitless (0 <= eccen < 1)

 required
incl float

Inclination, radians (0 <= incl <= pi)

 required
raan float

Right ascension of ascending node, radians

 required
argp float | None

Argument of periapsis, radians (5th positional argument)

 None
nu float | None

True anomaly, radians (6th positional argument)

 None
w float | None

Argument of periapsis, radians — deprecated keyword alias of argp (kept indefinitely); give one or the other, not both

 None
true_anomaly float | None

True anomaly, radians (keyword alternative to nu)

 None
eccentric_anomaly float | None

Eccentric anomaly, radians (keyword alternative to nu)

 None
mean_anomaly float | None

Mean anomaly, radians (keyword alternative to nu)

 None
mu float | None

Gravitational parameter of the central body, m^3/s^2 (default satkit.consts.mu_earth)

 None

Raises:

Type Description
ValueError

an element outside its domain (non-finite value, a <= 0, eccen outside [0, 1), incl outside [0, pi], mu <= 0); more or fewer than one anomaly given; both argp and w given
TypeError

no argument of periapsis given
Notes

Exactly one of nu, true_anomaly, eccentric_anomaly or mean_anomaly must be given; anything else raises ValueError. All six elements may be passed positionally or by keyword.

Example 
import math
import satkit

# Create a ~400 km circular LEO orbit
k = satkit.kepler(
    a=6.781e6,  # semi-major axis, meters
    eccen=0.001,  # near-circular
    incl=math.radians(51.6),
    raan=math.radians(0),
    argp=math.radians(0),
    nu=math.radians(0),
)

# Same orbit, positional, located by mean anomaly instead
k2 = satkit.kepler(6.781e6, 0.001, math.radians(51.6), 0, 0, mean_anomaly=1.0)

# A 100 km circular lunar orbit
k_moon = satkit.kepler(1837.4e3, 0.0, math.radians(90), 0, 0, 0,
                       mu=satkit.consts.mu_moon)
print(f"lunar period: {k_moon.period / 60:.1f} min")

to_pv()

Convert Keplerian element set to position and velocity vectors

Returns:

Type Description
tuple[NDArray[float64], NDArray[float64]]

Tuple with two elements representing the position and velocity vectors
Example 
pos, vel = k.to_pv()
print(f"Position: {pos} m")
print(f"Velocity: {vel} m/s")

propagate(dt)

Propagate Keplerian element set by input duration

Two-body (unperturbed) propagation: only the anomaly changes.

Parameters:

Name Type Description Default
dt duration | float | int

Duration by which to propagate the Keplerian element set. A number is interpreted as seconds.

 required

Returns:

Type Description
kepler

Keplerian element set object after propagation
Example 
# Propagate orbit by one orbital period
k2 = k.propagate(k.period)
# ... or by ten minutes
k3 = k.propagate(satkit.duration.from_minutes(10))

Raises:

Type Description
TypeError

if dt is neither a duration nor a number.
ValueError

if dt is a NaN or infinite number of seconds.
OverflowError

if dt is too large for a duration.

from_pv(pos, vel, *, mu=None) staticmethod

Create Keplerian element set from input position and velocity vectors

Parameters:

Name Type Description Default
pos NDArray[float64]

3-element position vector, meters

 required
vel NDArray[float64]

3-element velocity vector, meters/second

 required
mu float | None

Gravitational parameter of the central body, m^3/s^2 (default satkit.consts.mu_earth); the returned element set carries it, so its period and to_pv refer to the same body

 None

Returns:

Type Description
kepler

Keplerian element set object
Example 
import numpy as np
pos = np.array([6.781e6, 0, 0])  # meters, GCRF
vel = np.array([0, 7.5e3, 0])    # m/s, GCRF
k = satkit.kepler.from_pv(pos, vel)
print(f"Semi-major axis: {k.a/1e3:.1f} km")
print(f"Eccentricity: {k.eccen:.6f}")

Raises:

Type Description
ValueError

if the state is hyperbolic/parabolic (eccen >= 1) or rectilinear (zero angular momentum), if pos or vel holds a NaN or infinity, or if mu is not positive and finite.
RuntimeError

if the inputs are not 3-element vectors.