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 postprocessing steps.
Functions#

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

Function to unnormalize spherical harmonic coefficients 

Function to compute degreetwo 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)(lm)!)}{(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\).
 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:
 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:
 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 degreetwo spherical harmonic coefficients from an inertia tensor
Function to compute degreetwo 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 degreetwo coefficients are computed from the inertia tensor, the degreeone coefficients are set to zero (and \(C_{00}=0\))
 Return type: