htswanalysis/MACS/lib/gsl/gsl-1.11/doc/specfunc.texi

   1 @cindex special functions
   2
   3 This chapter describes the GSL special function library.  The library
   4 includes routines for calculating the values of Airy functions, Bessel
   5 functions, Clausen functions, Coulomb wave functions, Coupling
   6 coefficients, the Dawson function, Debye functions, Dilogarithms,
   7 Elliptic integrals, Jacobi elliptic functions, Error functions,
   8 Exponential integrals, Fermi-Dirac functions, Gamma functions,
   9 Gegenbauer functions, Hypergeometric functions, Laguerre functions,
  10 Legendre functions and Spherical Harmonics, the Psi (Digamma) Function,
  11 Synchrotron functions, Transport functions, Trigonometric functions and
  12 Zeta functions.  Each routine also computes an estimate of the numerical
  13 error in the calculated value of the function.
  14
  15 The functions in this chapter are declared in individual header files,
  16 such as @file{gsl_sf_airy.h}, @file{gsl_sf_bessel.h}, etc.  The complete
  17 set of header files can be included using the file @file{gsl_sf.h}.
  18
  19 @menu
  20 * Special Function Usage::
  21 * The gsl_sf_result struct::
  22 * Special Function Modes::
  23 * Airy Functions and Derivatives::
  24 * Bessel Functions::
  25 * Clausen Functions::
  26 * Coulomb Functions::
  27 * Coupling Coefficients::
  28 * Dawson Function::
  29 * Debye Functions::
  30 * Dilogarithm::
  31 * Elementary Operations::
  32 * Elliptic Integrals::
  33 * Elliptic Functions (Jacobi)::
  34 * Error Functions::
  35 * Exponential Functions::
  36 * Exponential Integrals::
  37 * Fermi-Dirac Function::
  38 * Gamma and Beta Functions::
  39 * Gegenbauer Functions::
  40 * Hypergeometric Functions::
  41 * Laguerre Functions::
  42 * Lambert W Functions::
  43 * Legendre Functions and Spherical Harmonics::
  44 * Logarithm and Related Functions::
  45 * Mathieu Functions::
  46 * Power Function::
  47 * Psi (Digamma) Function::
  48 * Synchrotron Functions::
  49 * Transport Functions::
  50 * Trigonometric Functions::
  51 * Zeta Functions::
  52 * Special Functions Examples::
  53 * Special Functions References and Further Reading::
  54 @end menu
  55
  56 @node Special Function Usage
  57 @section Usage
  58
  59 The special functions are available in two calling conventions, a
  60 @dfn{natural form} which returns the numerical value of the function and
  61 an @dfn{error-handling form} which returns an error code.  The two types
  62 of function provide alternative ways of accessing the same underlying
  63 code.
  64
  65 The @dfn{natural form} returns only the value of the function and can be
  66 used directly in mathematical expressions.  For example, the following
  67 function call will compute the value of the Bessel function
  68 @math{J_0(x)},
  69
  70 @example
  71 double y = gsl_sf_bessel_J0 (x);
  72 @end example
  73
  74 @noindent
  75 There is no way to access an error code or to estimate the error using
  76 this method.  To allow access to this information the alternative
  77 error-handling form stores the value and error in a modifiable argument,
  78
  79 @example
  80 gsl_sf_result result;
  81 int status = gsl_sf_bessel_J0_e (x, &result);
  82 @end example
  83
  84 @noindent
  85 The error-handling functions have the suffix @code{_e}. The returned
  86 status value indicates error conditions such as overflow, underflow or
  87 loss of precision.  If there are no errors the error-handling functions
  88 return @code{GSL_SUCCESS}.
  89
  90 @node The gsl_sf_result struct
  91 @section The gsl_sf_result struct
  92 @cindex gsl_sf_result
  93 @cindex gsl_sf_result_e10
  94
  95 The error handling form of the special functions always calculate an
  96 error estimate along with the value of the result.  Therefore,
  97 structures are provided for amalgamating a value and error estimate.
  98 These structures are declared in the header file @file{gsl_sf_result.h}.
  99
 100 The @code{gsl_sf_result} struct contains value and error fields.
 101
 102 @example
 103 typedef struct
 104 @{
 105   double val;
 106   double err;
 107 @} gsl_sf_result;
 108 @end example
 109
 110 @noindent
 111 The field @var{val} contains the value and the field @var{err} contains
 112 an estimate of the absolute error in the value.
 113
 114 In some cases, an overflow or underflow can be detected and handled by a
 115 function.  In this case, it may be possible to return a scaling exponent
 116 as well as an error/value pair in order to save the result from
 117 exceeding the dynamic range of the built-in types.  The
 118 @code{gsl_sf_result_e10} struct contains value and error fields as well
 119 as an exponent field such that the actual result is obtained as
 120 @code{result * 10^(e10)}.
 121
 122 @example
 123 typedef struct
 124 @{
 125   double val;
 126   double err;
 127   int    e10;
 128 @} gsl_sf_result_e10;
 129 @end example
 130
 131 @node Special Function Modes
 132 @section Modes
 133
 134 The goal of the library is to achieve double precision accuracy wherever
 135 possible.  However the cost of evaluating some special functions to
 136 double precision can be significant, particularly where very high order
 137 terms are required.  In these cases a @code{mode} argument allows the
 138 accuracy of the function to be reduced in order to improve performance.
 139 The following precision levels are available for the mode argument,
 140
 141 @table @code
 142 @item GSL_PREC_DOUBLE
 143 Double-precision, a relative accuracy of approximately @c{$2 \times 10^{-16}$}
 144 @math{2 * 10^-16}.
 145 @item GSL_PREC_SINGLE
 146 Single-precision, a relative accuracy of approximately @c{$1 \times 10^{-7}$}
 147 @math{10^-7}.
 148 @item GSL_PREC_APPROX
 149 Approximate values, a relative accuracy of approximately @c{$5 \times 10^{-4}$}
 150 @math{5 * 10^-4}.
 151 @end table
 152
 153 @noindent
 154 The approximate mode provides the fastest evaluation at the lowest
 155 accuracy.
 156
 157 @node Airy Functions and Derivatives
 158 @section Airy Functions and Derivatives
 159 @include specfunc-airy.texi
 160
 161 @node Bessel Functions
 162 @section Bessel Functions
 163 @include specfunc-bessel.texi
 164
 165 @node Clausen Functions
 166 @section Clausen Functions
 167 @include specfunc-clausen.texi
 168
 169 @node Coulomb Functions
 170 @section Coulomb Functions
 171 @include specfunc-coulomb.texi
 172
 173 @node Coupling Coefficients
 174 @section Coupling Coefficients
 175 @include specfunc-coupling.texi
 176
 177 @node Dawson Function
 178 @section Dawson Function
 179 @include specfunc-dawson.texi
 180
 181 @node Debye Functions
 182 @section Debye Functions
 183 @include specfunc-debye.texi
 184
 185 @node Dilogarithm
 186 @section Dilogarithm
 187 @include specfunc-dilog.texi
 188
 189 @node Elementary Operations
 190 @section Elementary Operations
 191 @include specfunc-elementary.texi
 192
 193 @node Elliptic Integrals
 194 @section Elliptic Integrals
 195 @include specfunc-ellint.texi
 196
 197 @node Elliptic Functions (Jacobi)
 198 @section Elliptic Functions (Jacobi)
 199 @include specfunc-elljac.texi
 200
 201 @node Error Functions
 202 @section Error Functions
 203 @include specfunc-erf.texi
 204
 205 @node Exponential Functions
 206 @section Exponential Functions
 207 @include specfunc-exp.texi
 208
 209 @node Exponential Integrals
 210 @section Exponential Integrals
 211 @include specfunc-expint.texi
 212
 213 @node Fermi-Dirac Function
 214 @section Fermi-Dirac Function
 215 @include specfunc-fermi-dirac.texi
 216
 217 @node Gamma and Beta Functions
 218 @section Gamma and Beta Functions
 219 @include specfunc-gamma.texi
 220
 221 @node Gegenbauer Functions
 222 @section Gegenbauer Functions
 223 @include specfunc-gegenbauer.texi
 224
 225 @node Hypergeometric Functions
 226 @section Hypergeometric Functions
 227 @include specfunc-hyperg.texi
 228
 229 @node Laguerre Functions
 230 @section Laguerre Functions
 231 @include specfunc-laguerre.texi
 232
 233 @node Lambert W Functions
 234 @section Lambert W Functions
 235 @include specfunc-lambert.texi
 236
 237 @node Legendre Functions and Spherical Harmonics
 238 @section Legendre Functions and Spherical Harmonics
 239 @include specfunc-legendre.texi
 240
 241 @node Logarithm and Related Functions
 242 @section Logarithm and Related Functions
 243 @include specfunc-log.texi
 244
 245 @node Mathieu Functions
 246 @section Mathieu Functions
 247 @include specfunc-mathieu.texi
 248
 249 @node Power Function
 250 @section Power Function
 251 @include specfunc-pow-int.texi
 252
 253 @node Psi (Digamma) Function
 254 @section Psi (Digamma) Function
 255 @include specfunc-psi.texi
 256
 257 @node Synchrotron Functions
 258 @section Synchrotron Functions
 259 @include specfunc-synchrotron.texi
 260
 261 @node Transport Functions
 262 @section Transport Functions
 263 @include specfunc-transport.texi
 264
 265 @node Trigonometric Functions
 266 @section Trigonometric Functions
 267 @include specfunc-trig.texi
 268
 269 @node Zeta Functions
 270 @section Zeta Functions
 271 @include specfunc-zeta.texi
 272
 273 @node Special Functions Examples
 274 @section Examples
 275
 276 The following example demonstrates the use of the error handling form of
 277 the special functions, in this case to compute the Bessel function
 278 @math{J_0(5.0)},
 279
 280 @example
 281 @verbatiminclude examples/specfun_e.c
 282 @end example
 283
 284 @noindent
 285 Here are the results of running the program,
 286
 287 @example
 288 $ ./a.out
 289 @verbatiminclude examples/specfun_e.out
 290 @end example
 291
 292 @noindent
 293 The next program computes the same quantity using the natural form of
 294 the function. In this case the error term @var{result.err} and return
 295 status are not accessible.
 296
 297 @example
 298 @verbatiminclude examples/specfun.c
 299 @end example
 300
 301 @noindent
 302 The results of the function are the same,
 303
 304 @example
 305 $ ./a.out
 306 @verbatiminclude examples/specfun.out
 307 @end example
 308
 309
 310
 311 @node Special Functions References and Further Reading
 312 @section References and Further Reading
 313
 314 The library follows the conventions of @cite{Abramowitz & Stegun} where
 315 possible,
 316 @itemize @asis
 317 @item
 318 Abramowitz & Stegun (eds.), @cite{Handbook of Mathematical Functions}
 319 @end itemize
 320
 321 @noindent
 322 The following papers contain information on the algorithms used
 323 to compute the special functions,
 324 @cindex MISCFUN
 325 @itemize @asis
 326 @item
 327 MISCFUN: A software package to compute uncommon special functions.
 328 @cite{ACM Trans.@: Math.@: Soft.}, vol.@: 22, 1996, 288--301
 329
 330 @item
 331 G.N. Watson, A Treatise on the Theory of Bessel Functions,
 332 2nd Edition (Cambridge University Press, 1944).
 333
 334 @item
 335 G. Nemeth, Mathematical Approximations of Special Functions,
 336 Nova Science Publishers, ISBN 1-56072-052-2
 337
 338 @item
 339 B.C. Carlson, Special Functions of Applied Mathematics (1977)
 340
 341 @item
 342 W.J. Thompson, Atlas for Computing Mathematical Functions, John Wiley & Sons,
 343 New York (1997).
 344
 345 @item
 346 Y.Y. Luke, Algorithms for the Computation of Mathematical Functions, Academic
 347 Press, New York (1977).
 348
 349 @comment @item
 350 @comment Fermi-Dirac functions of orders @math{-1/2}, @math{1/2}, @math{3/2}, and
 351 @comment @math{5/2}.  @cite{ACM Trans. Math. Soft.}, vol. 24, 1998, 1-12.
 352 @end itemize