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 gsl_sf_airy.h, gsl_sf_bessel.h, etc.  The complete set of header files can be included using the file gsl_sf.h.

Usage
=====

The special functions are available in two calling conventions, a natural form which returns the numerical value of the function and an error-handling form which returns an error code.  The two types of function provide alternative ways of accessing the same underlying code.

The 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 J_0(x),

     double y = gsl_sf_bessel_J0 (x);

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,

     gsl_sf_result result;
     int status = gsl_sf_bessel_J0_e (x, &result);

The error-handling functions have the suffix _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 GSL_SUCCESS.

The gsl_sf_result struct
========================

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 gsl_sf_result.h.

The gsl_sf_result struct contains value and error fields.

     typedef struct
     {
       double val;
       double err;
     } gsl_sf_result;

The field VAL contains the value and the field 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 gsl_sf_result_e10 struct contains value and error fields as well as an exponent field such that the actual result is obtained as result * 10^(e10).

     typedef struct
     {
       double val;
       double err;
       int    e10;
     } gsl_sf_result_e10;

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 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,

GSL_PREC_DOUBLE
     Double-precision, a relative accuracy of approximately $2 \times 10^-16$ 2 * 10^-16.

GSL_PREC_SINGLE
     Single-precision, a relative accuracy of approximately $1 \times 10^-7$ 10^-7.

GSL_PREC_APPROX
     Approximate values, a relative accuracy of approximately $5 \times 10^-4$ 5 * 10^-4.

The approximate mode provides the fastest evaluation at the lowest accuracy.

Airy Functions and Derivatives
==============================

     [file specfunc-airy.texi not included]

Bessel Functions
================

     [file specfunc-bessel.texi not included]

Clausen Functions
=================

     [file specfunc-clausen.texi not included]

Coulomb Functions
=================

     [file specfunc-coulomb.texi not included]

Coupling Coefficients
=====================

     [file specfunc-coupling.texi not included]

Dawson Function
===============

     [file specfunc-dawson.texi not included]

Debye Functions
===============

     [file specfunc-debye.texi not included]

Dilogarithm
===========

     [file specfunc-dilog.texi not included]

Elementary Operations
=====================

     [file specfunc-elementary.texi not included]

Elliptic Integrals
==================

     [file specfunc-ellint.texi not included]

Elliptic Functions (Jacobi)
===========================

     [file specfunc-elljac.texi not included]

Error Functions
===============

     [file specfunc-erf.texi not included]

Exponential Functions
=====================

     [file specfunc-exp.texi not included]

Exponential Integrals
=====================

     [file specfunc-expint.texi not included]

Fermi-Dirac Function
====================

     [file specfunc-fermi-dirac.texi not included]

Gamma and Beta Functions
========================

     [file specfunc-gamma.texi not included]

Gegenbauer Functions
====================

     [file specfunc-gegenbauer.texi not included]

Hypergeometric Functions
========================

     [file specfunc-hyperg.texi not included]

Laguerre Functions
==================

     [file specfunc-laguerre.texi not included]

Lambert W Functions
===================

     [file specfunc-lambert.texi not included]

Legendre Functions and Spherical Harmonics
==========================================

     [file specfunc-legendre.texi not included]

Logarithm and Related Functions
===============================

     [file specfunc-log.texi not included]

Mathieu Functions
=================

     [file specfunc-mathieu.texi not included]

Power Function
==============

     [file specfunc-pow-int.texi not included]

Psi (Digamma) Function
======================

     [file specfunc-psi.texi not included]

Synchrotron Functions
=====================

     [file specfunc-synchrotron.texi not included]

Transport Functions
===================

     [file specfunc-transport.texi not included]

Trigonometric Functions
=======================

     [file specfunc-trig.texi not included]

Zeta Functions
==============

     [file specfunc-zeta.texi not included]

Examples
========

The following example demonstrates the use of the error handling form of the special functions, in this case to compute the Bessel function J_0(5.0),

          [file specfun_e.c not included]

Here are the results of running the program,

     $ ./a.out
          [file specfun_e.out not included]

The next program computes the same quantity using the natural form of the function. In this case the error term RESULT.ERR and return status are not accessible.

          [file specfun.c not included]

The results of the function are the same,

     $ ./a.out
          [file specfun.out not included]

References and Further Reading
==============================

The library follows the conventions of Abramowitz & Stegun where possible,

  Abramowitz & Stegun (eds.), Handbook of Mathematical Functions

The following papers contain information on the algorithms used to compute the special functions,

  MISCFUN: A software package to compute uncommon special functions. ACM Trans. Math. Soft., vol. 22, 1996, 288--301

  G.N. Watson, A Treatise on the Theory of Bessel Functions, 2nd Edition (Cambridge University Press, 1944).

  G. Nemeth, Mathematical Approximations of Special Functions, Nova Science Publishers, ISBN 1-56072-052-2

  B.C. Carlson, Special Functions of Applied Mathematics (1977)

  W.J. Thompson, Atlas for Computing Mathematical Functions, John Wiley & Sons, New York (1997).

  Y.Y. Luke, Algorithms for the Computation of Mathematical Functions, Academic Press, New York (1977).