.. index::

   single: Legendre polynomials

   single: Legendre functions

   single: spherical harmonics

   single: conical functions

   single: hyperbolic space

The Legendre Functions and Legendre Polynomials are described in

Abramowitz & Stegun, Chapter 8.  These functions are declared in 

the header file :file:`gsl_sf_legendre.h`.

Legendre Polynomials

--------------------

.. function:: double gsl_sf_legendre_P1 (double x)

              double gsl_sf_legendre_P2 (double x)

              double gsl_sf_legendre_P3 (double x)

              int gsl_sf_legendre_P1_e (double x, gsl_sf_result * result)

              int gsl_sf_legendre_P2_e (double x, gsl_sf_result * result)

              int gsl_sf_legendre_P3_e (double x, gsl_sf_result * result)

   These functions evaluate the Legendre polynomials

   :math:`P_l(x)` using explicit representations for :math:`l = 1, 2, 3`.

.. Exceptional Return Values: none

.. function:: double gsl_sf_legendre_Pl (int l, double x)

              int gsl_sf_legendre_Pl_e (int l, double x, gsl_sf_result * result)

   These functions evaluate the Legendre polynomial :math:`P_l(x)`

   for a specific value of :data:`l`, :data:`x` subject to :math:`l \ge 0` and

   :math:`|x| \le 1`.

.. Exceptional Return Values: GSL_EDOM

.. function:: int gsl_sf_legendre_Pl_array (int lmax, double x, double result_array[])

              int gsl_sf_legendre_Pl_deriv_array (int lmax, double x, double result_array[], double result_deriv_array[])

   These functions compute arrays of Legendre polynomials

   :math:`P_l(x)` and derivatives :math:`dP_l(x)/dx`

   for :math:`l = 0, \dots, lmax` and :math:`|x| \le 1`.

.. Exceptional Return Values: GSL_EDOM

.. function:: double gsl_sf_legendre_Q0 (double x)

              int gsl_sf_legendre_Q0_e (double x, gsl_sf_result * result)

   These routines compute the Legendre function :math:`Q_0(x)` for

   :math:`x > -1` and :math:`x \ne 1`.

.. Exceptional Return Values: GSL_EDOM

.. function:: double gsl_sf_legendre_Q1 (double x)

              int gsl_sf_legendre_Q1_e (double x, gsl_sf_result * result)

   These routines compute the Legendre function :math:`Q_1(x)` for

   :math:`x > -1` and :math:`x \ne 1`.

.. Exceptional Return Values: GSL_EDOM

.. function:: double gsl_sf_legendre_Ql (int l, double x)

              int gsl_sf_legendre_Ql_e (int l, double x, gsl_sf_result * result)

   These routines compute the Legendre function :math:`Q_l(x)` for

   :math:`x > -1`, :math:`x \ne 1` and :math:`l \ge 0`.

.. Exceptional Return Values: GSL_EDOM

Associated Legendre Polynomials and Spherical Harmonics

-------------------------------------------------------

The following functions compute the associated Legendre polynomials

:math:`P_l^m(x)` which are solutions of the differential equation

.. only:: not texinfo

   .. math:: (1 - x^2) {d^2 \over dx^2} P_l^m(x) - 2x {d \over dx} P_l^m(x) +

             \left( l(l+1) - {m^2 \over 1 - x^2} \right) P_l^m(x) = 0

