GNU Scientific Library – Reference Manual: Associated Legendre Polynomials and Spherical Harmonics

Next: Conical Functions, Previous: Legendre Polynomials, Up: Legendre Functions and Spherical Harmonics [Index]

#### 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.

Next: Conical Functions, Previous: Legendre Polynomials, Up: Legendre Functions and Spherical Harmonics [Index]