Fermi Physics Class Libraries Module: Special Functions

ZOOM ZOOM

Special Functions Package

This package provides natural-syntax C++ wrapping for the large spectrum of special functions provided in the GNU Scientific Library (gsl). As of July 26, 2002, these wrappers correspond to release 1.2 of the gsl. The gsl itself exists as a separate external product available via the usual ups/upd mechanism. As such, the user must issue the command

setup gsl

before starting up either a compilation or a link. This is to insure that the environment variable $GSL_DIR is properly defined.

Tables specifying the entire list of function signatures, as well as the corresponding underlying routine in gsl, are provided. This page also explains the details of how these functions are used in C++.

The gsl Reference Manual documents these functions. There are other C sources in gsl. These are not provided with the package, but are described in the Reference Manual. ZOOM has not wrapped these for C++, and makes no claim as to whether the non-special-function portions will compile and correctly execute on ZOOM platforms under a C++ compiler. Only the Special Functions section is supported.

Structure of Classes in the Package
Syntax and Use of Most Functions
List of Basic Signatures for Each Function
List of Possible Exceptions for Each Class
Class and Struct Descriptions Generated by the doxygen Utility.


Structure of Classes in the Package

The functions are grouped into several groups, each of which is implemented as a struct containing a variety of specific functions. For instance, there is an Bessel struct, accessed by including SpecialFunctions/Bessel.h, which has functions like Bessel::J0(double x). These functions are all static and the structs have no data members.

The structs are:


Syntax and Use of Most Functions

Most of these functions logically ought to return a real number. For such a function, two forms are provided. The basic form indeed returns a double, which is the natural syntax. Most users will use this simplest form.

A second form, with the same name but ending in Err, returns a Dpair, which is merely a structure holding two doubles: the usual return value, and the maximum possible computational error.

Relatively few of these functions logically ought to return something other than a real. For example, the package defines Dvector as a std::vector of doubles. For clarity, we list here all the data types (other than the usual primitive types, float, double and so on) used in various places in the package.

In the brief signatures below, we will explicitly note when a return type is not the usual double.

(In the case of routines returning arrays of results, the name of the Err version has the word Err tacked on before the word Array.)

Errors due to invalid input values or other difficulties are dealt with via the ZOOM Exceptions mechanism, which if C++ exceptions are enabled can lead to throwing exceptions. These exceptions are always derived from ZMxSpecFun which in turn is derived from the basic ZMexception class. Possible exceptions are listed (with brief explanations) in SFExceptions.h.


List of Basic Signatures for Each Function

Airy

Bessel

ClaussenIntegral

Coulomb

DawsonIntegral

DebyeIntegral

DiLogarithm

EllipticIntegrals

ErrorFunction

ExpIntegrals

Exponential

FermiDirac

Gamma

Gegenbauer

Hyperbolic

Note. There are no inverse hyperbolic functions for complex argument.

HyperGeometric

IntegerPowers

JacobiElliptics

Laguerre

Legendre

Logarithm

PolyGamma

Synchrotron

Transport

Trigonometry

Wigner

Zeta


List of Possible Exceptions for Each Class


Many of these classes can throw exceptions of various types. These are all summarized in the following table.

 

Class Possible Exception
Airy GSL_EUNDRFLW, GSL_EOVRFLW
Bessel GSL_EDOM, GSL_EOVRFLW, GSL_EUNDRFLW, GSL_EINVAL
Chebyshev GSL_ENOMEM, GSL_EFAILED
ClausenIntegral None
Coulomb GSL_EDOM, GSL_EMAXITER, GSL_EUNDRFLW, GSL_EOVRFLW, GSL_ERUNAWAY, GSL_ELOSS, GSL_ESANITY
DawsonIntegral GSL_EUNDRFLW
DebyeIntegral GSL_EDOM, GSL_EUNDRFLW
DiLogarithm GSL_EMAXITER
EllipticIntegrals GSL_EDOM
ErrorFunction GSL_EUNDRFLW
ExpIntegrals GSL_EDOM, GSL_EUNDRFLW, GSL_EOVRFLW
Exponential GSL_EOVRFLW, GSL_EUNDRFLW
FermiDirac GSL_EUNDRFLW, GSL_EOVRFLW
Gamma GSL_EDOM, GSL_EROUND, GSL_ELOSS, GSL_EOVRFLW, GSL_EUNDRFLW
Gegenbauer GSL_EDOM
HyperGeometric GSL_EDOM, GSL_EOVRFLW, GSL_EUNDRFLW
IntegerPowers None
JacobiElliptics GSL_EDOM
Laguerre GSL_EDOM, GSL_EOVRFLW
Legendre GSL_EDOM, GSL_EOVRFLW
Logarithm GSL_EDOM
PolyGamma GSL_EDOM, GSL_ELOSS
Synchrotron GSL_EDOM, GSL_EUNDRFLW
Transport GSL_EDOM, GSL_EUNDRFLW
Trigonometry GSL_EDOM, GSL_ELOSS GSL_EOVRFLW
Wigner GSL_EDOM, GSL_EOVRFLW
Zeta GSL_EDOM, GSL_EOVRFLW, GSL_EUNDRFLW

 

The meanings and assigned severities of these exceptions are:

 

Exception Explanation Severity
GSL_EDOM Input value outside valid domain ERROR
GSL_EFAILED Generic (unclassified) failure SEVERE
GSL_EINVAL Invalid argument supplied ERROR
GSL_ELOSS Failure due to excessive precision loss WARNING
GSL_EMAXITER Maximum number of iterations exceeded ERROR
GSL_ENOMEM malloc failed SEVERE
GSL_EOVRFLW Overflow WARNING
GSL_EROUND Failure due to excessive roundoff WARNING
GSL_ERUNAWAY Iterative process out of control ERROR
GSL_ESANITY Sanity check failed SEVERE
GSL_EUNDRFLW Underflow WARNING

ZOOM Home Page - Fermilab at Work - Fermilab Home


Mark Fischler
Last modified: October 20, 2000.