Math Special Functions

The Special Functions library currently provides eight templated special functions, in namespace boost. Use the functions sinc_pi and sinhc_pi to implement quaternions and octonions.

The functions acosh, asinh and atanh are entirely classical, use the function sinc_pi in signal processing tasks, and the function sinhc_pi is an ad'hoc function whose naming is modelled on sinc_pi and hyperbolic functions.

The functions log1p, expm1 and hypot are all part of the C99 standard but not yet C++. The user needs the functions log1p and hypot for the complex number inverse trigonometric functions.

The functions implemented can throw standard exceptions, but no exception specification has been made.

The interface and implementation for each function (or forms of a function) are both supplied by one header file:

template<typename T> 
T acosh(const T x);

Computes the reciprocal of (the restriction to the range of [0;+ ∞ [) the hyperbolic cosine function, at x. Values returned are positive. Use the generalized Taylor series near 1 and Laurent series near infinity to ensure accuracy.

If x is in the range ]- ∞ ;+1[ a quiet NaN is returned (if the system allows, otherwise a domain_error exception is generated).

template<typename T> 
T asinh(const T x);

Computes the reciprocal of the hyperbolic sine function. Use Taylor series at the origin and Laurent series near infinity to ensure accuracy.

template<typename T> 
T atanh(const T x);

Computes the reciprocal of the hyperbolic tangent function, at x. Use Taylor series at the origin to ensure accuracy.

If x is in the range ]- ∞ ;-1[ or in the range ]+1;+ ∞ [ a quiet NaN is returned (if the system allows, otherwise a domain_error exception is generated).

If x is in the range `[-1;-1+ ε [, minus infinity is returned (if the system allows, otherwise an out_of_range exception is generated), with ε denoting numeric_limits<T>::epsilon().

If x is in the range ]+1- ε ;+1], plus infinity is returned (if the system allows, otherwise an out_of_range exception is generated), with ε denoting numeric_limits<T>::epsilon().

template <class T>
T expm1(T t);

Return value: This function returns e^x - 1 .

For small x, then e^x is very close to 1, as a result calculating e^x - 1 results in catastrophic cancellation errors when x is small. expm1 calculates e^x - 1 using a series expansion when x is small (giving an accuracy of less than 2ε ).

Finally when BOOST_HAS_EXPM1 is defined then the float/double/long double specializations of this template forward to the platform's native implementation of this function.

template <class T>
T hypot(T x, T y);

Return value: The function computes hypot  avoiding any undue underflow and overflow.

When calculating hypot it is quite easy for the intermediate terms to either overflow or underflow, even though the result is representable. One possible alternative form is hypot2, but that can overflow or underflow if x and y are of very differing magnitudes. The hypot function takes care of all the special cases for the user.

template <class T>
T log1p(T x);

Return value: This function returns the natural logarithm of x+1.

There are many situations where it is desirable to compute log(x+1). However, for small x then x+1 suffers from catastrophic cancellation errors so that x+1 == 1 and log(x+1) == 0, when in fact for very small x, the best approximation to log(x+1) would be x. log1p calculates the best approximation to log(1+x) using a Taylor series expansion for accuracy (less than 2ε ). Note that there are faster methods available, for example using the equivalence:

log(1+x) == (log(1+x) * x) / ((1-x) - 1)

However, experience has shown that these methods tend to fail once the compiler's optimizations are turned on. In contrast, the series expansion method seems to be reasonably immune to optimizer-induced errors.

Finally when BOOST_HAS_LOG1P is defined then the float/double/long double specializations of this template simply forward to the platform's native implementation of this function.

template<typename T> 
T sinc_pi(const T x);

template<typename T, template<typename> class U> 
U<T> sinc_pi(const U<T> x);

Computes the Sinus Cardinal of x. The second form is for complexes, quaternions, octonions. Use the Taylor series at the origin to ensure accuracy.

template<typename T> 
T sinhc_pi(const T x);

template<typename T, template<typename> class U> 
U<T> sinhc_pi(const U<T> x);

Computes the Hyperbolic Sinus Cardinal of x. The second form is for complexes, quaternions, octonions. Use the Taylor series at the origin to ensure accuracy.