choclo.legendre.associated_function_derivative

choclo.legendre.associated_function_derivative#

choclo.legendre.associated_function_derivative(max_degree, p, dp)[source]#

Theta derivative of the 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\).

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 p argument in a subsequent call.

The output is filled in place in the parameter dp so 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.

Warning

This function does not implement normalization and should not be used beyond degree 13 because they will overflow 64-bit float range. Use choclo.legendre.associated_function_schmidt_derivative and choclo.legendre.associated_function_fully_derivative instead.

Parameters:
max_degreeint

The maximum degree \(n\) for the calculation.

pnumpy.ndarray

A 2D array with shape (max_degree + 1, max_degree + 1) with values of \(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 where m > n are ignored. See choclo.legendre.associated_function.

dpnumpy.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 where m > n are not filled out and will retain their original values.

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.

Note

Does not implement the Condon-Shortly phase element.

References

[Alken2022]