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¶
|
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 |
|
|
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\).
- 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:
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:
- 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é [7]; see
WignerDMatricesCachefor 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:
Classes¶
Cache for Wigner D-matrices used to rotate spherical harmonic coefficients. |
|
Cache for rotating spherical harmonic coefficients between reference frames. |
- class WignerDMatricesCache¶
Bases:
pybind11_objectCache 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é [7], using the angular-momentum conventions of Varshalovich et al. [41].
The implemented algorithm is the recursive Cayley-Klein formulation used by Boué [7]. 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:
- Returns:
Complex vector with the three Cartesian angular-momentum-operator components.
- Return type:
- get_coefficient(self: tudatpy.kernel.astro.gravitation.WignerDMatricesCache, degree: int, original_order: int, new_order: int) complex¶
Returns a single Wigner D-matrix coefficient.
- 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:
- 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:
- class SphericalHarmonicTransformationCache¶
Bases:
pybind11_objectCache 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é [7].
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 totransform_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:
- 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:
- 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.
- 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.
- 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].