.. only:: texinfo

   ::

      (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 :math:`l` and order :math:`m` satisfy :math:`0 \le l` and

:math:`0 \le m \le l`.

The functions :math:`P_l^m(x)` grow combinatorially with

:math:`l` and can overflow for :math:`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

  .. only:: not texinfo

     .. math::

        S_l^0(x) &= P_l^0(x) \\

        S_l^m(x) &= (-1)^m \sqrt{2 {(l-m)! \over (l+m)!}} P_l^m(x), m > 0 

  .. only:: texinfo

     ::

        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 :math:`(-1)^m` is called the Condon-Shortley phase

  factor and can be excluded if desired by setting the parameter

  :code:`csphase = 1` in the functions below.

* Spherical Harmonic Normalization

  The associated Legendre polynomials suitable for calculating spherical

  harmonics are defined as

  .. only:: not texinfo

     .. math:: Y_l^m(x) = (-1)^m \sqrt{{2l + 1 \over 4 \pi} {(l-m)! \over (l+m)!}} P_l^m(x)

  .. only:: texinfo

     ::

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

  where again the phase factor :math:`(-1)^m` can be included or excluded

  if desired.

* Full Normalization

  The fully normalized associated Legendre polynomials are defined as

  .. only:: not texinfo

     .. math:: N_l^m(x) = (-1)^m \sqrt{(l + {1 \over 2}) {(l-m)! \over (l+m)!}} P_l^m(x)

  .. only:: texinfo

     ::

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

  and have the property

  .. math:: \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

:math:`dP_l^m(x)/dx` and :math:`d^2 P_l^m(x)/dx^2` as well as their alternate

versions :math:`d P_l^m(\cos{\theta})/d\theta` and

:math:`d^2 P_l^m(\cos{\theta})/d\theta^2`. While there is a simple

scaling relationship between the two forms, the derivatives

involving :math:`\theta` are heavily used in spherical harmonic

expansions and so these routines are also provided.

In the functions below, a parameter of type :type:`gsl_sf_legendre_t`

specifies the type of normalization to use. The possible values are

.. type:: gsl_sf_legendre_t

   ================================== ===============================================================================

   Value                              Description

   ================================== ===============================================================================

   :code:`GSL_SF_LEGENDRE_NONE`       The unnormalized associated Legendre polynomials :math:`P_l^m(x)`

   :code:`GSL_SF_LEGENDRE_SCHMIDT`    The Schmidt semi-normalized associated Legendre polynomials :math:`S_l^m(x)`

   :code:`GSL_SF_LEGENDRE_SPHARM`     The spherical harmonic associated Legendre polynomials :math:`Y_l^m(x)`

   :code:`GSL_SF_LEGENDRE_FULL`       The fully normalized associated Legendre polynomials :math:`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[])

              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 :math:`0 \le l \le lmax` and

   :math:`0 \le m \le l` for :math:`|x| \le 1`.

   The :data:`norm` parameter specifies which normalization is used.

   The normalized :math:`P_l^m(x)` values are stored in :data:`result_array`, whose

   minimum size can be obtained from calling :func:`gsl_sf_legendre_array_n`.

   The array index of :math:`P_l^m(x)` is obtained from calling

   :code:`gsl_sf_legendre_array_index(l, m)`. To include or exclude

   the Condon-Shortley phase factor of :math:`(-1)^m`, set the parameter

   :data:`csphase` to either :math:`-1` or :math:`1` respectively in the

   :code:`_e` function. This factor is excluded 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[])

              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 :data:`lmax` for

   :math:`|x| < 1`.

   The parameter :data:`norm` specifies the normalization used. The

   normalized :math:`P_l^m(x)` values and their derivatives

   :math:`dP_l^m(x)/dx` are stored in :data:`result_array` and

   :data:`result_deriv_array` respectively.

   To include or exclude

   the Condon-Shortley phase factor of :math:`(-1)^m`, set the parameter

   :data:`csphase` to either :math:`-1` or :math:`1` respectively in the

   :code:`_e` function. This factor is excluded 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[])

              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 :data:`lmax` for

   :math:`|x| < 1`.

   The normalized :math:`P_l^m(x)` values and their derivatives

   :math:`dP_l^m(\cos{\theta})/d\theta` are stored in :data:`result_array` and

   :data:`result_deriv_array` respectively.

   To include or exclude

   the Condon-Shortley phase factor of :math:`(-1)^m`, set the parameter

   :data:`csphase` to either :math:`-1` or :math:`1` respectively in the

   :code:`_e` function. This factor is excluded 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[])

              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 :data:`lmax` for

   :math:`|x| < 1`.

   The parameter :data:`norm` specifies the normalization used. The

   normalized :math:`P_l^m(x)`, their first derivatives

   :math:`dP_l^m(x)/dx`, and their second derivatives

   :math:`d^2 P_l^m(x)/dx^2` are stored in :data:`result_array`,

   :data:`result_deriv_array`, and :data:`result_deriv2_array` respectively.

   To include or exclude

   the Condon-Shortley phase factor of :math:`(-1)^m`, set the parameter

   :data:`csphase` to either :math:`-1` or :math:`1` respectively in the

   :code:`_e` function. This factor is excluded 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[])

              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

   :data:`lmax` for

   :math:`|x| < 1`.

   The parameter :data:`norm` specifies the normalization used. The

   normalized :math:`P_l^m(x)`, their first derivatives

   :math:`dP_l^m(\cos{\theta})/d\theta`, and their second derivatives

   :math:`d^2 P_l^m(\cos{\theta})/d\theta^2` are stored in :data:`result_array`,

   :data:`result_deriv_array`, and :data:`result_deriv2_array` respectively.

   To include or exclude

   the Condon-Shortley phase factor of :math:`(-1)^m`, set the parameter

   :data:`csphase` to either :math:`-1` or :math:`1` respectively in the

   :code:`_e` function. This factor is excluded by default.

