7.24.2 Associated Legendre Polynomials and Spherical Harmonics

The following functions compute the associated Legendre polynomials P_l^m(x) which are solutions of the differential equation

(1 - x^2) d^2 P_l^m(x) / dx^2 P_l^m(x) - 2x d/dx P_l^m(x) +
( l(l+1) - m^2 / (1 - x^2) ) P_l^m(x) = 0

where the degree l and order m satisfy 0 \le l and 0 \le m \le l. The functions P_l^m(x) grow combinatorially with l and can overflow for l larger than about 150. Alternatively, one may calculate normalized associated Legendre polynomials. There are a number of different normalization conventions, and these functions can be stably computed up to degree and order 2700. The following normalizations are provided:

Schmidt semi-normalization

Schmidt semi-normalized associated Legendre polynomials are often used in the magnetics community and are defined as

S_l^0(x) = P_l^0(x)
S_l^m(x) = (-1)^m \sqrt((2(l-m)! / (l+m)!)) P_l^m(x), m > 0 

The factor of (-1)^m is called the Condon-Shortley phase factor and can be excluded if desired by setting the parameter csphase = 1 in the functions below.

Spherical Harmonic Normalization

The associated Legendre polynomials suitable for calculating spherical harmonics are defined as

Y_l^m(x) = (-1)^m \sqrt((2l + 1) * (l-m)! / (4 \pi) / (l+m)!) P_l^m(x)

where again the phase factor (-1)^m can be included or excluded if desired.

Full Normalization

The fully normalized associated Legendre polynomials are defined as

N_l^m(x) = (-1)^m \sqrt((l + 1/2) * (l-m)! / (l+m)!) P_l^m(x)

and have the property

\int_(-1)^1 ( N_l^m(x) )^2 dx = 1

The normalized associated Legendre routines below use a recurrence relation which is stable up to a degree and order of about 2700. Beyond this, the computed functions could suffer from underflow leading to incorrect results. Routines are provided to compute first and second derivatives dP_l^m(x)/dx and d^2 P_l^m(x)/dx^2 as well as their alternate versions d P_l^m(\cos{\theta})/d\theta and d^2 P_l^m(\cos{\theta})/d\theta^2. While there is a simple scaling relationship between the two forms, the derivatives involving \theta are heavily used in spherical harmonic expansions and so these routines are also provided.

In the functions below, a parameter of type gsl_sf_legendre_t specifies the type of normalization to use. The possible values are

GSL_SF_LEGENDRE_NONE

This specifies the computation of the unnormalized associated Legendre polynomials P_l^m(x).

GSL_SF_LEGENDRE_SCHMIDT

This specifies the computation of the Schmidt semi-normalized associated Legendre polynomials S_l^m(x).

GSL_SF_LEGENDRE_SPHARM

This specifies the computation of the spherical harmonic associated Legendre polynomials Y_l^m(x).

GSL_SF_LEGENDRE_FULL

This specifies the computation of the fully normalized associated Legendre polynomials N_l^m(x).

Function: int gsl_sf_legendre_array (const gsl_sf_legendre_t norm, const size_t lmax, const double x, double result_array[])

Function: int gsl_sf_legendre_array_e (const gsl_sf_legendre_t norm, const size_t lmax, const double x, const double csphase, double result_array[])

These functions calculate all normalized associated Legendre polynomials for 0 \le l \le lmax and 0 \le m \le l for |x| <= 1. The norm parameter specifies which normalization is used. The normalized P_l^m(x) values are stored in result_array, whose minimum size can be obtained from calling gsl_sf_legendre_array_n. The array index of P_l^m(x) is obtained from calling gsl_sf_legendre_array_index(l, m). To include or exclude the Condon-Shortley phase factor of (-1)^m, set the parameter csphase to either -1 or 1 respectively in the _e function. This factor is included by default.

Function: int gsl_sf_legendre_deriv_array (const gsl_sf_legendre_t norm, const size_t lmax, const double x, double result_array[], double result_deriv_array[])

Function: int gsl_sf_legendre_deriv_array_e (const gsl_sf_legendre_t norm, const size_t lmax, const double x, const double csphase, double result_array[], double result_deriv_array[])

These functions calculate all normalized associated Legendre functions and their first derivatives up to degree lmax for |x| < 1. The parameter norm specifies the normalization used. The normalized P_l^m(x) values and their derivatives dP_l^m(x)/dx are stored in result_array and result_deriv_array respectively. To include or exclude the Condon-Shortley phase factor of (-1)^m, set the parameter csphase to either -1 or 1 respectively in the _e function. This factor is included by default.

Function: int gsl_sf_legendre_deriv_alt_array (const gsl_sf_legendre_t norm, const size_t lmax, const double x, double result_array[], double result_deriv_array[])

