.. index:: special functions

*****************

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, Hermite polynomials and 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`.

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

:math:`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 :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`.

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 :file:`gsl_sf_result.h`.

The following struct contains value and error fields.

.. type:: gsl_sf_result

   ::

     typedef struct

     {

       double val;

       double err;

     } gsl_sf_result;

   The field :data:`val` contains the value and the field :data:`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

following struct contains value and error fields as well

as an exponent field such that the actual result is obtained as

:code:`result * 10^(e10)`.

.. type:: gsl_sf_result_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 :code:`mode` argument, of type

:type:`gsl_mode_t` allows the

accuracy of the function to be reduced in order to improve performance.

The following precision levels are available for the mode argument,

.. type:: gsl_mode_t

   .. macro:: GSL_PREC_DOUBLE

      Double-precision, a relative accuracy of approximately :math:`2 * 10^{-16}`.

   .. macro:: GSL_PREC_SINGLE

      Single-precision, a relative accuracy of approximately :math:`10^{-7}`.

   .. macro:: GSL_PREC_APPROX

      Approximate values, a relative accuracy of approximately :math:`5 * 10^{-4}`.

The approximate mode provides the fastest evaluation at the lowest

accuracy.

Airy Functions and Derivatives

==============================

.. include:: specfunc-airy.rst

Bessel Functions

================

.. include:: specfunc-bessel.rst

Clausen Functions

=================

.. include:: specfunc-clausen.rst

Coulomb Functions

=================

.. include:: specfunc-coulomb.rst

Coupling Coefficients

=====================

.. include:: specfunc-coupling.rst

Dawson Function

===============

.. include:: specfunc-dawson.rst

Debye Functions

===============

.. include:: specfunc-debye.rst

.. _dilog-function:

Dilogarithm

===========

.. include:: specfunc-dilog.rst

Elementary Operations

=====================

.. include:: specfunc-elementary.rst

Elliptic Integrals

==================

.. include:: specfunc-ellint.rst

Elliptic Functions (Jacobi)

===========================

.. include:: specfunc-elljac.rst

Error Functions

===============

.. include:: specfunc-erf.rst

Exponential Functions

=====================

.. include:: specfunc-exp.rst

Exponential Integrals

=====================

.. include:: specfunc-expint.rst

Fermi-Dirac Function

====================

.. include:: specfunc-fermi-dirac.rst

Gamma and Beta Functions

========================

.. include:: specfunc-gamma.rst

Gegenbauer Functions

====================

.. include:: specfunc-gegenbauer.rst

Hermite Polynomials and Functions

=================================

.. include:: specfunc-hermite.rst

Hypergeometric Functions

========================

.. include:: specfunc-hyperg.rst

.. _laguerre-functions:

Laguerre Functions

==================

.. include:: specfunc-laguerre.rst

Lambert W Functions

===================

.. include:: specfunc-lambert.rst

Legendre Functions and Spherical Harmonics

==========================================

.. include:: specfunc-legendre.rst

Logarithm and Related Functions

===============================

.. include:: specfunc-log.rst

Mathieu Functions

=================

.. include:: specfunc-mathieu.rst

Power Function

==============

.. include:: specfunc-pow-int.rst

Psi (Digamma) Function

======================

.. include:: specfunc-psi.rst

Synchrotron Functions

=====================

.. include:: specfunc-synchrotron.rst

Transport Functions

===================

.. include:: specfunc-transport.rst

Trigonometric Functions

=======================

.. include:: specfunc-trig.rst

Zeta Functions

==============

.. include:: specfunc-zeta.rst

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

.. include:: examples/specfun_e.c

   :code:

Here are the results of running the program,

.. include:: examples/specfun_e.txt

   :code:

The next program computes the same quantity using the natural form of

the function. In this case the error term :data:`result.err` and return

status are not accessible.

.. include:: examples/specfun.c

   :code:

The results of the function are the same,

.. include:: examples/specfun.txt

   :code:

References and Further Reading

==============================

The library follows the conventions of the following book where possible,

* Handbook of Mathematical Functions, edited by Abramowitz & Stegun,

  Dover,  ISBN 0486612724.

The following papers contain information on the algorithms used 

to compute the special functions,

.. index:: MISCFUN

* Allan J. MacLeod, 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)

* N. M. Temme, Special Functions: An Introduction to the Classical

  Functions of Mathematical Physics (1996), ISBN 978-0471113133.

* 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).

* S. A. Holmes and W. E. Featherstone, A unified approach to the Clenshaw

  summation and the recursive computation of very high degree and order

  normalised associated Legendre functions, Journal of Geodesy, 76,

  pg. 279-299, 2002.