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

@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