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
  • The Earth gravitational parameter (MU_EARTH) is used throughout
  • Only closed orbits are supported (0 <= eccen < 1)
  • 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

a property writable

Semi-major axis, meters

eccen property writable

Eccentricity, unitless

inclination property writable

Inclination, radians

raan property writable

Right ascension of ascending node, radians

nu property writable

True anomaly, radians

w property writable

Argument of perigee, radians

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

Create Keplerian element set object from input elements

Parameters:

Name Type Description Default
a float

Semi-major axis, meters

 required
eccen float

Eccentricity, unitless (0 <= eccen < 1)

 required
incl float

Inclination, radians

 required
raan float

Right ascension of ascending node, radians

 required
w float

Argument of perigee, radians

 required
nu float | None

True anomaly, radians (6th positional argument)

 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
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),
    w=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)

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))

from_pv(pos, vel) staticmethod

Create Keplerian element set from input position and velocity vectors

Parameters:

Name Type Description Default
pos NDArray[float64]

3-element array representing position vector

 required
vel NDArray[float64]

3-element array representing velocity vector

 required

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
RuntimeError

if the state is hyperbolic/parabolic (eccen >= 1) or rectilinear (zero angular momentum), or if the inputs are not 3-element vectors.