gravitation

Utility functions for calculations related to (spherical harmonic) gravity fields

This module contains a list of utility functions for calculations related to (spherical harmonic) gravity fields. Note that the calculations relating to gravity fields that are relevant for a numerical propagation and estimation are done in the relevant environment, acceleration, etc. models in the numerical_simulation`. The functions in this module are meant to support the user on relevant pre- and post-processing steps.

Functions

legendre_normalization_factor(degree, order)

Function to calculate the normalization factor for spherical harmonics at a given degree and order

normalize_spherical_harmonic_coefficients(...)

Function to normalize spherical harmonic coefficients

unnormalize_spherical_harmonic_coefficients(...)

Function to unnormalize spherical harmonic coefficients

spherical_harmonic_coefficients_from_inertia(...)

Function to compute degree-two spherical harmonic coefficients from an inertia tensor

transform_spherical_harmonic_coefficients_with_wigner_d(...)

Function to rotate spherical harmonic coefficients with precomputed Wigner D-matrices

legendre_normalization_factor(degree: int, order: int) → float

Function to calculate the normalization factor for spherical harmonics at a given degree and order

Function to calculate the normalization factor for spherical harmonics at a given degree and order. Specifically, this function returns the value \(\mathcal{N}_{lm}\), computed from:

\[\mathcal{N}_{lm}=\sqrt{\frac{(2-\delta_{0m})(2l+1)(l-m)!)}{(l+m)!}}\]

with \(\delta_{0m}\) is the Kronecker Delta function. The following can be used such that the conversion between unnormalized and fully normalized spherical harmonic coefficients and Legendre polynomials can be computed from:

\[\begin{split}[C,S]_{lm}&=\mathcal{N}_{lm}[\bar{C},\bar{S}]_{lm}\\ \bar{P}_{lm}&=\mathcal{N}_{lm}{P}_{lm}\end{split}\]

with \([C,S]_{lm}\) denoting the unnormalized cosine or sine spherical harmonic coefficients at degree \(l\) and order \(m\), and \(P_{lm}\) and \(\bar{P}_{lm}\) representing the unnormalized and normalized associated Legendre polynomials at degree \(l\) and order \(m\).

Parameters:
  • degree (int) – Spherical harmonic degree \(l\)

  • order (int) – Spherical harmonic order \(m\)

Returns:

Normalization factor \(\mathcal{N}_{lm}\)

Return type:

float

normalize_spherical_harmonic_coefficients(unnormalized_cosine_coefficients: numpy.ndarray[numpy.float64[m, n]], unnormalized_sine_coefficients: numpy.ndarray[numpy.float64[m, n]]) → tuple[numpy.ndarray[numpy.float64[m, n]], numpy.ndarray[numpy.float64[m, n]]]

Function to normalize spherical harmonic coefficients

Function to normalize spherical harmonic coefficients, using the equations provided in the legendre_normalization_factor() function.

Parameters:
  • unnormalized_cosine_coefficients (numpy.ndarray) – Matrix for which entry \((i,j)\) contains the unnormalized cosine coefficient \(C_{lm}\)

  • unnormalized_sine_coefficients (numpy.ndarray) – Matrix for which entry \((i,j)\) contains the unnormalized sine coefficient \(S_{lm}\)

Returns:

Tuple of two matrices, containing the normalized coefficients \(\bar{C}_{lm}\) (first) and \(\bar{S}_{lm}\) (second)

Return type:

tuple[numpy.ndarray, numpy.ndarray]

unnormalize_spherical_harmonic_coefficients(normalized_cosine_coefficients: numpy.ndarray[numpy.float64[m, n]], normalized_sine_coefficients: numpy.ndarray[numpy.float64[m, n]]) → tuple[numpy.ndarray[numpy.float64[m, n]], numpy.ndarray[numpy.float64[m, n]]]

Function to unnormalize spherical harmonic coefficients

Function to unnormalize spherical harmonic coefficients, using the equations provided in the legendre_normalization_factor() function.

Parameters:
  • normalized_cosine_coefficients (numpy.ndarray) – Matrix for which entry \((i,j)\) contains the normalized cosine coefficient \(\bar{C}_{lm}\)

  • normalized_sine_coefficients (numpy.ndarray) – Matrix for which entry \((i,j)\) contains the normalized sine coefficient \(\bar{S}_{lm}\)

Returns:

Tuple of two matrices, containing the unnormalized coefficients \({C}_{lm}\) (first) and \({S}_{lm}\) (second)

Return type:

tuple[numpy.ndarray, numpy.ndarray]

spherical_harmonic_coefficients_from_inertia(inertia_tensor: numpy.ndarray[numpy.float64[3, 3]], gravitational_parameter: float, reference_radius: float, output_normalized_coefficients: bool = True) → tuple[numpy.ndarray[numpy.float64[m, n]], numpy.ndarray[numpy.float64[m, n]], float]

Function to compute degree-two spherical harmonic coefficients from an inertia tensor

Function to compute degree-two spherical harmonic coefficients \(C_{20}\), \(C_{21}\), \(C_{22}\), \(S_{21}\), \(S_{22}\) and from an inertia tensor \(\mathbf{I}\), according to the following relation”

\[\begin{split}\mathbf{I}=M R^2\left(\left(\begin{array}{ccc} \frac{C_{20}}{3}-2 C_{22} & -2 S_{22} & -C_{21} \\ -2 S_{22} & \frac{C_{20}}{3}+2 C_{22} & -S_{21} \\ -C_{21} & -S_{21} & -\frac{2 C_{20}}{3} \end{array}\right)+\bar{I} \mathbf{1}_{3 \times 3}\right)\end{split}\]

with \(M\) the mass of the body, and \(R\) the reference radius of the spherical harmonic coefficients. The term \(\bar{I}\) is the mean moment of inertia. The spherical harmonic coefficients in the above matrix are unnormalized.

Parameters:
  • inertia_tensor (numpy.ndarray[numpy.float64[3, 3]]) – Full inertia tensor \(\mathbf{I}\) of the body for which spherical harmonic coefficients are to be computed.

  • gravitational_parameter (float) – Gravitational parameter \(\mu\) of the body for which spherical harmonic coefficients are to be computed.

  • reference_radius (float) – Reference radius w.r.t. which spherical harmonic coefficients are to be computed.

  • output_normalized_coefficients (bool, default=True) – Boolean denoting whether the coefficients computed are normalized (if true) or unnormalized (if false)

Returns:

Tuple containing the spherical harmonic coefficients \({C}_{lm}\) (first), \({S}_{lm}\) (second), and the mean moment of inertia (third). The degree-two coefficients are computed from the inertia tensor, the degree-one coefficients are set to zero (and \(C_{00}=0\))

Return type:

tuple[numpy.ndarray, numpy.ndarray, float]

transform_spherical_harmonic_coefficients_with_wigner_d(cosine_coefficients: numpy.ndarray[numpy.float64[m, n]], sine_coefficients: numpy.ndarray[numpy.float64[m, n]], wigner_matrices: list[numpy.ndarray[numpy.complex128[m, n]]], are_coefficients_normalized: bool = True) → tuple[numpy.ndarray[numpy.float64[m, n]], numpy.ndarray[numpy.float64[m, n]]]

Function to rotate spherical harmonic coefficients with precomputed Wigner D-matrices

Function to rotate real-valued spherical harmonic coefficients using precomputed Wigner D-matrices. The transformation follows the Wigner-D coefficient rotation formalism used by Boué [6]; see WignerDMatricesCache for the algorithm used to compute the Wigner D-matrices. For each degree \(l\), input coefficients \(C_{lk},S_{lk}\) are mapped to \(C'_{lm},S'_{lm}\) using the Wigner-D entries \(D^l_{m,k}\) as

\[\tilde{C}_{lm} = \eta_m\Re(D^l_{m,0})C_{l0} +\frac{1}{2}\sum_{k=1}^{l}\eta_{mk} \left[ \left((-1)^k\Re(D^l_{m,k})+\Re(D^l_{m,-k})\right)C_{lk} +\left((-1)^k\Im(D^l_{m,k})-\Im(D^l_{m,-k})\right)S_{lk} \right]\]
\[\tilde{S}_{lm} = \eta_m\Im(D^l_{m,0})C_{l0} +\frac{1}{2}\sum_{k=1}^{l}\eta_{mk} \left[ \left((-1)^k\Im(D^l_{m,k})+\Im(D^l_{m,-k})\right)C_{lk} +\left(-(-1)^k\Re(D^l_{m,k})+\Re(D^l_{m,-k})\right)S_{lk} \right]\]
\[C'_{lm}=(-1)^m(2-\delta_{0m})\tilde{C}_{lm},\qquad S'_{lm}=(-1)^{m+1}(2-\delta_{0m})\tilde{S}_{lm}.\]

For normalized coefficients, \(\eta_m=1\) when \(m=0\), \(\eta_m=1/\sqrt{2}\) when \(m>0\), and \(\eta_{mk}=\sqrt{2}\eta_m\). For unnormalized coefficients, \(\eta_m=\sqrt{(l-m)!/(l+m)!}\) and \(\eta_{mk}=\sqrt{(l+k)!/(l-k)!}\eta_m\).

Parameters:
  • cosine_coefficients (numpy.ndarray) – Matrix of cosine spherical harmonic coefficients.

  • sine_coefficients (numpy.ndarray) – Matrix of sine spherical harmonic coefficients.

  • wigner_matrices (list[numpy.ndarray]) – Complex Wigner D-matrices, one matrix per spherical harmonic degree.

  • are_coefficients_normalized (bool, default=True) – Boolean denoting whether the input coefficients are fully normalized.

Returns:

Tuple containing the rotated cosine and sine coefficient matrices.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

Classes

WignerDMatricesCache

Cache for Wigner D-matrices used to rotate spherical harmonic coefficients.

SphericalHarmonicTransformationCache

Cache for rotating spherical harmonic coefficients between reference frames.

class WignerDMatricesCache

Bases: pybind11_object

Cache for Wigner D-matrices used to rotate spherical harmonic coefficients.

This class computes and stores Wigner D-matrices up to a requested maximum degree for a rotation parameterized by Cayley-Klein parameters. These matrices are used in the spherical-harmonic coefficient transformation algorithms of Boué [6], using the angular-momentum conventions of Varshalovich et al. [35].

The implemented algorithm is the recursive Cayley-Klein formulation used by Boué [6]. With Cayley-Klein parameters \(a\) and \(b\), the recursion starts from

\[D^0_{0,0}=1\]

and the degree-one seed

\[\begin{split}\begin{aligned} D^1_{1,1}&=a^2,& D^1_{1,0}&=-\sqrt{2}a b^*,& D^1_{1,-1}&=(b^*)^2,\\ D^1_{0,1}&=\sqrt{2}ab,& D^1_{0,0}&=|a|^2-|b|^2,& D^1_{0,-1}&=-\sqrt{2}a^*b^*,\\ D^1_{-1,1}&=b^2,& D^1_{-1,0}&=\sqrt{2}a^*b,& D^1_{-1,-1}&=(a^*)^2 . \end{aligned}\end{split}\]

For \(l>1\), non-negative row orders are computed from

\[D^l_{m,k} = q^-_{lmk}D^1_{1,1}D^{l-1}_{m-1,k-1} +q^0_{lmk}D^1_{1,0}D^{l-1}_{m-1,k} +q^+_{lmk}D^1_{1,-1}D^{l-1}_{m-1,k+1}\]

with

\[q^-_{lmk}=\sqrt{\frac{(l+k)(l+k-1)}{(l+m)(l+m-1)}},\quad q^0_{lmk}=\sqrt{\frac{2(l+k)(l-k)}{(l+m)(l+m-1)}},\quad q^+_{lmk}=\sqrt{\frac{(l-k)(l-k-1)}{(l+m)(l+m-1)}} .\]

The remaining rows are filled from the conjugate symmetry

\[D^l_{m,k}=(-1)^{m-k}\left(D^l_{-m,-k}\right)^* .\]

Cartesian angular-momentum-operator values are computed from the cached matrices as

\[\hat{\mathcal{J}}_zD^l_{m,k}=-i mD^l_{m,k}\]

and, with \(A^+_{lm}=i\sqrt{(l(l+1)-m(m-1))/2}\,D^l_{m-1,k}\) and \(A^-_{lm}=-i\sqrt{(l(l+1)-m(m+1))/2}\,D^l_{m+1,k}\),

\[\hat{\mathcal{J}}_xD^l_{m,k}=\frac{A^-_{lm}-A^+_{lm}}{\sqrt{2}}, \qquad \hat{\mathcal{J}}_yD^l_{m,k}=i\frac{A^-_{lm}+A^+_{lm}}{\sqrt{2}} .\]
get_angular_momentum_operator_on_coefficient(self: tudatpy.kernel.astro.gravitation.WignerDMatricesCache, degree: int, original_order: int, new_order: int) → numpy.ndarray[numpy.complex128[3, 1]]

Returns the Cartesian angular-momentum operator applied to a Wigner D coefficient.

Parameters:
  • degree (int) – Spherical harmonic degree.

  • original_order (int) – Original spherical harmonic order.

  • new_order (int) – Transformed spherical harmonic order.

Returns:

Complex vector with the three Cartesian angular-momentum-operator components.

Return type:

numpy.ndarray

get_coefficient(self: tudatpy.kernel.astro.gravitation.WignerDMatricesCache, degree: int, original_order: int, new_order: int) → complex

Returns a single Wigner D-matrix coefficient.

Parameters:
  • degree (int) – Spherical harmonic degree.

  • original_order (int) – Original spherical harmonic order.

  • new_order (int) – Transformed spherical harmonic order.

Returns:

Requested Wigner D coefficient.

Return type:

complex

get_matrices(self: tudatpy.kernel.astro.gravitation.WignerDMatricesCache) → list[numpy.ndarray[numpy.complex128[m, n]]]

Returns all cached Wigner D-matrices.

Returns:

Complex Wigner D-matrices from degree zero up to the maximum degree.

Return type:

list[numpy.ndarray]

get_matrix(self: tudatpy.kernel.astro.gravitation.WignerDMatricesCache, degree: int) → numpy.ndarray[numpy.complex128[m, n]]

Returns the Wigner D-matrix for a single degree.

Parameters:

degree (int) – Spherical harmonic degree.

Returns:

Complex Wigner D-matrix for the requested degree.

Return type:

numpy.ndarray

update_matrices(self: tudatpy.kernel.astro.gravitation.WignerDMatricesCache, cayley_klein_a: complex | complex, cayley_klein_b: complex | complex) → None

Updates the cached Wigner D-matrices from Cayley-Klein parameters.

Parameters:
  • cayley_klein_a (complex) – Cayley-Klein parameter \(a\).

  • cayley_klein_b (complex) – Cayley-Klein parameter \(b\).

class SphericalHarmonicTransformationCache

Bases: pybind11_object

Cache for rotating spherical harmonic coefficients between reference frames.

This class stores Wigner D-matrices for a specified maximum degree/order and applies them to real-valued spherical harmonic coefficient matrices. The implementation follows the coefficient transformation approach of Boué [6].

A call to one of the update functions first computes the Cayley-Klein parameters of the requested frame rotation and updates the internal WignerDMatricesCache. A subsequent call to transform_coefficients() applies the cached Wigner D-matrices degree by degree to the real cosine/sine coefficient matrices.

For each degree \(l\) and target order \(m\geq 0\), define

\[\begin{split}\eta_m = \begin{cases} 1, & m=0\\ 1/\sqrt{2}, & m>0 \end{cases}\end{split}\]

for normalized coefficients, and \(\eta_m=\sqrt{(l-m)!/(l+m)!}\) for unnormalized coefficients. For \(k>0\), define \(\eta_{mk}=\sqrt{2}\eta_m\) for normalized coefficients and \(\eta_{mk}=\sqrt{(l+k)!/(l-k)!}\eta_m\) for unnormalized coefficients. The intermediate transformed coefficients are computed as

\[\tilde{C}_{lm} = \eta_m\Re(D^l_{m,0})C_{l0} +\frac{1}{2}\sum_{k=1}^{l}\eta_{mk} \left[ \left((-1)^k\Re(D^l_{m,k})+\Re(D^l_{m,-k})\right)C_{lk} +\left((-1)^k\Im(D^l_{m,k})-\Im(D^l_{m,-k})\right)S_{lk} \right]\]
\[\tilde{S}_{lm} = \eta_m\Im(D^l_{m,0})C_{l0} +\frac{1}{2}\sum_{k=1}^{l}\eta_{mk} \left[ \left((-1)^k\Im(D^l_{m,k})+\Im(D^l_{m,-k})\right)C_{lk} +\left(-(-1)^k\Re(D^l_{m,k})+\Re(D^l_{m,-k})\right)S_{lk} \right].\]

The returned real coefficients are then

\[C'_{lm}=(-1)^m(2-\delta_{0m})\tilde{C}_{lm},\qquad S'_{lm}=(-1)^{m+1}(2-\delta_{0m})\tilde{S}_{lm}.\]
get_wigner_matrices_cache(self: tudatpy.kernel.astro.gravitation.SphericalHarmonicTransformationCache) → tudatpy.kernel.astro.gravitation.WignerDMatricesCache

Returns the Wigner D-matrix cache used internally.

Returns:

Wigner D-matrix cache used by this spherical harmonic transformation cache.

Return type:

WignerDMatricesCache

set_update_partials(self: tudatpy.kernel.astro.gravitation.SphericalHarmonicTransformationCache, update_partials: bool = True) → None

Sets whether coefficient partials are updated by the cache.

Parameters:

update_partials (bool, default=True) – Boolean denoting whether coefficient partials should be updated.

transform_coefficients(self: tudatpy.kernel.astro.gravitation.SphericalHarmonicTransformationCache, cosine_coefficients: numpy.ndarray[numpy.float64[m, n]], sine_coefficients: numpy.ndarray[numpy.float64[m, n]], are_coefficients_normalized: bool = True) → tuple[numpy.ndarray[numpy.float64[m, n]], numpy.ndarray[numpy.float64[m, n]]]

Rotates spherical harmonic coefficients using the current cache orientation.

Parameters:
  • cosine_coefficients (numpy.ndarray) – Matrix of cosine spherical harmonic coefficients.

  • sine_coefficients (numpy.ndarray) – Matrix of sine spherical harmonic coefficients.

  • are_coefficients_normalized (bool, default=True) – Boolean denoting whether the input coefficients are fully normalized.

Returns:

Tuple containing the rotated cosine and sine coefficient matrices.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

update_from_313_euler_angles(self: tudatpy.kernel.astro.gravitation.SphericalHarmonicTransformationCache, first_z_rotation: float, x_rotation: float, second_z_rotation: float) → None

Updates the transformation cache from 3-1-3 Euler angles.

Parameters:
  • first_z_rotation (float) – First rotation angle about the z-axis, in radians.

  • x_rotation (float) – Rotation angle about the x-axis, in radians.

  • second_z_rotation (float) – Second rotation angle about the z-axis, in radians.

update_from_cayley_klein_parameters(self: tudatpy.kernel.astro.gravitation.SphericalHarmonicTransformationCache, cayley_klein_a: complex | complex, cayley_klein_b: complex | complex) → None

Updates the transformation cache from Cayley-Klein parameters.

Parameters:
  • cayley_klein_a (complex) – Cayley-Klein parameter \(a\).

  • cayley_klein_b (complex) – Cayley-Klein parameter \(b\).

update_from_quaternion(self: tudatpy.kernel.astro.gravitation.SphericalHarmonicTransformationCache, rotation_quaternion: numpy.ndarray[numpy.float64[4, 1]]) → None

Updates the transformation cache from a quaternion.

Parameters:

rotation_quaternion (numpy.ndarray) – Quaternion as a scalar-first vector [w, x, y, z].