diff options
Diffstat (limited to 'gsl-1.9/doc/specfunc.texi')
| -rw-r--r-- | gsl-1.9/doc/specfunc.texi | 352 |
1 files changed, 352 insertions, 0 deletions
diff --git a/gsl-1.9/doc/specfunc.texi b/gsl-1.9/doc/specfunc.texi new file mode 100644 index 0000000..50c93c3 --- /dev/null +++ b/gsl-1.9/doc/specfunc.texi @@ -0,0 +1,352 @@ +@cindex special functions + +This chapter describes the GSL special function library. The library +includes routines for calculating the values of Airy functions, Bessel +functions, Clausen functions, Coulomb wave functions, Coupling +coefficients, the Dawson function, Debye functions, Dilogarithms, +Elliptic integrals, Jacobi elliptic functions, Error functions, +Exponential integrals, Fermi-Dirac functions, Gamma functions, +Gegenbauer functions, Hypergeometric functions, Laguerre functions, +Legendre functions and Spherical Harmonics, the Psi (Digamma) Function, +Synchrotron functions, Transport functions, Trigonometric functions and +Zeta functions. Each routine also computes an estimate of the numerical +error in the calculated value of the function. + +The functions in this chapter are declared in individual header files, +such as @file{gsl_sf_airy.h}, @file{gsl_sf_bessel.h}, etc. The complete +set of header files can be included using the file @file{gsl_sf.h}. + +@menu +* Special Function Usage:: +* The gsl_sf_result struct:: +* Special Function Modes:: +* Airy Functions and Derivatives:: +* Bessel Functions:: +* Clausen Functions:: +* Coulomb Functions:: +* Coupling Coefficients:: +* Dawson Function:: +* Debye Functions:: +* Dilogarithm:: +* Elementary Operations:: +* Elliptic Integrals:: +* Elliptic Functions (Jacobi):: +* Error Functions:: +* Exponential Functions:: +* Exponential Integrals:: +* Fermi-Dirac Function:: +* Gamma and Beta Functions:: +* Gegenbauer Functions:: +* Hypergeometric Functions:: +* Laguerre Functions:: +* Lambert W Functions:: +* Legendre Functions and Spherical Harmonics:: +* Logarithm and Related Functions:: +* Mathieu Functions:: +* Power Function:: +* Psi (Digamma) Function:: +* Synchrotron Functions:: +* Transport Functions:: +* Trigonometric Functions:: +* Zeta Functions:: +* Special Functions Examples:: +* Special Functions References and Further Reading:: +@end menu + +@node Special Function Usage +@section Usage + +The special functions are available in two calling conventions, a +@dfn{natural form} which returns the numerical value of the function and +an @dfn{error-handling form} which returns an error code. The two types +of function provide alternative ways of accessing the same underlying +code. + +The @dfn{natural form} returns only the value of the function and can be +used directly in mathematical expressions. For example, the following +function call will compute the value of the Bessel function +@math{J_0(x)}, + +@example +double y = gsl_sf_bessel_J0 (x); +@end example + +@noindent +There is no way to access an error code or to estimate the error using +this method. To allow access to this information the alternative +error-handling form stores the value and error in a modifiable argument, + +@example +gsl_sf_result result; +int status = gsl_sf_bessel_J0_e (x, &result); +@end example + +@noindent +The error-handling functions have the suffix @code{_e}. The returned +status value indicates error conditions such as overflow, underflow or +loss of precision. If there are no errors the error-handling functions +return @code{GSL_SUCCESS}. + +@node The gsl_sf_result struct +@section The gsl_sf_result struct +@cindex gsl_sf_result +@cindex gsl_sf_result_e10 + +The error handling form of the special functions always calculate an +error estimate along with the value of the result. Therefore, +structures are provided for amalgamating a value and error estimate. +These structures are declared in the header file @file{gsl_sf_result.h}. + +The @code{gsl_sf_result} struct contains value and error fields. + +@example +typedef struct +@{ + double val; + double err; +@} gsl_sf_result; +@end example + +@noindent +The field @var{val} contains the value and the field @var{err} contains +an estimate of the absolute error in the value. + +In some cases, an overflow or underflow can be detected and handled by a +function. In this case, it may be possible to return a scaling exponent +as well as an error/value pair in order to save the result from +exceeding the dynamic range of the built-in types. The +@code{gsl_sf_result_e10} struct contains value and error fields as well +as an exponent field such that the actual result is obtained as +@code{result * 10^(e10)}. + +@example +typedef struct +@{ + double val; + double err; + int e10; +@} gsl_sf_result_e10; +@end example + +@node Special Function Modes +@section Modes + +The goal of the library is to achieve double precision accuracy wherever +possible. However the cost of evaluating some special functions to +double precision can be significant, particularly where very high order +terms are required. In these cases a @code{mode} argument allows the +accuracy of the function to be reduced in order to improve performance. +The following precision levels are available for the mode argument, + +@table @code +@item GSL_PREC_DOUBLE +Double-precision, a relative accuracy of approximately @c{$2 \times 10^{-16}$} +@math{2 * 10^-16}. +@item GSL_PREC_SINGLE +Single-precision, a relative accuracy of approximately @c{$1 \times 10^{-7}$} +@math{10^-7}. +@item GSL_PREC_APPROX +Approximate values, a relative accuracy of approximately @c{$5 \times 10^{-4}$} +@math{5 * 10^-4}. +@end table + +@noindent +The approximate mode provides the fastest evaluation at the lowest +accuracy. + +@node Airy Functions and Derivatives +@section Airy Functions and Derivatives +@include specfunc-airy.texi + +@node Bessel Functions +@section Bessel Functions +@include specfunc-bessel.texi + +@node Clausen Functions +@section Clausen Functions +@include specfunc-clausen.texi + +@node Coulomb Functions +@section Coulomb Functions +@include specfunc-coulomb.texi + +@node Coupling Coefficients +@section Coupling Coefficients +@include specfunc-coupling.texi + +@node Dawson Function +@section Dawson Function +@include specfunc-dawson.texi + +@node Debye Functions +@section Debye Functions +@include specfunc-debye.texi + +@node Dilogarithm +@section Dilogarithm +@include specfunc-dilog.texi + +@node Elementary Operations +@section Elementary Operations +@include specfunc-elementary.texi + +@node Elliptic Integrals +@section Elliptic Integrals +@include specfunc-ellint.texi + +@node Elliptic Functions (Jacobi) +@section Elliptic Functions (Jacobi) +@include specfunc-elljac.texi + +@node Error Functions +@section Error Functions +@include specfunc-erf.texi + +@node Exponential Functions +@section Exponential Functions +@include specfunc-exp.texi + +@node Exponential Integrals +@section Exponential Integrals +@include specfunc-expint.texi + +@node Fermi-Dirac Function +@section Fermi-Dirac Function +@include specfunc-fermi-dirac.texi + +@node Gamma and Beta Functions +@section Gamma and Beta Functions +@include specfunc-gamma.texi + +@node Gegenbauer Functions +@section Gegenbauer Functions +@include specfunc-gegenbauer.texi + +@node Hypergeometric Functions +@section Hypergeometric Functions +@include specfunc-hyperg.texi + +@node Laguerre Functions +@section Laguerre Functions +@include specfunc-laguerre.texi + +@node Lambert W Functions +@section Lambert W Functions +@include specfunc-lambert.texi + +@node Legendre Functions and Spherical Harmonics +@section Legendre Functions and Spherical Harmonics +@include specfunc-legendre.texi + +@node Logarithm and Related Functions +@section Logarithm and Related Functions +@include specfunc-log.texi + +@node Mathieu Functions +@section Mathieu Functions +@include specfunc-mathieu.texi + +@node Power Function +@section Power Function +@include specfunc-pow-int.texi + +@node Psi (Digamma) Function +@section Psi (Digamma) Function +@include specfunc-psi.texi + +@node Synchrotron Functions +@section Synchrotron Functions +@include specfunc-synchrotron.texi + +@node Transport Functions +@section Transport Functions +@include specfunc-transport.texi + +@node Trigonometric Functions +@section Trigonometric Functions +@include specfunc-trig.texi + +@node Zeta Functions +@section Zeta Functions +@include specfunc-zeta.texi + +@node Special Functions Examples +@section Examples + +The following example demonstrates the use of the error handling form of +the special functions, in this case to compute the Bessel function +@math{J_0(5.0)}, + +@example +@verbatiminclude examples/specfun_e.c +@end example + +@noindent +Here are the results of running the program, + +@example +$ ./a.out +@verbatiminclude examples/specfun_e.out +@end example + +@noindent +The next program computes the same quantity using the natural form of +the function. In this case the error term @var{result.err} and return +status are not accessible. + +@example +@verbatiminclude examples/specfun.c +@end example + +@noindent +The results of the function are the same, + +@example +$ ./a.out +@verbatiminclude examples/specfun.out +@end example + + + +@node Special Functions References and Further Reading +@section References and Further Reading + +The library follows the conventions of @cite{Abramowitz & Stegun} where +possible, +@itemize @asis +@item +Abramowitz & Stegun (eds.), @cite{Handbook of Mathematical Functions} +@end itemize + +@noindent +The following papers contain information on the algorithms used +to compute the special functions, +@cindex MISCFUN +@itemize @asis +@item +MISCFUN: A software package to compute uncommon special functions. +@cite{ACM Trans.@: Math.@: Soft.}, vol.@: 22, 1996, 288--301 + +@item +G.N. Watson, A Treatise on the Theory of Bessel Functions, +2nd Edition (Cambridge University Press, 1944). + +@item +G. Nemeth, Mathematical Approximations of Special Functions, +Nova Science Publishers, ISBN 1-56072-052-2 + +@item +B.C. Carlson, Special Functions of Applied Mathematics (1977) + +@item +W.J. Thompson, Atlas for Computing Mathematical Functions, John Wiley & Sons, +New York (1997). + +@item +Y.Y. Luke, Algorithms for the Computation of Mathematical Functions, Academic +Press, New York (1977). + +@comment @item +@comment Fermi-Dirac functions of orders @math{-1/2}, @math{1/2}, @math{3/2}, and +@comment @math{5/2}. @cite{ACM Trans. Math. Soft.}, vol. 24, 1998, 1-12. +@end itemize |