Orbital Mechanics

Orbital coordinate transformation utilities.

This module provides tools for converting between Cartesian coordinates (position and velocity) and orbital elements, as well as computing Jacobian matrices for these transformations.

class multineas.orbit.OrbitalCoordinates[source]

Bases: object

Class for transforming between Cartesian coordinates and orbital elements.

This class provides methods to convert between position-velocity (X) coordinates and orbital elements (E), as well as computing the Jacobian matrix for these transformations. These transformations are essential for working with orbital mechanics and probability density functions in orbital element space.

None

Examples

Convert from Cartesian coordinates to orbital elements:

>>> from multineas.orbit import OrbitalCoordinates
>>> import numpy as np
>>>
>>> # Define position and velocity in AU and AU/day
>>> x, y, z = 1.0, 0.0, 0.0
>>> vx, vy, vz = 0.0, 6.28, 0.0
>>> mu = 0.01720209895**2  # Standard gravitational parameter
>>>
>>> oc = OrbitalCoordinates()
>>> q, e, i, Omega, w, M, a = oc.transformation_x_to_e(x, y, z, vx, vy, vz, mu)
>>> print(f"Semi-major axis: {a:.4f} AU")
>>> print(f"Eccentricity: {e:.4f}")

Convert from orbital elements back to Cartesian coordinates:

>>> x_new, y_new, z_new, vx_new, vy_new, vz_new = oc.transformation_e_to_x(
...     q, e, i, Omega, w, M, mu
... )
>>> print(f"Position: ({x_new:.4f}, {y_new:.4f}, {z_new:.4f}) AU")

Compute the Jacobian matrix for coordinate transformation:

>>> J = oc.compute_jacobian_x_to_e(a, e, i, Omega, w, M, mu)
>>> print(f"Jacobian shape: {J.shape}")

compute_jacobian_x_to_e(a: float, e: float, i: float, Omega: float, w: float, M: float, mu: float) → ndarray[source]

Compute the Jacobian matrix for transformation from Cartesian to orbital elements.

Computes the Jacobian matrix J that relates differential changes in Cartesian coordinates (x, y, z, vx, vy, vz) to differential changes in orbital elements (q, e, i, Omega, w, M). The Jacobian is computed using analytical derivatives of the transformation equations.

The Jacobian matrix has shape (6, 6) where: - Rows correspond to Cartesian coordinates: [x, y, z, vx, vy, vz] - Columns correspond to orbital elements: [q, e, i, Omega, w, M]

Parameters:

a (float) – Semi-major axis (AU).
e (float) – Eccentricity (dimensionless).
i (float) – Inclination (radians).
Omega (float) – Longitude of ascending node (radians).
w (float) – Argument of periapsis (radians).
M (float) – Mean anomaly (radians).
mu (float) – Standard gravitational parameter (AU^3/day^2).

Returns:

J – Jacobian matrix of shape (6, 6). The matrix relates changes in Cartesian coordinates to changes in orbital elements (q, e, i, Omega, w, M).

Return type:

numpy.ndarray

Examples

>>> from multineas.orbit import OrbitalCoordinates
>>> import numpy as np
>>>
>>> oc = OrbitalCoordinates()
>>> # Define orbital elements
>>> a = 1.0  # AU
>>> e = 0.1
>>> i = np.pi / 6  # 30 degrees
>>> Omega = 0.0
>>> w = 0.0
>>> M = 0.0
>>> mu = 0.01720209895**2
>>>
>>> # Compute Jacobian
>>> J = oc.compute_jacobian_x_to_e(a, e, i, Omega, w, M, mu)
>>> print(f"Jacobian shape: {J.shape}")
>>> print(f"Jacobian determinant: {np.linalg.det(J):.6e}")

Notes

This method is particularly useful for computing probability density functions in orbital element space from probability densities in Cartesian space, as the Jacobian determinant gives the volume element transformation factor.

The computation involves: 1. Solving Kepler’s equation to find the eccentric anomaly E 2. Computing partial derivatives with respect to each orbital element 3. Constructing the full Jacobian matrix 4. Applying a transformation from (a, e) to (q, e) coordinates

transformation_e_to_x(q: float, e: float, i: float, Omega: float, w: float, M: float, mu: float) → tuple[float, float, float, float, float, float][source]

Transform from orbital elements to Cartesian coordinates (position and velocity).

Converts orbital elements to a state vector (position x, y, z and velocity vx, vy, vz) using SPICE routines. This is the inverse transformation of transformation_x_to_e.

Parameters:

q (float) – Periapsis distance (AU).
e (float) – Eccentricity (dimensionless).
i (float) – Inclination (radians).
Omega (float) – Longitude of ascending node (radians).
w (float) – Argument of periapsis (radians).
M (float) – Mean anomaly (radians).
mu (float) – Standard gravitational parameter (AU^3/day^2).

Returns:

x (float) – X-component of position (AU).
y (float) – Y-component of position (AU).
z (float) – Z-component of position (AU).
vx (float) – X-component of velocity (AU/day).
vy (float) – Y-component of velocity (AU/day).
vz (float) – Z-component of velocity (AU/day).

Examples

>>> from multineas.orbit import OrbitalCoordinates
>>> import numpy as np
>>>
>>> oc = OrbitalCoordinates()
>>> # Define orbital elements
>>> q = 0.5  # AU
>>> e = 0.5
>>> i = np.pi / 4  # 45 degrees
>>> Omega = 0.0
>>> w = 0.0
>>> M = 0.0
>>> mu = 0.01720209895**2
>>>
>>> x, y, z, vx, vy, vz = oc.transformation_e_to_x(q, e, i, Omega, w, M, mu)
>>> print(f"Position: ({x:.4f}, {y:.4f}, {z:.4f}) AU")
>>> print(f"Velocity: ({vx:.4f}, {vy:.4f}, {vz:.4f}) AU/day")

transformation_x_to_e(x: float, y: float, z: float, vx: float, vy: float, vz: float, mu: float) → tuple[float, float, float, float, float, float, float][source]

Transform from Cartesian coordinates (position and velocity) to orbital elements.

Converts a state vector (position x, y, z and velocity vx, vy, vz) to orbital elements using SPICE routines. The orbital elements returned are: periapsis distance (q), eccentricity (e), inclination (i), longitude of ascending node (Omega), argument of periapsis (w), mean anomaly (M), and semi-major axis (a).

Parameters:

x (float) – X-component of position (AU).
y (float) – Y-component of position (AU).
z (float) – Z-component of position (AU).
vx (float) – X-component of velocity (AU/day).
vy (float) – Y-component of velocity (AU/day).
vz (float) – Z-component of velocity (AU/day).
mu (float) – Standard gravitational parameter (AU^3/day^2).

Returns:

q (float) – Periapsis distance (AU).
e (float) – Eccentricity (dimensionless).
i (float) – Inclination (radians).
Omega (float) – Longitude of ascending node (radians).
w (float) – Argument of periapsis (radians).
M (float) – Mean anomaly (radians).
a (float) – Semi-major axis (AU).

Examples

>>> from multineas.orbit import OrbitalCoordinates
>>> import numpy as np
>>>
>>> oc = OrbitalCoordinates()
>>> # Circular orbit at 1 AU
>>> x, y, z = 1.0, 0.0, 0.0
>>> vx, vy, vz = 0.0, 6.28, 0.0
>>> mu = 0.01720209895**2
>>>
>>> q, e, i, Omega, w, M, a = oc.transformation_x_to_e(x, y, z, vx, vy, vz, mu)
>>> print(f"Eccentricity: {e:.6f}")  # Should be close to 0 for circular orbit
>>> print(f"Semi-major axis: {a:.4f} AU")