choclo.legendre.associated_function_schmidt_derivative#
- choclo.legendre.associated_function_schmidt_derivative(max_degree, p, dp)[source]#
Theta derivatives of the Schmidt-normalized associated Legendre functions.
Calculates the derivative
\[\dfrac{\partial P_n^m}{\partial\theta}(\cos\theta),\]of the associated Legendre function \(P_n^m(\cos\theta)\), with \(n\) (the degree) and \(m\) (the order) being integers and \(0 \le m \le n\). Assumes that the Legendre function is Schmidt-normalized.
Implements the recursive relations defined in [Alken2022], which use calculated values of \(P_n^m\) to calculate its derivatives. Since the calculations are 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.
Higher-order derivatives can be calculated by passing the output of this function as the
pargument in a subsequent call.The output is filled in place in the parameter
dpso that the users can control the memory allocation. In spherical harmonics, this function if often called in a loop and so reusing memory can save computation time.- Parameters:
- max_degree
int The maximum degree \(n\) for the calculation.
- p
numpy.ndarray A 2D array with shape
(max_degree + 1, max_degree + 1)with values of the Schmidt-normalized \(P_n^m(\cos\theta)\). 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(\cos\theta)\). Elements wherem > nare ignored. Seechoclo.legendre.associated_function_schmidt.- dp
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,dp[n, m]corresponds to \(\partial P_n^m(\cos\theta) / \partial\theta\). Elements wherem > nare not filled out and will retain their original values.
- max_degree
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 spherical harmonics, these functions are usually evaluated as \(P_n^m(\cos\theta)\), in which \(\theta\) is the geocentric colatitude with range [0, 180] degrees. It’s often required to know the derivative of the \(P_n^m\) with respect to \(\theta\), which is what this function calculates.
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 geomagnetism, it’s common to employ Schmidt normalization
\[S_n^m = \sqrt{(2 - \delta_{m,0})\dfrac{(n - m)!}{(n + m)!}},\]in which \(\delta_{m,0}\) is the Kronecker delta function. In practice, the equation above is not used. Instead, the derivative is evaluated using recursive equations specifically for the normalized version.
Note
Does not implement the Condon-Shortly phase element.
Note
First and second order derivatives are tested against the Legendre differential equation and produce accurate results until degree and order 2800. Higher order derivatives have not been tested.
References