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