.. function:: size_t gsl_sf_legendre_array_n (const size_t lmax)

   This function returns the minimum array size for maximum degree :data:`lmax`

   needed for the array versions of the associated Legendre functions.

   Size is calculated as the total number of :math:`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 :data:`result_array`,

   :data:`result_deriv_array`, or :data:`result_deriv2_array` corresponding

   to :math:`P_l^m(x)`, :math:`P_l^{'m}(x)`, or :math:`P_l^{''m}(x)`. The

   index is given by :math:`l(l+1)/2 + m`.

.. function:: double gsl_sf_legendre_Plm (int l, int m, double x)

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

   These routines compute the associated Legendre polynomial

   :math:`P_l^m(x)` for :math:`m \ge 0`,

   :math:`l \ge m`, and :math:`|x| \le 1`.

.. Exceptional Return Values: GSL_EDOM, GSL_EOVRFLW

.. function:: double gsl_sf_legendre_sphPlm (int l, int m, double x)

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

   These routines compute the normalized associated Legendre polynomial

   :math:`\sqrt{(2l+1)/(4\pi)} \sqrt{(l-m)!/(l+m)!} P_l^m(x)` suitable

   for use in spherical harmonics.  The parameters must satisfy :math:`m \ge 0`,

   :math:`l \ge m`, and :math:`|x| \le 1`.

   These routines avoid the overflows

   that occur for the standard normalization of :math:`P_l^m(x)`.

.. Exceptional Return Values: GSL_EDOM

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

              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 :func:`gsl_sf_legendre_array` and

   :func:`gsl_sf_legendre_deriv_array`.

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

              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 :func:`gsl_sf_legendre_array` and

   :func:`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.

Conical Functions

-----------------

The Conical Functions :math:`P^\mu_{-(1/2)+i\lambda}(x)`

and :math:`Q^\mu_{-(1/2)+i\lambda}`

are described in Abramowitz & Stegun, Section 8.12.

.. function:: double gsl_sf_conicalP_half (double lambda, double x)

              int gsl_sf_conicalP_half_e (double lambda, double x, gsl_sf_result * result)

   These routines compute the irregular Spherical Conical Function

   :math:`P^{1/2}_{-1/2 + i \lambda}(x)` for :math:`x > -1`.

.. Exceptional Return Values: GSL_EDOM

.. function:: double gsl_sf_conicalP_mhalf (double lambda, double x)

              int gsl_sf_conicalP_mhalf_e (double lambda, double x, gsl_sf_result * result)

   These routines compute the regular Spherical Conical Function

   :math:`P^{-1/2}_{-1/2 + i \lambda}(x)` for :math:`x > -1`.

.. Exceptional Return Values: GSL_EDOM

.. function:: double gsl_sf_conicalP_0 (double lambda, double x)

              int gsl_sf_conicalP_0_e (double lambda, double x, gsl_sf_result * result)

   These routines compute the conical function

   :math:`P^0_{-1/2 + i \lambda}(x)` for :math:`x > -1`.

.. Exceptional Return Values: GSL_EDOM

.. function:: double gsl_sf_conicalP_1 (double lambda, double x)

              int gsl_sf_conicalP_1_e (double lambda, double x, gsl_sf_result * result)

   These routines compute the conical function 

   :math:`P^1_{-1/2 + i \lambda}(x)` for :math:`x > -1`.

.. Exceptional Return Values: GSL_EDOM

.. function:: double gsl_sf_conicalP_sph_reg (int l, double lambda, double x)

              int gsl_sf_conicalP_sph_reg_e (int l, double lambda, double x, gsl_sf_result * result)

   These routines compute the Regular Spherical Conical Function

   :math:`P^{-1/2-l}_{-1/2 + i \lambda}(x)`

   for :math:`x > -1` and :math:`l \ge -1`.

.. Exceptional Return Values: GSL_EDOM

.. function:: double gsl_sf_conicalP_cyl_reg (int m, double lambda, double x)

              int gsl_sf_conicalP_cyl_reg_e (int m, double lambda, double x, gsl_sf_result * result)

   These routines compute the Regular Cylindrical Conical Function

   :math:`P^{-m}_{-1/2 + i \lambda}(x)`

   for :math:`x > -1` and :math:`m \ge -1`.

.. Exceptional Return Values: GSL_EDOM

Radial Functions for Hyperbolic Space

-------------------------------------

The following spherical functions are specializations of Legendre

functions which give the regular eigenfunctions of the Laplacian on a

3-dimensional hyperbolic space :math:`H^3`.  Of particular interest is

the flat limit, :math:`\lambda \to \infty`, :math:`\eta \to 0`,

:math:`\lambda\eta` fixed.

.. function:: double gsl_sf_legendre_H3d_0 (double lambda, double eta)

              int gsl_sf_legendre_H3d_0_e (double lambda, double eta, gsl_sf_result * result)

   These routines compute the zeroth radial eigenfunction of the Laplacian on the

   3-dimensional hyperbolic space,

   .. math:: L^{H3d}_0(\lambda,\eta) := {\sin(\lambda\eta) \over \lambda\sinh(\eta)}

   for :math:`\eta \ge 0`.

   In the flat limit this takes the form

   :math:`L^{H3d}_0(\lambda,\eta) = j_0(\lambda\eta)`.

.. Exceptional Return Values: GSL_EDOM

.. function:: double gsl_sf_legendre_H3d_1 (double lambda, double eta)

              int gsl_sf_legendre_H3d_1_e (double lambda, double eta, gsl_sf_result * result)

   These routines compute the first radial eigenfunction of the Laplacian on

   the 3-dimensional hyperbolic space,

   .. math:: L^{H3d}_1(\lambda,\eta) := {1\over\sqrt{\lambda^2 + 1}} {\left(\sin(\lambda \eta)\over \lambda \sinh(\eta)\right)} \left(\coth(\eta) - \lambda \cot(\lambda\eta)\right)

   for :math:`\eta \ge 0`

   In the flat limit this takes the form 

   :math:`L^{H3d}_1(\lambda,\eta) = j_1(\lambda\eta)`.

.. Exceptional Return Values: GSL_EDOM

.. function:: double gsl_sf_legendre_H3d (int l, double lambda, double eta)

              int gsl_sf_legendre_H3d_e (int l, double lambda, double eta, gsl_sf_result * result)

   These routines compute the :data:`l`-th radial eigenfunction of the

   Laplacian on the 3-dimensional hyperbolic space :math:`\eta \ge 0` and

   :math:`l \ge 0`.

   In the flat limit this takes the form

   :math:`L^{H3d}_l(\lambda,\eta) = j_l(\lambda\eta)`.

.. Exceptional Return Values: GSL_EDOM

.. function:: int gsl_sf_legendre_H3d_array (int lmax, double lambda, double eta, double result_array[])

   This function computes an array of radial eigenfunctions

   :math:`L^{H3d}_l( \lambda, \eta)`

   for :math:`0 \le l \le lmax`.

.. Exceptional Return Values: