OrbitalElements#

class OrbitalElements#

Bases: object

Performs conversions between Cartesian state vectors and classical orbital elements.

Provides static methods to convert between position/velocity vectors (r, v) and Keplerian orbital elements \((p, e, i, \Omega, \omega, \nu)\), as well as related quantities such as mean motion, period, and eccentric anomaly.

Two element sets appear here. rv2coe() returns the osculating set built on the semi-latus rectum and the true anomaly. Everything to do with partials — coe2rv(), rv2mean_elements(), the two Jacobians and covariance_to_elements() — uses Montenbruck & Gill’s \((a, e, i, \Omega, \omega, M)\) instead, listed in MEAN_ELEMENT_NAMES, because that is the set their closed-form partials are written for. The two describe the same orbit; only the parameterisation differs.

Methods

coe2rv(grav_param, a, ecc, inc, raan, argp, ...)

Build a Cartesian state from mean Keplerian elements.

covariance_to_elements(grav_param, r, v, ...)

Map a Cartesian state and its covariance into mean elements.

elements_by_state_jacobian(grav_param, r, v)

d(a, e, i, RAAN, argp, M) / d(r, v).

rv2coe(grav_param, r, v[, threshHold])

Convert state vector to classical orbital elements.

rv2mean_elements(grav_param, r, v)

Convert a Cartesian state to the mean elements the Jacobian uses.

solve_kepler(mean_anomaly, ecc[, tol, max_iter])

Solve M = E - e sin E for the eccentric anomaly.

state_by_elements_jacobian(grav_param, a, ...)

d(r, v) / d(a, e, i, RAAN, argp, M) in closed form.

See also

scarabaeus.SolutionOD.state_covariance_to_elements

Applies the covariance transformation to an OD solution.

References

[1]

Vallado, D. A. (2013). Fundamentals of Astrodynamics and Applications (4th ed.). Microcosm Press. ISBN 978-1-881883-18-0.

[2]

Montenbruck, O., & Gill, E. (2000). Satellite Orbits: Models, Methods and Applications. Springer. ISBN 978-3-540-67280-7.

classmethod coe2rv(grav_param, a, ecc, inc, raan, argp, mean_anomaly)#

Build a Cartesian state from mean Keplerian elements.

The inverse of rv2mean_elements(), and the function the elements-to-state Jacobian differentiates.

Parameters:
grav_paramfloat

Gravitational parameter in km^3/s^2.

afloat

Semi-major axis in km. Must be positive.

eccfloat

Eccentricity, 0 <= e < 1.

inc, raan, argp, mean_anomalyfloat

Inclination, RAAN, argument of periapsis and mean anomaly, radians.

Returns:
tuple of numpy.ndarray

Position (km) and velocity (km/s).

Raises:
NonEllipticOrbitError

If a <= 0 or ecc is outside [0, 1).

classmethod covariance_to_elements(grav_param, r, v, covariance)#

Map a Cartesian state and its covariance into mean elements.

Linear (first-order) propagation of uncertainty,

\[P_{oe} = J \, P_{rv} \, J^{T}, \qquad J = \frac{\partial(a,e,i,\Omega,\omega,M)} {\partial(\mathbf r, \mathbf v)}\]
Parameters:
grav_paramfloat

Gravitational parameter in km^3/s^2.

r, vnumpy.ndarray

Position (km) and velocity (km/s).

covariancenumpy.ndarray

(6, 6) Cartesian covariance, ordered (r, v). A larger matrix — a state carrying estimated parameters — is accepted and its leading 6x6 block is used.

Returns:
elementsnumpy.ndarray

(a, e, i, RAAN, argp, M), km and radians.

covariance_elementsnumpy.ndarray

(6, 6) covariance in those elements, symmetrised.

jacobiannumpy.ndarray

The (6, 6) Jacobian that was applied.

Raises:
InvalidCovarianceError

If covariance is not square, or smaller than 6x6.

NonEllipticOrbitError

If the state is not on a closed orbit.

Notes

This is a linearisation: it is accurate while the Cartesian uncertainty is small against the curvature of the element map. A near-circular or near-equatorial orbit makes argp/RAAN weakly defined and the Jacobian correspondingly large, so read those variances with care.

classmethod elements_by_state_jacobian(grav_param, r, v)#

d(a, e, i, RAAN, argp, M) / d(r, v).

The inverse of state_by_elements_jacobian(), which is how Montenbruck & Gill obtain it: the state-by-element partials have closed forms, and the map is a bijection wherever the elements are defined.

Parameters:
grav_paramfloat

Gravitational parameter in km^3/s^2.

r, vnumpy.ndarray

Position (km) and velocity (km/s).

Returns:
numpy.ndarray

(6, 6) Jacobian; rows follow MEAN_ELEMENT_NAMES and columns are (rx, ry, rz, vx, vy, vz).

Raises:
NonEllipticOrbitError

If the state is not on a closed orbit.

classmethod rv2mean_elements(grav_param, r, v)#

Convert a Cartesian state to the mean elements the Jacobian uses.

Same geometry as rv2coe(), re-expressed in Montenbruck & Gill’s set: semi-major axis instead of the semi-latus rectum, and mean anomaly instead of true anomaly.

Parameters:
grav_paramfloat

Gravitational parameter in km^3/s^2.

r, vnumpy.ndarray

Position (km) and velocity (km/s).

Returns:
numpy.ndarray

(a, ecc, inc, raan, argp, M) in km and radians.

Raises:
NonEllipticOrbitError

If the state is not on a closed orbit.

classmethod state_by_elements_jacobian(grav_param, a, ecc, inc, raan, argp, mean_anomaly)#

d(r, v) / d(a, e, i, RAAN, argp, M) in closed form.

Follows Montenbruck & Gill: the three orientation angles enter only through rigid rotations, so their partials are cross products with the corresponding rotation axis — the inertial pole for the RAAN, the line of nodes for the inclination, and the orbit normal for the argument of periapsis. The in-plane elements are differentiated through the eccentric anomaly, using dE/dM = a/r and dE/de = a sin(E)/r from Kepler’s equation.

Parameters:
grav_paramfloat

Gravitational parameter in km^3/s^2.

a, ecc, inc, raan, argp, mean_anomalyfloat

Mean elements, km and radians.

Returns:
numpy.ndarray

(6, 6) Jacobian; rows are (rx, ry, rz, vx, vy, vz) and columns follow MEAN_ELEMENT_NAMES.

static solve_kepler(mean_anomaly, ecc, tol: float = 1e-13, max_iter: int = 60)#

Solve M = E - e sin E for the eccentric anomaly.

Parameters:
mean_anomalyfloat

Mean anomaly in radians.

eccfloat

Eccentricity, 0 <= e < 1.

tolfloat, optional

Convergence tolerance on the Newton step. Defaults to 1e-13.

max_iterint, optional

Iteration cap. Defaults to 60.

Returns:
float

Eccentric anomaly in radians.

Raises:
NonEllipticOrbitError

If ecc is outside [0, 1). The equation still has real roots there, so without this guard an open orbit would return a number that is not an eccentric anomaly.

KeplerConvergenceError

If Newton’s method does not converge within max_iter.

rv2coe(grav_param: float, r: ndarray[tuple[Any, ...], dtype[_ScalarT]], v: ndarray[tuple[Any, ...], dtype[_ScalarT]], threshHold: float = 1e-08)#

Convert state vector to classical orbital elements.

Parameters:
grav_paramfloat

Standard gravitational parameter in \(\frac{km^3}{s^2}\).

rnp.ndarray

Position vector in kilometers.

vnp.ndarray

Velocity vector in kilometers per second.

tolfloat, optional

Tolerance for eccentricity and inclination checks. Defaults to 1e-8.

Returns:
pfloat

Semi-latus rectum of parameter in kilometers.

ecc: float

Eccentricity.

inc: float

Inclination in radians.

raan: float

Right ascension of the ascending node in radians.

argp: float

Argument of Perigee in radians.

nu: float

True Anomaly in radians.

Notes

All angles are in radians; distances in km; velocities in km/s

MEAN_ELEMENT_NAMES = ('a', 'ecc', 'inc', 'raan', 'argp', 'M')#

Element order used by rv2mean_elements(), coe2rv() and the Jacobians: semi-major axis, eccentricity, inclination, RAAN, argument of periapsis, mean anomaly. This is Montenbruck & Gill’s set — a rather than the semi-latus rectum and M rather than the true anomaly — and is the one the covariance transformation is expressed in.

exception InvalidCovarianceError#

Bases: ValueError

Raised when a covariance does not have the shape a Cartesian state covariance must have.

exception KeplerConvergenceError#

Bases: RuntimeError

Raised when Kepler’s equation does not converge.

exception NonEllipticOrbitError#

Bases: ValueError

Raised when an operation defined only for a closed orbit is asked for a parabolic or hyperbolic one.