path: root/gsl-1.9/doc/specfunc-legendre.texi

@cindex Legendre functions
@cindex spherical harmonics
@cindex conical functions
@cindex 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}.

@menu
* Legendre Polynomials::        
* Associated Legendre Polynomials and Spherical Harmonics::  
* Conical Functions::           
* Radial Functions for Hyperbolic Space::  
@end menu

@node Legendre Polynomials
@subsection Legendre Polynomials

@deftypefun double gsl_sf_legendre_P1 (double @var{x})
@deftypefunx double gsl_sf_legendre_P2 (double @var{x})
@deftypefunx double gsl_sf_legendre_P3 (double @var{x})
@deftypefunx int gsl_sf_legendre_P1_e (double @var{x}, gsl_sf_result * @var{result})
@deftypefunx int gsl_sf_legendre_P2_e (double @var{x}, gsl_sf_result * @var{result})
@deftypefunx int gsl_sf_legendre_P3_e (double @var{x}, gsl_sf_result * @var{result})
These functions evaluate the Legendre polynomials
@c{$P_l(x)$} 
@math{P_l(x)} using explicit
representations for @math{l=1, 2, 3}.
@comment Exceptional Return Values: none
@end deftypefun

@deftypefun double gsl_sf_legendre_Pl (int @var{l}, double @var{x})
@deftypefunx int gsl_sf_legendre_Pl_e (int @var{l}, double @var{x}, gsl_sf_result * @var{result})
These functions evaluate the Legendre polynomial @c{$P_l(x)$} 
@math{P_l(x)} for a specific value of @var{l},
@var{x} subject to @c{$l \ge 0$}
@math{l >= 0}, 
@c{$|x| \le 1$}
@math{|x| <= 1}
@comment Exceptional Return Values: GSL_EDOM
@end deftypefun

@deftypefun int gsl_sf_legendre_Pl_array (int @var{lmax}, double @var{x}, double @var{result_array}[])
@deftypefunx int gsl_sf_legendre_Pl_deriv_array (int @var{lmax}, double @var{x}, double @var{result_array}[], double @var{result_deriv_array}[])

These functions compute an array of Legendre polynomials
@math{P_l(x)}, and optionally their derivatives @math{dP_l(x)/dx}, 
for @math{l = 0, \dots, lmax}, 
@c{$|x| \le 1$}
@math{|x| <= 1}
@comment Exceptional Return Values: GSL_EDOM
@end deftypefun


@deftypefun double gsl_sf_legendre_Q0 (double @var{x})
@deftypefunx int gsl_sf_legendre_Q0_e (double @var{x}, gsl_sf_result * @var{result})
These routines compute the Legendre function @math{Q_0(x)} for @math{x >
-1}, @c{$x \ne 1$}
@math{x != 1}.
@comment Exceptional Return Values: GSL_EDOM
@end deftypefun


@deftypefun double gsl_sf_legendre_Q1 (double @var{x})
@deftypefunx int gsl_sf_legendre_Q1_e (double @var{x}, gsl_sf_result * @var{result})
These routines compute the Legendre function @math{Q_1(x)} for @math{x >
-1}, @c{$x \ne 1$}
@math{x != 1}.
@comment Exceptional Return Values: GSL_EDOM
@end deftypefun

@deftypefun double gsl_sf_legendre_Ql (int @var{l}, double @var{x})
@deftypefunx int gsl_sf_legendre_Ql_e (int @var{l}, double @var{x}, gsl_sf_result * @var{result})
These routines compute the Legendre function @math{Q_l(x)} for @math{x >
-1}, @c{$x \ne 1$}
@math{x != 1} and @c{$l \ge 0$}
@math{l >= 0}.
@comment Exceptional Return Values: GSL_EDOM
@end deftypefun


@node Associated Legendre Polynomials and Spherical Harmonics
@subsection Associated Legendre Polynomials and Spherical Harmonics

The following functions compute the associated Legendre Polynomials
@math{P_l^m(x)}.  Note that this function grows combinatorially with
@math{l} and can overflow for @math{l} larger than about 150.  There is
no trouble for small @math{m}, but overflow occurs when @math{m} and
@math{l} are both large.  Rather than allow overflows, these functions
refuse to calculate @math{P_l^m(x)} and return @code{GSL_EOVRFLW} when
they can sense that @math{l} and @math{m} are too big.

If you want to calculate a spherical harmonic, then @emph{do not} use
these functions.  Instead use @code{gsl_sf_legendre_sphPlm} below,
which uses a similar recursion, but with the normalized functions.

@deftypefun double gsl_sf_legendre_Plm (int @var{l}, int @var{m}, double @var{x})
@deftypefunx int gsl_sf_legendre_Plm_e (int @var{l}, int @var{m}, double @var{x}, gsl_sf_result * @var{result})
These routines compute the associated Legendre polynomial
@math{P_l^m(x)} for @c{$m \ge 0$}
@math{m >= 0}, @c{$l \ge m$}
@math{l >= m}, @c{$|x| \le 1$}
@math{|x| <= 1}. 
@comment Exceptional Return Values: GSL_EDOM, GSL_EOVRFLW
@end deftypefun

@deftypefun int gsl_sf_legendre_Plm_array (int @var{lmax}, int @var{m}, double @var{x}, double @var{result_array}[])
@deftypefunx int gsl_sf_legendre_Plm_deriv_array (int @var{lmax}, int @var{m}, double @var{x}, double @var{result_array}[], double @var{result_deriv_array}[])
These functions compute an array of Legendre polynomials
@math{P_l^m(x)}, and optionally their derivatives @math{dP_l^m(x)/dx},
for @c{$m \ge 0$}
@math{m >= 0}, @c{$l = |m|, \dots, lmax$}
@math{l = |m|, ..., lmax}, @c{$|x| \le 1$}
@math{|x| <= 1}.
@comment Exceptional Return Values: GSL_EDOM, GSL_EOVRFLW
@end deftypefun


@deftypefun double gsl_sf_legendre_sphPlm (int @var{l}, int @var{m}, double @var{x})
@deftypefunx int gsl_sf_legendre_sphPlm_e (int @var{l}, int @var{m}, double @var{x}, gsl_sf_result * @var{result})
These routines compute the normalized associated Legendre polynomial
@c{$\sqrt{(2l+1)/(4\pi)} \sqrt{(l-m)!/(l+m)!} P_l^m(x)$}
@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 @c{$m \ge 0$}
@math{m >= 0}, @c{$l \ge m$}
@math{l >= m}, @c{$|x| \le 1$}
@math{|x| <= 1}. Theses routines avoid the overflows
that occur for the standard normalization of @math{P_l^m(x)}.
@comment Exceptional Return Values: GSL_EDOM
@end deftypefun

@deftypefun int gsl_sf_legendre_sphPlm_array (int @var{lmax}, int @var{m}, double @var{x}, double @var{result_array}[])
@deftypefunx int gsl_sf_legendre_sphPlm_deriv_array (int @var{lmax}, int @var{m}, double @var{x}, double @var{result_array}[], double @var{result_deriv_array}[])
These functions compute an array of normalized associated Legendre functions
@c{$\sqrt{(2l+1)/(4\pi)} \sqrt{(l-m)!/(l+m)!} P_l^m(x)$}
@math{$\sqrt@{(2l+1)/(4\pi)@} \sqrt@{(l-m)!/(l+m)!@} P_l^m(x)$},
and optionally their derivatives,
for @c{$m \ge 0$}
@math{m >= 0}, @c{$l = |m|, \dots, lmax$}
@math{l = |m|, ..., lmax}, @c{$|x| \le 1$}
@math{|x| <= 1.0}
@comment Exceptional Return Values: GSL_EDOM
@end deftypefun

@deftypefun int gsl_sf_legendre_array_size (const int @var{lmax}, const int @var{m})
This function returns the size of @var{result_array}[] needed for the array
versions of @math{P_l^m(x)}, @math{@var{lmax} - @var{m} + 1}.
@comment Exceptional Return Values: none
@end deftypefun

@node Conical Functions
@subsection Conical Functions

The Conical Functions @c{$P^\mu_{-(1/2)+i\lambda}(x)$}
@math{P^\mu_@{-(1/2)+i\lambda@}(x)} and @c{$Q^\mu_{-(1/2)+i\lambda}$} 
@math{Q^\mu_@{-(1/2)+i\lambda@}} 
are described in Abramowitz & Stegun, Section 8.12.

@deftypefun double gsl_sf_conicalP_half (double @var{lambda}, double @var{x})
@deftypefunx int gsl_sf_conicalP_half_e (double @var{lambda}, double @var{x}, gsl_sf_result * @var{result})
These routines compute the irregular Spherical Conical Function
@c{$P^{1/2}_{-1/2 + i \lambda}(x)$}
@math{P^@{1/2@}_@{-1/2 + i \lambda@}(x)} for @math{x > -1}.
@comment Exceptional Return Values: GSL_EDOM
@end deftypefun

@deftypefun double gsl_sf_conicalP_mhalf (double @var{lambda}, double @var{x})
@deftypefunx int gsl_sf_conicalP_mhalf_e (double @var{lambda}, double @var{x}, gsl_sf_result * @var{result})
These routines compute the regular Spherical Conical Function
@c{$P^{-1/2}_{-1/2 + i \lambda}(x)$}
@math{P^@{-1/2@}_@{-1/2 + i \lambda@}(x)} for @math{x > -1}.
@comment Exceptional Return Values: GSL_EDOM
@end deftypefun

@deftypefun double gsl_sf_conicalP_0 (double @var{lambda}, double @var{x})
@deftypefunx int gsl_sf_conicalP_0_e (double @var{lambda}, double @var{x}, gsl_sf_result * @var{result})
These routines compute the conical function
@c{$P^0_{-1/2 + i \lambda}(x)$}
@math{P^0_@{-1/2 + i \lambda@}(x)}
for @math{x > -1}.
@comment Exceptional Return Values: GSL_EDOM
@end deftypefun


@deftypefun double gsl_sf_conicalP_1 (double @var{lambda}, double @var{x})
@deftypefunx int gsl_sf_conicalP_1_e (double @var{lambda}, double @var{x}, gsl_sf_result * @var{result})
These routines compute the conical function 
@c{$P^1_{-1/2 + i \lambda}(x)$}
@math{P^1_@{-1/2 + i \lambda@}(x)} for @math{x > -1}.
@comment Exceptional Return Values: GSL_EDOM
@end deftypefun


@deftypefun double gsl_sf_conicalP_sph_reg (int @var{l}, double @var{lambda}, double @var{x})
@deftypefunx int gsl_sf_conicalP_sph_reg_e (int @var{l}, double @var{lambda}, double @var{x}, gsl_sf_result * @var{result})
These routines compute the Regular Spherical Conical Function
@c{$P^{-1/2-l}_{-1/2 + i \lambda}(x)$}
@math{P^@{-1/2-l@}_@{-1/2 + i \lambda@}(x)} for @math{x > -1}, @c{$l \ge -1$}
@math{l >= -1}.
@comment Exceptional Return Values: GSL_EDOM
@end deftypefun


@deftypefun double gsl_sf_conicalP_cyl_reg (int @var{m}, double @var{lambda}, double @var{x})
@deftypefunx int gsl_sf_conicalP_cyl_reg_e (int @var{m}, double @var{lambda}, double @var{x}, gsl_sf_result * @var{result})
These routines compute the Regular Cylindrical Conical Function
@c{$P^{-m}_{-1/2 + i \lambda}(x)$}
@math{P^@{-m@}_@{-1/2 + i \lambda@}(x)} for @math{x > -1}, @c{$m \ge -1$}
@math{m >= -1}.
@comment Exceptional Return Values: GSL_EDOM
@end deftypefun



@node Radial Functions for Hyperbolic Space
@subsection 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{H3d}.  Of particular interest is
the flat limit, @math{\lambda \to \infty}, @math{\eta \to 0},
@math{\lambda\eta} fixed.
  
@deftypefun double gsl_sf_legendre_H3d_0 (double @var{lambda}, double @var{eta})
@deftypefunx int gsl_sf_legendre_H3d_0_e (double @var{lambda}, double @var{eta}, gsl_sf_result * @var{result})
These routines compute the zeroth radial eigenfunction of the Laplacian on the
3-dimensional hyperbolic space,
@c{$$L^{H3d}_0(\lambda,\eta) := {\sin(\lambda\eta) \over \lambda\sinh(\eta)}$$}
@math{L^@{H3d@}_0(\lambda,\eta) := \sin(\lambda\eta)/(\lambda\sinh(\eta))}
for @c{$\eta \ge 0$}
@math{\eta >= 0}.
In the flat limit this takes the form
@c{$L^{H3d}_0(\lambda,\eta) = j_0(\lambda\eta)$}
@math{L^@{H3d@}_0(\lambda,\eta) = j_0(\lambda\eta)}.
@comment Exceptional Return Values: GSL_EDOM
@end deftypefun

@deftypefun double gsl_sf_legendre_H3d_1 (double @var{lambda}, double @var{eta})
@deftypefunx int gsl_sf_legendre_H3d_1_e (double @var{lambda}, double @var{eta}, gsl_sf_result * @var{result})
These routines compute the first radial eigenfunction of the Laplacian on
the 3-dimensional hyperbolic space,
@c{$$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)$$}
@math{L^@{H3d@}_1(\lambda,\eta) := 1/\sqrt@{\lambda^2 + 1@} \sin(\lambda \eta)/(\lambda \sinh(\eta)) (\coth(\eta) - \lambda \cot(\lambda\eta))}
for @c{$\eta \ge 0$}
@math{\eta >= 0}.
In the flat limit this takes the form 
@c{$L^{H3d}_1(\lambda,\eta) = j_1(\lambda\eta)$}
@math{L^@{H3d@}_1(\lambda,\eta) = j_1(\lambda\eta)}.
@comment Exceptional Return Values: GSL_EDOM
@end deftypefun

@deftypefun double gsl_sf_legendre_H3d (int @var{l}, double @var{lambda}, double @var{eta})
@deftypefunx int gsl_sf_legendre_H3d_e (int @var{l}, double @var{lambda}, double @var{eta}, gsl_sf_result * @var{result})
These routines compute the @var{l}-th radial eigenfunction of the
Laplacian on the 3-dimensional hyperbolic space @c{$\eta \ge 0$}
@math{\eta >= 0}, @c{$l \ge 0$}
@math{l >= 0}. In the flat limit this takes the form
@c{$L^{H3d}_l(\lambda,\eta) = j_l(\lambda\eta)$}
@math{L^@{H3d@}_l(\lambda,\eta) = j_l(\lambda\eta)}.
@comment Exceptional Return Values: GSL_EDOM
@end deftypefun

@deftypefun int gsl_sf_legendre_H3d_array (int @var{lmax}, double @var{lambda}, double @var{eta}, double @var{result_array}[])
This function computes an array of radial eigenfunctions
@c{$L^{H3d}_l( \lambda, \eta)$} 
@math{L^@{H3d@}_l(\lambda, \eta)} 
for @c{$0 \le l \le lmax$}
@math{0 <= l <= lmax}.
@comment Exceptional Return Values:
@end deftypefun