OrbitalElements#
- class OrbitalElements#
Bases:
objectPerforms 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 andcovariance_to_elements()— uses Montenbruck & Gill’s \((a, e, i, \Omega, \omega, M)\) instead, listed inMEAN_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 Efor 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_elementsApplies 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 <= 0oreccis 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
covarianceis 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/RAANweakly 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 followMEAN_ELEMENT_NAMESand 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/randdE/de = a sin(E)/rfrom 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 followMEAN_ELEMENT_NAMES.
- static solve_kepler(mean_anomaly, ecc, tol: float = 1e-13, max_iter: int = 60)#
Solve
M = E - e sin Efor 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
eccis 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 —arather than the semi-latus rectum andMrather than the true anomaly — and is the one the covariance transformation is expressed in.
- exception InvalidCovarianceError#
Bases:
ValueErrorRaised when a covariance does not have the shape a Cartesian state covariance must have.
- exception KeplerConvergenceError#
Bases:
RuntimeErrorRaised when Kepler’s equation does not converge.
- exception NonEllipticOrbitError#
Bases:
ValueErrorRaised when an operation defined only for a closed orbit is asked for a parabolic or hyperbolic one.