[def __asinh [link boost_math.math_special_functions.asinh asinh]]
[def __acosh [link boost_math.math_special_functions.acosh acosh]]
[def __atanh [link boost_math.math_special_functions.atanh atanh]]
[def __sinc_pi [link boost_math.math_special_functions.sinc_pi sinc_pi]]
[def __sinhc_pi [link boost_math.math_special_functions.sinhc_pi sinhc_pi]]
[def __log1p [link boost_math.math_special_functions.log1p log1p]]
[def __expm1 [link boost_math.math_special_functions.expm1 expm1]]
[def __hypot [link boost_math.math_special_functions.hypot hypot]]
[def __form1 [^\[0;+'''∞'''\[]]
[def __form2 [^\]-'''∞''';+1\[]]
[def __form3 [^\]-'''∞''';-1\[]]
[def __form4 [^\]+1;+'''∞'''\[]]
[def __form5 `[^\[-1;-1+'''ε'''\[]]
[def __form6 '''ε''']
[def __form7 [^\]+1-'''ε''';+1\]]]
[def __effects [*Effects: ]]
[def __formula [*Formula: ]]
[def __exm1 '''ex - 1''']
[def __ex '''ex''']
[def __te '''2ε''']
[section Math Special Functions]
[section Overview]
The Special Functions library currently provides eight templated special functions,
in namespace boost. Two of these (__sinc_pi and __sinhc_pi) are needed by our
implementation of quaternions and octonions.
The functions __acosh, __asinh and __atanh are entirely classical,
the function __sinc_pi sees heavy use 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++. Two of these (__log1p and __hypot) were needed for the
[link boost_math.inverse_complex complex number inverse trigonometric functions].
The functions implemented here can throw standard exceptions, but no
exception specification has been made.
[endsect]
[section Header Files]
The interface and implementation for each function (or forms of a function)
are both supplied by one header file:
* [@../../boost/math/special_functions/acosh.hpp acosh.hpp]
* [@../../boost/math/special_functions/asinh.hpp asinh.hpp]
* [@../../boost/math/special_functions/atanh.hpp atanh.hpp]
* [@../../boost/math/special_functions/expm1.hpp expm1.hpp]
* [@../../boost/math/special_functions/hypot.hpp hypot.hpp]
* [@../../boost/math/special_functions/log1p.hpp log1p.hpp]
* [@../../boost/math/special_functions/sinc.hpp sinc.hpp]
* [@../../boost/math/special_functions/sinhc.hpp sinhc.hpp]
[endsect]
[section Synopsis]
namespace boost{ namespace math{
template
T __acosh(const T x);
template
T __asinh(const T x);
template
T __atanh(const T x);
template
T __expm1(const T x);
template
T __hypot(const T x);
template
T __log1p(const T x);
template
T __sinc_pi(const T x);
template class U>
U __sinc_pi(const U x);
template
T __sinhc_pi(const T x);
template class U>
U __sinhc_pi(const U x);
}
}
[endsect]
[section acosh]
template
T acosh(const T x);
Computes the reciprocal of (the restriction to the range of __form1)
[link boost_math.background_information_and_white_papers.the_inverse_hyperbolic_functions
the hyperbolic cosine function], at x. Values returned are positive. Generalised
Taylor series are used near 1 and Laurent series are used near the
infinity to ensure accuracy.
If x is in the range __form2 a quiet NaN is returned (if the system allows,
otherwise a `domain_error` exception is generated).
[endsect]
[section asinh]
template
T asinh(const T x);
Computes the reciprocal of
[link boost_math.background_information_and_white_papers.the_inverse_hyperbolic_functions
the hyperbolic sine function].
Taylor series are used at the origin and Laurent series are used near the
infinity to ensure accuracy.
[endsect]
[section atanh]
template
T atanh(const T x);
Computes the reciprocal of
[link boost_math.background_information_and_white_papers.the_inverse_hyperbolic_functions
the hyperbolic tangent function], at x.
Taylor series are used at the origin to ensure accuracy.
If x is in the range
__form3
or in the range
__form4
a quiet NaN is returned
(if the system allows, otherwise a `domain_error` exception is generated).
If x is in the range
__form5,
minus infinity is returned
(if the system allows, otherwise an `out_of_range` exception
is generated), with
__form6
denoting numeric_limits::epsilon().
If x is in the range
__form7,
plus infinity is returned (if the system allows,
otherwise an `out_of_range` exception is generated), with
__form6
denoting
numeric_limits::epsilon().
[endsect]
[section:expm1 expm1]
template
T expm1(T t);
__effects returns __exm1.
For small x, then __ex is very close to 1, as a result calculating __exm1 results
in catastrophic cancellation errors when x is small. `expm1` calculates __exm1 using
a series expansion when x is small (giving an accuracy of less than __te).
Finally when BOOST_HAS_EXPM1 is defined then the `float/double/long double`
specializations of this template simply forward to the platform's
native implementation of this function.
[endsect]
[section:hypot hypot]
template
T hypot(T x, T y);
__effects computes [$../../libs/math/doc/images/hypot.png] in such a way as to avoid undue underflow and overflow.
When calculating [$../../libs/math/doc/images/hypot.png] it's quite easy for the intermediate terms to either
overflow or underflow, even though the result is in fact perfectly representable.
One possible alternative form is [$../../libs/math/doc/images/hypot2.png], 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 you, so you don't have to.
[endsect]
[section:log1p log1p]
template
T log1p(T x);
__effects 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 __te).
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 quite spectacularly
once the compiler's optimizations are turned on. In contrast, the series expansion
method seems to be reasonably immune 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.
[endsect]
[section sinc_pi]
template
T sinc_pi(const T x);
template class U>
U sinc_pi(const U x);
Computes
[link boost_math.background_information_and_white_papers.sinus_cardinal_and_hyperbolic_sinus_cardinal_functions
the Sinus Cardinal] of x. The second form is for complexes,
quaternions, octonions... Taylor series are used at the origin
to ensure accuracy.
[endsect]
[section sinhc_pi]
template
T sinhc_pi(const T x);
template class U>
U sinhc_pi(const U x);
Computes
[link boost_math.background_information_and_white_papers.sinus_cardinal_and_hyperbolic_sinus_cardinal_functions
the Hyperbolic Sinus Cardinal] of x. The second form is for
complexes, quaternions, octonions... Taylor series are used at the origin
to ensure accuracy.
[endsect]
[section Test Programs]
The [@../../libs/math/special_functions/special_functions_test.cpp
special_functions_test.cpp]
and [@../../libs/math/test/log1p_expm1_test.cpp log1p_expm1_test.cpp] test programs test the functions for
float, double and long double arguments ([@../../libs/math/special_functions/output.txt sample output], with message
output enabled).
If you define the symbol BOOST_SPECIAL_FUNCTIONS_TEST_VERBOSE, you will
get additional output
([@../../libs/math/special_functions/output_more.txt verbose output]),
which may prove useful for
tuning on your platform (the library use "reasonable" tolerances,
which may prove to be too strict for your platform); this will only be
helpfull if you enable message output at the same time, of course
(by uncommenting the relevant line in the test or by adding `--log_level=messages`
to your command line,...).
[endsect]
[section Acknowledgements]
The mathematical text has been typeset with [@http://www.nisus-soft.com/
Nisus Writer], and the
illustrations have been made with [@http://www.pacifict.com/
Graphing Calculator]. Jens Maurer
was the Review Manager for this library. More acknowledgements in the
History section. Thank you to all who contributed to the discution
about this library.
[endsect]
[section History]
* 1.5.0 - 17/12/2005: John Maddock added __log1p, __expm1 and __hypot. Converted documentation to Quickbook Format.
* 1.4.2 - 03/02/2003: transitionned to the unit test framework; now included by the library headers (rather than the test files).
* 1.4.1 - 18/09/2002: improved compatibility with Microsoft compilers.
* 1.4.0 - 14/09/2001: added (after rewrite) __acosh and __asinh, which were submited by Eric Ford; applied changes for Gcc 2.9.x suggested by John Maddock; improved accuracy; sanity check for test file, related to accuracy.
* 1.3.2 - 07/07/2001: introduced namespace math.
* 1.3.1 - 07/06/2001:(end of Boost review) split special_functions.hpp into atanh.hpp, sinc.hpp and sinhc.hpp; improved efficiency of __atanh with compile-time technique (Daryle Walker); improved accuracy of all functions near zero (Peter Schmitteckert).
* 1.3.0 - 26/03/2001: support for complexes & all, for cardinal functions.
* 1.2.0 - 31/01/2001: minor modifications for Koenig lookup.
* 1.1.0 - 23/01/2001: boostification.
* 1.0.0 - 10/08/1999: first public version.
[endsect]
[section To Do]
* Add more functions.
* Improve test of each function.
[endsect]
[endsect]