# 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 Function to normalize spherical harmonic coefficients Function to unnormalize spherical harmonic coefficients Function to compute degree-two spherical harmonic coefficients from an inertia tensor
legendre_normalization_factor(degree: int, order: int) #

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:
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 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: