htswanalysis/MACS/lib/gsl/gsl-1.11/doc/specfunc-legendre.texi

   1 @cindex Legendre functions
   2 @cindex spherical harmonics
   3 @cindex conical functions
   4 @cindex hyperbolic space
   5
   6 The Legendre Functions and Legendre Polynomials are described in
   7 Abramowitz & Stegun, Chapter 8.  These functions are declared in
   8 the header file @file{gsl_sf_legendre.h}.
   9
  10 @menu
  11 * Legendre Polynomials::
  12 * Associated Legendre Polynomials and Spherical Harmonics::
  13 * Conical Functions::
  14 * Radial Functions for Hyperbolic Space::
  15 @end menu
  16
  17 @node Legendre Polynomials
  18 @subsection Legendre Polynomials
  19
  20 @deftypefun double gsl_sf_legendre_P1 (double @var{x})
  21 @deftypefunx double gsl_sf_legendre_P2 (double @var{x})
  22 @deftypefunx double gsl_sf_legendre_P3 (double @var{x})
  23 @deftypefunx int gsl_sf_legendre_P1_e (double @var{x}, gsl_sf_result * @var{result})
  24 @deftypefunx int gsl_sf_legendre_P2_e (double @var{x}, gsl_sf_result * @var{result})
  25 @deftypefunx int gsl_sf_legendre_P3_e (double @var{x}, gsl_sf_result * @var{result})
  26 These functions evaluate the Legendre polynomials
  27 @c{$P_l(x)$}
  28 @math{P_l(x)} using explicit
  29 representations for @math{l=1, 2, 3}.
  30 @comment Exceptional Return Values: none
  31 @end deftypefun
  32
  33 @deftypefun double gsl_sf_legendre_Pl (int @var{l}, double @var{x})
  34 @deftypefunx int gsl_sf_legendre_Pl_e (int @var{l}, double @var{x}, gsl_sf_result * @var{result})
  35 These functions evaluate the Legendre polynomial @c{$P_l(x)$}
  36 @math{P_l(x)} for a specific value of @var{l},
  37 @var{x} subject to @c{$l \ge 0$}
  38 @math{l >= 0},
  39 @c{$|x| \le 1$}
  40 @math{|x| <= 1}
  41 @comment Exceptional Return Values: GSL_EDOM
  42 @end deftypefun
  43
  44 @deftypefun int gsl_sf_legendre_Pl_array (int @var{lmax}, double @var{x}, double @var{result_array}[])
  45 @deftypefunx int gsl_sf_legendre_Pl_deriv_array (int @var{lmax}, double @var{x}, double @var{result_array}[], double @var{result_deriv_array}[])
  46
  47 These functions compute an array of Legendre polynomials
  48 @math{P_l(x)}, and optionally their derivatives @math{dP_l(x)/dx},
  49 for @math{l = 0, \dots, lmax},
  50 @c{$|x| \le 1$}
  51 @math{|x| <= 1}
  52 @comment Exceptional Return Values: GSL_EDOM
  53 @end deftypefun
  54
  55
  56 @deftypefun double gsl_sf_legendre_Q0 (double @var{x})
  57 @deftypefunx int gsl_sf_legendre_Q0_e (double @var{x}, gsl_sf_result * @var{result})
  58 These routines compute the Legendre function @math{Q_0(x)} for @math{x >
  59 -1}, @c{$x \ne 1$}
  60 @math{x != 1}.
  61 @comment Exceptional Return Values: GSL_EDOM
  62 @end deftypefun
  63
  64
  65 @deftypefun double gsl_sf_legendre_Q1 (double @var{x})
  66 @deftypefunx int gsl_sf_legendre_Q1_e (double @var{x}, gsl_sf_result * @var{result})
  67 These routines compute the Legendre function @math{Q_1(x)} for @math{x >
  68 -1}, @c{$x \ne 1$}
  69 @math{x != 1}.
  70 @comment Exceptional Return Values: GSL_EDOM
  71 @end deftypefun
  72
  73 @deftypefun double gsl_sf_legendre_Ql (int @var{l}, double @var{x})
  74 @deftypefunx int gsl_sf_legendre_Ql_e (int @var{l}, double @var{x}, gsl_sf_result * @var{result})
  75 These routines compute the Legendre function @math{Q_l(x)} for @math{x >
  76 -1}, @c{$x \ne 1$}
  77 @math{x != 1} and @c{$l \ge 0$}
  78 @math{l >= 0}.
  79 @comment Exceptional Return Values: GSL_EDOM
  80 @end deftypefun
  81
  82
  83 @node Associated Legendre Polynomials and Spherical Harmonics
  84 @subsection Associated Legendre Polynomials and Spherical Harmonics
  85
  86 The following functions compute the associated Legendre Polynomials
  87 @math{P_l^m(x)}.  Note that this function grows combinatorially with
  88 @math{l} and can overflow for @math{l} larger than about 150.  There is
  89 no trouble for small @math{m}, but overflow occurs when @math{m} and
  90 @math{l} are both large.  Rather than allow overflows, these functions
  91 refuse to calculate @math{P_l^m(x)} and return @code{GSL_EOVRFLW} when
  92 they can sense that @math{l} and @math{m} are too big.
  93
  94 If you want to calculate a spherical harmonic, then @emph{do not} use
  95 these functions.  Instead use @code{gsl_sf_legendre_sphPlm} below,
  96 which uses a similar recursion, but with the normalized functions.
  97
  98 @deftypefun double gsl_sf_legendre_Plm (int @var{l}, int @var{m}, double @var{x})
  99 @deftypefunx int gsl_sf_legendre_Plm_e (int @var{l}, int @var{m}, double @var{x}, gsl_sf_result * @var{result})
 100 These routines compute the associated Legendre polynomial
 101 @math{P_l^m(x)} for @c{$m \ge 0$}
 102 @math{m >= 0}, @c{$l \ge m$}
 103 @math{l >= m}, @c{$|x| \le 1$}
 104 @math{|x| <= 1}.
 105 @comment Exceptional Return Values: GSL_EDOM, GSL_EOVRFLW
 106 @end deftypefun
 107
 108 @deftypefun int gsl_sf_legendre_Plm_array (int @var{lmax}, int @var{m}, double @var{x}, double @var{result_array}[])
 109 @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}[])
 110 These functions compute an array of Legendre polynomials
 111 @math{P_l^m(x)}, and optionally their derivatives @math{dP_l^m(x)/dx},
 112 for @c{$m \ge 0$}
 113 @math{m >= 0}, @c{$l = |m|, \dots, lmax$}
 114 @math{l = |m|, ..., lmax}, @c{$|x| \le 1$}
 115 @math{|x| <= 1}.
 116 @comment Exceptional Return Values: GSL_EDOM, GSL_EOVRFLW
 117 @end deftypefun
 118
 119
 120 @deftypefun double gsl_sf_legendre_sphPlm (int @var{l}, int @var{m}, double @var{x})
 121 @deftypefunx int gsl_sf_legendre_sphPlm_e (int @var{l}, int @var{m}, double @var{x}, gsl_sf_result * @var{result})
 122 These routines compute the normalized associated Legendre polynomial
 123 @c{$\sqrt{(2l+1)/(4\pi)} \sqrt{(l-m)!/(l+m)!} P_l^m(x)$}
 124 @math{$\sqrt@{(2l+1)/(4\pi)@} \sqrt@{(l-m)!/(l+m)!@} P_l^m(x)$} suitable
 125 for use in spherical harmonics.  The parameters must satisfy @c{$m \ge 0$}
 126 @math{m >= 0}, @c{$l \ge m$}
 127 @math{l >= m}, @c{$|x| \le 1$}
 128 @math{|x| <= 1}. Theses routines avoid the overflows
 129 that occur for the standard normalization of @math{P_l^m(x)}.
 130 @comment Exceptional Return Values: GSL_EDOM
 131 @end deftypefun
 132
 133 @deftypefun int gsl_sf_legendre_sphPlm_array (int @var{lmax}, int @var{m}, double @var{x}, double @var{result_array}[])
 134 @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}[])
 135 These functions compute an array of normalized associated Legendre functions
 136 @c{$\sqrt{(2l+1)/(4\pi)} \sqrt{(l-m)!/(l+m)!} P_l^m(x)$}
 137 @math{$\sqrt@{(2l+1)/(4\pi)@} \sqrt@{(l-m)!/(l+m)!@} P_l^m(x)$},
 138 and optionally their derivatives,
 139 for @c{$m \ge 0$}
 140 @math{m >= 0}, @c{$l = |m|, \dots, lmax$}
 141 @math{l = |m|, ..., lmax}, @c{$|x| \le 1$}
 142 @math{|x| <= 1.0}
 143 @comment Exceptional Return Values: GSL_EDOM
 144 @end deftypefun
 145
 146 @deftypefun int gsl_sf_legendre_array_size (const int @var{lmax}, const int @var{m})
 147 This function returns the size of @var{result_array}[] needed for the array
 148 versions of @math{P_l^m(x)}, @math{@var{lmax} - @var{m} + 1}.  @inlinefn{}
 149 @comment Exceptional Return Values: none
 150 @end deftypefun
 151
 152 @node Conical Functions
 153 @subsection Conical Functions
 154
 155 The Conical Functions @c{$P^\mu_{-(1/2)+i\lambda}(x)$}
 156 @math{P^\mu_@{-(1/2)+i\lambda@}(x)} and @c{$Q^\mu_{-(1/2)+i\lambda}$}
 157 @math{Q^\mu_@{-(1/2)+i\lambda@}}
 158 are described in Abramowitz & Stegun, Section 8.12.
 159
 160 @deftypefun double gsl_sf_conicalP_half (double @var{lambda}, double @var{x})
 161 @deftypefunx int gsl_sf_conicalP_half_e (double @var{lambda}, double @var{x}, gsl_sf_result * @var{result})
 162 These routines compute the irregular Spherical Conical Function
 163 @c{$P^{1/2}_{-1/2 + i \lambda}(x)$}
 164 @math{P^@{1/2@}_@{-1/2 + i \lambda@}(x)} for @math{x > -1}.
 165 @comment Exceptional Return Values: GSL_EDOM
 166 @end deftypefun
 167
 168 @deftypefun double gsl_sf_conicalP_mhalf (double @var{lambda}, double @var{x})
 169 @deftypefunx int gsl_sf_conicalP_mhalf_e (double @var{lambda}, double @var{x}, gsl_sf_result * @var{result})
 170 These routines compute the regular Spherical Conical Function
 171 @c{$P^{-1/2}_{-1/2 + i \lambda}(x)$}
 172 @math{P^@{-1/2@}_@{-1/2 + i \lambda@}(x)} for @math{x > -1}.
 173 @comment Exceptional Return Values: GSL_EDOM
 174 @end deftypefun
 175
 176 @deftypefun double gsl_sf_conicalP_0 (double @var{lambda}, double @var{x})
 177 @deftypefunx int gsl_sf_conicalP_0_e (double @var{lambda}, double @var{x}, gsl_sf_result * @var{result})
 178 These routines compute the conical function
 179 @c{$P^0_{-1/2 + i \lambda}(x)$}
 180 @math{P^0_@{-1/2 + i \lambda@}(x)}
 181 for @math{x > -1}.
 182 @comment Exceptional Return Values: GSL_EDOM
 183 @end deftypefun
 184
 185
 186 @deftypefun double gsl_sf_conicalP_1 (double @var{lambda}, double @var{x})
 187 @deftypefunx int gsl_sf_conicalP_1_e (double @var{lambda}, double @var{x}, gsl_sf_result * @var{result})
 188 These routines compute the conical function
 189 @c{$P^1_{-1/2 + i \lambda}(x)$}
 190 @math{P^1_@{-1/2 + i \lambda@}(x)} for @math{x > -1}.
 191 @comment Exceptional Return Values: GSL_EDOM
 192 @end deftypefun
 193
 194
 195 @deftypefun double gsl_sf_conicalP_sph_reg (int @var{l}, double @var{lambda}, double @var{x})
 196 @deftypefunx int gsl_sf_conicalP_sph_reg_e (int @var{l}, double @var{lambda}, double @var{x}, gsl_sf_result * @var{result})
 197 These routines compute the Regular Spherical Conical Function
 198 @c{$P^{-1/2-l}_{-1/2 + i \lambda}(x)$}
 199 @math{P^@{-1/2-l@}_@{-1/2 + i \lambda@}(x)} for @math{x > -1}, @c{$l \ge -1$}
 200 @math{l >= -1}.
 201 @comment Exceptional Return Values: GSL_EDOM
 202 @end deftypefun
 203
 204
 205 @deftypefun double gsl_sf_conicalP_cyl_reg (int @var{m}, double @var{lambda}, double @var{x})
 206 @deftypefunx int gsl_sf_conicalP_cyl_reg_e (int @var{m}, double @var{lambda}, double @var{x}, gsl_sf_result * @var{result})
 207 These routines compute the Regular Cylindrical Conical Function
 208 @c{$P^{-m}_{-1/2 + i \lambda}(x)$}
 209 @math{P^@{-m@}_@{-1/2 + i \lambda@}(x)} for @math{x > -1}, @c{$m \ge -1$}
 210 @math{m >= -1}.
 211 @comment Exceptional Return Values: GSL_EDOM
 212 @end deftypefun
 213
 214
 215
 216 @node Radial Functions for Hyperbolic Space
 217 @subsection Radial Functions for Hyperbolic Space
 218
 219 The following spherical functions are specializations of Legendre
 220 functions which give the regular eigenfunctions of the Laplacian on a
 221 3-dimensional hyperbolic space @math{H3d}.  Of particular interest is
 222 the flat limit, @math{\lambda \to \infty}, @math{\eta \to 0},
 223 @math{\lambda\eta} fixed.
 224
 225 @deftypefun double gsl_sf_legendre_H3d_0 (double @var{lambda}, double @var{eta})
 226 @deftypefunx int gsl_sf_legendre_H3d_0_e (double @var{lambda}, double @var{eta}, gsl_sf_result * @var{result})
 227 These routines compute the zeroth radial eigenfunction of the Laplacian on the
 228 3-dimensional hyperbolic space,
 229 @c{$$L^{H3d}_0(\lambda,\eta) := {\sin(\lambda\eta) \over \lambda\sinh(\eta)}$$}
 230 @math{L^@{H3d@}_0(\lambda,\eta) := \sin(\lambda\eta)/(\lambda\sinh(\eta))}
 231 for @c{$\eta \ge 0$}
 232 @math{\eta >= 0}.
 233 In the flat limit this takes the form
 234 @c{$L^{H3d}_0(\lambda,\eta) = j_0(\lambda\eta)$}
 235 @math{L^@{H3d@}_0(\lambda,\eta) = j_0(\lambda\eta)}.
 236 @comment Exceptional Return Values: GSL_EDOM
 237 @end deftypefun
 238
 239 @deftypefun double gsl_sf_legendre_H3d_1 (double @var{lambda}, double @var{eta})
 240 @deftypefunx int gsl_sf_legendre_H3d_1_e (double @var{lambda}, double @var{eta}, gsl_sf_result * @var{result})
 241 These routines compute the first radial eigenfunction of the Laplacian on
 242 the 3-dimensional hyperbolic space,
 243 @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)$$}
 244 @math{L^@{H3d@}_1(\lambda,\eta) := 1/\sqrt@{\lambda^2 + 1@} \sin(\lambda \eta)/(\lambda \sinh(\eta)) (\coth(\eta) - \lambda \cot(\lambda\eta))}
 245 for @c{$\eta \ge 0$}
 246 @math{\eta >= 0}.
 247 In the flat limit this takes the form
 248 @c{$L^{H3d}_1(\lambda,\eta) = j_1(\lambda\eta)$}
 249 @math{L^@{H3d@}_1(\lambda,\eta) = j_1(\lambda\eta)}.
 250 @comment Exceptional Return Values: GSL_EDOM
 251 @end deftypefun
 252
 253 @deftypefun double gsl_sf_legendre_H3d (int @var{l}, double @var{lambda}, double @var{eta})
 254 @deftypefunx int gsl_sf_legendre_H3d_e (int @var{l}, double @var{lambda}, double @var{eta}, gsl_sf_result * @var{result})
 255 These routines compute the @var{l}-th radial eigenfunction of the
 256 Laplacian on the 3-dimensional hyperbolic space @c{$\eta \ge 0$}
 257 @math{\eta >= 0}, @c{$l \ge 0$}
 258 @math{l >= 0}. In the flat limit this takes the form
 259 @c{$L^{H3d}_l(\lambda,\eta) = j_l(\lambda\eta)$}
 260 @math{L^@{H3d@}_l(\lambda,\eta) = j_l(\lambda\eta)}.
 261 @comment Exceptional Return Values: GSL_EDOM
 262 @end deftypefun
 263
 264 @deftypefun int gsl_sf_legendre_H3d_array (int @var{lmax}, double @var{lambda}, double @var{eta}, double @var{result_array}[])
 265 This function computes an array of radial eigenfunctions
 266 @c{$L^{H3d}_l( \lambda, \eta)$}
 267 @math{L^@{H3d@}_l(\lambda, \eta)}
 268 for @c{$0 \le l \le lmax$}
 269 @math{0 <= l <= lmax}.
 270 @comment Exceptional Return Values:
 271 @end deftypefun
 272