choclo.legendre.associated_function_fully#
- choclo.legendre.associated_function_fully(x, max_degree, p)[source]#
Fully-normalized associated Legendre functions up to maximum degree.
The associated Legendre functions functions \(P_n^m(x)\) are solutions to Legendre’s equation, with \(n\) (the degree) and \(m\) (the order) being integers and \(0 \le m \le n\). The full normalization is applied to the functions to constrain their value range and avoid overflows. This normalization if often used in gravity field models.
We calculate their values using the recursive relations defined in [Alken2022] but with the definition of the normalization from [Hofmann-Wellenhof2006]. Being recursive, it’s not possible to calculate only the values for a specific degree and order. All values up to the desired degree are always calculated.
- Parameters:
- x
float The argument of \(P_n^m(x)\). Must be in the range [-1, 1].
- max_degree
int The maximum degree \(n\) for the calculation.
- p
numpy.array A 2D array with shape
(max_degree + 1, max_degree + 1)that will be filled in place with the output values. The rows of the array correspond to the degree \(n\) and the columns to the order \(m\). Thus,p[n, m]corresponds to \(P_n^m(x)\). Elements wherem > nare not filled out and will retain their original values.
- x
Notes
The functions \(P_n^m(x)\) are solutions to Legendre’s differential equation
\[\frac{d}{d x} \left[ \left(1 - x^2\right) \frac{d}{d x} P_n^m(x) \right] + \left[ n (n + 1) - \frac{m^2}{1 - x^2} \right] P_n^m(x) = 0,\]which has non-trivial and non-singular solutions in the [-1, 1] range when \(n\) and \(m\) are integers and \(0 \le m \le n\).
In practice, their amplitudes tend to increase dramatically with the degree \(n\), and so normalization techniques are often employed to keep amplitudes to reasonable values. In gravimetry and geodesy, it’s common to employ full normalization
\[F_n^m = \sqrt{2(2n + 1)\dfrac{(n - m)!}{(n + m)!}},\]The normalization factor \(F_n^m\) multiplies the \(P_n^m\). In practice, the equation above is not used. Instead, the Legendre function is evaluated using recursive equations specifically for the normalized version.
Note
Does not implement the Condon-Shortly phase element.
Note
This function uses the scaling scheme of [Holmes2002] and produces accurate results until degree and order 2800.
References