xref: /third_party/boost/libs/math/doc/sf/inv_hyper.qbk

[/ math.qbk
  Copyright 2006 Hubert Holin and John Maddock.
  Distributed under the Boost Software License, Version 1.0.
  (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt).
]

[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 '''<code>e<superscript>x</superscript> - 1</code>''']
[def __ex '''<code>e<superscript>x</superscript></code>''']
[def __te '''2&#x03B5;''']

[section:inv_hyper Inverse Hyperbolic Functions]

[section:inv_hyper_over Inverse Hyperbolic Functions Overview]

The exponential function is defined, for all objects for which this makes sense,
as the power series
[equation special_functions_blurb1]
with ['[^n! = 1x2x3x4x5...xn]] (and ['[^0! = 1]] by definition) being the factorial of ['[^n]].
In particular, the exponential function is well defined for real numbers,
complex number, quaternions, octonions, and matrices of complex numbers,
among others.

[: ['[*Graph of exp on R]] ]

[: [$../graphs/exp_on_r.png] ]

[: ['[*Real and Imaginary parts of exp on C]]]
[: [$../graphs/im_exp_on_c.png]]

The hyperbolic functions are defined as power series which
can be computed (for reals, complex, quaternions and octonions) as:

Hyperbolic cosine: [equation special_functions_blurb5]

Hyperbolic sine: [equation special_functions_blurb6]

Hyperbolic tangent: [equation special_functions_blurb7]

[: ['[*Trigonometric functions on R (cos: purple; sin: red; tan: blue)]]]
[: [$../graphs/trigonometric.png]]

[: ['[*Hyperbolic functions on r (cosh: purple; sinh: red; tanh: blue)]]]
[: [$../graphs/hyperbolic.png]]

The hyperbolic sine is one to one on the set of real numbers,
with range the full set of reals, while the hyperbolic tangent is
also one to one on the set of real numbers but with range __form1, and
therefore both have inverses.

The hyperbolic cosine is one to one from __form2 onto __form3 (and from __form4 onto __form3).

The inverse function we use here is defined on __form3 with range __form2.

The inverse of the hyperbolic tangent is called the Argument hyperbolic tangent,
and can be computed as [equation special_functions_blurb15]

The inverse of the hyperbolic sine is called the Argument hyperbolic sine,
and can be computed (for __form5) as [equation special_functions_blurb17]

The inverse of the hyperbolic cosine is called the Argument hyperbolic cosine,
and can be computed as [equation special_functions_blurb18]

[endsect] [/section:inv_hyper_over Inverse Hyperbolic Functions Overview]

[section:acosh acosh]

``
#include <boost/math/special_functions/acosh.hpp>
``

   template<class T>
   ``__sf_result`` acosh(const T x);

   template<class T, class ``__Policy``>
   ``__sf_result`` acosh(const T x, const ``__Policy``&);

Computes the reciprocal of (the restriction to the range of __form1)
[link math_toolkit.inv_hyper.inv_hyper_over
the hyperbolic cosine function], at x. Values returned are positive.

If x is in the range __form2 then returns the result of __domain_error.

The return type of this function is computed using the __arg_promotion_rules:
the return type is `double` when T is an integer type, and T otherwise.

[optional_policy]

[graph acosh]

[h4 Accuracy]

Generally accuracy is to within 1 or 2 __epsilon across all supported platforms.

[h4 Testing]

This function is tested using a combination of random test values designed to give
full function coverage computed at high precision using the "naive" formula:

[equation acosh1]

along with a selection of sanity check values
computed using functions.wolfram.com to at least 50 decimal digits.

[h4 Implementation]

For sufficiently large x, we can use the
[@http://functions.wolfram.com/ElementaryFunctions/ArcCosh/06/01/06/01/0001/
approximation]:

[equation acosh2]

For x sufficiently close to 1 we can use the
[@http://functions.wolfram.com/ElementaryFunctions/ArcCosh/06/01/04/01/0001/
approximation]:

[equation acosh4]

Otherwise for x close to 1 we can use the following rearrangement of the
primary definition to preserve accuracy:

[equation acosh3]

Otherwise the
[@http://functions.wolfram.com/ElementaryFunctions/ArcCosh/02/
primary definition] is used:

[equation acosh1]

[endsect] [/section:acosh acosh]

[section:asinh asinh]

``
#include <boost/math/special_functions/asinh.hpp>
``

   template<class T>
   ``__sf_result`` asinh(const T x);

   template<class T, class ``__Policy``>
   ``__sf_result`` asinh(const T x, const ``__Policy``&);

Computes the reciprocal of
[link math_toolkit.inv_hyper.inv_hyper_over
the hyperbolic sine function].

The return type of this function is computed using the __arg_promotion_rules:
the return type is `double` when T is an integer type, and T otherwise.

[graph asinh]

[optional_policy]

[h4 Accuracy]

Generally accuracy is to within 1 or 2 __epsilon across all supported platforms.

[h4 Testing]

This function is tested using a combination of random test values designed to give
full function coverage computed at high precision using the "naive" formula:

[equation asinh1]

along with a selection of sanity check values
computed using functions.wolfram.com to at least 50 decimal digits.

[h4 Implementation]

For sufficiently large x we can use the
[@http://functions.wolfram.com/ElementaryFunctions/ArcSinh/06/01/06/01/0001/
approximation]:

[equation asinh2]

While for very small x we can use the
[@http://functions.wolfram.com/ElementaryFunctions/ArcSinh/06/01/03/01/0001/
approximation]:

[equation asinh3]

For 0.5 > x > [epsilon] the following rearrangement of the primary definition is used:

[equation asinh4]

Otherwise evaluation is via the
[@http://functions.wolfram.com/ElementaryFunctions/ArcSinh/02/
primary definition]:

[equation asinh4]

[endsect] [/section:asinh asinh]

[section:atanh atanh]

``
#include <boost/math/special_functions/atanh.hpp>
``

   template<class T>
   ``__sf_result`` atanh(const T x);

   template<class T, class ``__Policy``>
   ``__sf_result`` atanh(const T x, const ``__Policy``&);

Computes the reciprocal of
[link math_toolkit.inv_hyper.inv_hyper_over
the hyperbolic tangent function], at x.

[optional_policy]

If x is in the range
__form3
or in the range
__form4
then returns the result of __domain_error.

If x is in the range
__form5,
then the result of -__overflow_error is returned, with
__form6
denoting `std::numeric_limits<T>::epsilon()`.

If x is in the range
__form7,
then the result of __overflow_error is returned, with
__form6
denoting
`std::numeric_limits<T>::epsilon()`.

The return type of this function is computed using the __arg_promotion_rules:
the return type is `double` when T is an integer type, and T otherwise.

[graph atanh]

[h4 Accuracy]

Generally accuracy is to within 1 or 2 __epsilon across all supported platforms.

[h4 Testing]

This function is tested using a combination of random test values designed to give
full function coverage computed at high precision using the "naive" formula:

[equation atanh1]

along with a selection of sanity check values
computed using functions.wolfram.com to at least 50 decimal digits.

[h4 Implementation]

For sufficiently small x we can use the
[@http://functions.wolfram.com/ElementaryFunctions/ArcTanh/06/01/03/01/ approximation]:

[equation atanh2]

Otherwise the
[@http://functions.wolfram.com/ElementaryFunctions/ArcTanh/02/ primary definition]:

[equation atanh1]

or its equivalent form:

[equation atanh3]

is used.

[endsect] [/section:atanh atanh]

[endsect] [/section:inv_hyper Inverse Hyperbolic Functions]