diff options
Diffstat (limited to 'gsl-1.9/doc/specfunc-legendre.texi')
| -rw-r--r-- | gsl-1.9/doc/specfunc-legendre.texi | 272 |
1 files changed, 272 insertions, 0 deletions
diff --git a/gsl-1.9/doc/specfunc-legendre.texi b/gsl-1.9/doc/specfunc-legendre.texi new file mode 100644 index 0000000..4be1005 --- /dev/null +++ b/gsl-1.9/doc/specfunc-legendre.texi @@ -0,0 +1,272 @@ +@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 + |