Function: int gsl_sf_legendre_deriv_alt_array_e (const gsl_sf_legendre_t norm, const size_t lmax, const double x, const double csphase, double result_array[], double result_deriv_array[])

These functions calculate all normalized associated Legendre functions and their (alternate) first derivatives up to degree lmax for |x| < 1. The normalized P_l^m(x) values and their derivatives dP_l^m(\cos{\theta})/d\theta are stored in result_array and result_deriv_array respectively. To include or exclude the Condon-Shortley phase factor of (-1)^m, set the parameter csphase to either -1 or 1 respectively in the _e function. This factor is included by default.

Function: int gsl_sf_legendre_deriv2_array (const gsl_sf_legendre_t norm, const size_t lmax, const double x, double result_array[], double result_deriv_array[], double result_deriv2_array[])

Function: int gsl_sf_legendre_deriv2_array_e (const gsl_sf_legendre_t norm, const size_t lmax, const double x, const double csphase, double result_array[], double result_deriv_array[], double result_deriv2_array[])

These functions calculate all normalized associated Legendre functions and their first and second derivatives up to degree lmax for |x| < 1. The parameter norm specifies the normalization used. The normalized P_l^m(x), their first derivatives dP_l^m(x)/dx, and their second derivatives d^2 P_l^m(x)/dx^2 are stored in result_array, result_deriv_array, and result_deriv2_array respectively. To include or exclude the Condon-Shortley phase factor of (-1)^m, set the parameter csphase to either -1 or 1 respectively in the _e function. This factor is included by default.

Function: int gsl_sf_legendre_deriv2_alt_array (const gsl_sf_legendre_t norm, const size_t lmax, const double x, double result_array[], double result_deriv_array[], double result_deriv2_array[])

Function: int gsl_sf_legendre_deriv2_alt_array_e (const gsl_sf_legendre_t norm, const size_t lmax, const double x, const double csphase, double result_array[], double result_deriv_array[], double result_deriv2_array[])

These functions calculate all normalized associated Legendre functions and their (alternate) first and second derivatives up to degree lmax for |x| < 1. The parameter norm specifies the normalization used. The normalized P_l^m(x), their first derivatives dP_l^m(\cos{\theta})/d\theta, and their second derivatives d^2 P_l^m(\cos{\theta})/d\theta^2 are stored in result_array, result_deriv_array, and result_deriv2_array respectively. To include or exclude the Condon-Shortley phase factor of (-1)^m, set the parameter csphase to either -1 or 1 respectively in the _e function. This factor is included by default.

Function: size_t gsl_sf_legendre_array_n (const size_t lmax)

This function returns the minimum array size for maximum degree lmax needed for the array versions of the associated Legendre functions. Size is calculated as the total number of P_l^m(x) functions, plus extra space for precomputing multiplicative factors used in the recurrence relations.

Function: size_t gsl_sf_legendre_array_index (const size_t l, const size_t m)

This function returns the index into result_array, result_deriv_array, or result_deriv2_array corresponding to P_l^m(x), P_l^{'m}(x), or P_l^{''m}(x). The index is given by l(l+1)/2 + m.

Function: double gsl_sf_legendre_Plm (int l, int m, double x)

Function: int gsl_sf_legendre_Plm_e (int l, int m, double x, gsl_sf_result * result)

These routines compute the associated Legendre polynomial P_l^m(x) for m >= 0, l >= m, |x| <= 1.

Function: double gsl_sf_legendre_sphPlm (int l, int m, double x)

Function: int gsl_sf_legendre_sphPlm_e (int l, int m, double x, gsl_sf_result * result)

These routines compute the normalized associated Legendre polynomial \sqrt{(2l+1)/(4\pi)} \sqrt{(l-m)!/(l+m)!} P_l^m(x) suitable for use in spherical harmonics. The parameters must satisfy m >= 0, l >= m, |x| <= 1. Theses routines avoid the overflows that occur for the standard normalization of P_l^m(x).

Function: int gsl_sf_legendre_Plm_array (int lmax, int m, double x, double result_array[])

Function: int gsl_sf_legendre_Plm_deriv_array (int lmax, int m, double x, double result_array[], double result_deriv_array[])

These functions are now deprecated and will be removed in a future release; see gsl_sf_legendre_array and gsl_sf_legendre_deriv_array.

Function: int gsl_sf_legendre_sphPlm_array (int lmax, int m, double x, double result_array[])

Function: int gsl_sf_legendre_sphPlm_deriv_array (int lmax, int m, double x, double result_array[], double result_deriv_array[])

These functions are now deprecated and will be removed in a future release; see gsl_sf_legendre_array and gsl_sf_legendre_deriv_array.

Function: int gsl_sf_legendre_array_size (const int lmax, const int m)

This function is now deprecated and will be removed in a future release.