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

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:
  • tensor (inertia) – 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 of two matrices, containing the spherical harmonic coefficients \({C}_{lm}\) (first) and \({S}_{lm}\) (second) up to degree and order 2. 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]