123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345 |
- [section:powers Basic Functions]
- [section:sin_pi sin_pi]
- ``
- #include <boost/math/special_functions/sin_pi.hpp>
- ``
- namespace boost{ namespace math{
-
- template <class T>
- ``__sf_result`` sin_pi(T x);
-
- template <class T, class ``__Policy``>
- ``__sf_result`` sin_pi(T x, const ``__Policy``&);
-
- }} // namespaces
-
- Returns the sine of ['[pi][thin]x]. [/thin space to avoid collision of italic chars.]
- The return type of this function is computed using the __arg_promotion_rules:
- the return is `double` when /x/ is an integer type and T otherwise.
- [optional_policy]
- This function performs exact all-integer arithmetic argument reduction before computing the sine of ['[pi][sdot]x].
- [table_sin_pi]
- [endsect] [/section:sin_pi sin_pi]
- [section:cos_pi cos_pi]
- ``
- #include <boost/math/special_functions/cos_pi.hpp>
- ``
- namespace boost{ namespace math{
-
- template <class T>
- ``__sf_result`` cos_pi(T x);
-
- template <class T, class ``__Policy``>
- ``__sf_result`` cos_pi(T x, const ``__Policy``&);
-
- }} // namespaces
-
- Returns the cosine of ['[pi][thin]x].
- The return type of this function is computed using the __arg_promotion_rules:
- the return is `double` when /x/ is an integer type and T otherwise.
- [optional_policy]
- This function performs exact all-integer arithmetic argument reduction before computing the cosine of ['[pi][cdot]x].
- [table_cos_pi]
- [endsect] [/section:cos_pi cos_pi]
- [section:log1p log1p]
- ``
- #include <boost/math/special_functions/log1p.hpp>
- ``
- namespace boost{ namespace math{
-
- template <class T>
- ``__sf_result`` log1p(T x);
-
- template <class T, class ``__Policy``>
- ``__sf_result`` log1p(T x, const ``__Policy``&);
-
- }} // namespaces
-
- Returns the natural logarithm of /x+1/.
- The return type of this function is computed using the __arg_promotion_rules:
- the return is `double` when /x/ is an integer type and T otherwise.
- [optional_policy]
- 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).
- Alternatively 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, consequently they are
- used only when known not to break with a particular compiler.
- In contrast, the series expansion method seems to be reasonably
- immune to optimizer-induced errors.
- Finally when macro BOOST_HAS_LOG1P is defined then the `float/double/long double`
- specializations of this template simply forward to the platform's
- native (POSIX) implementation of this function.
- The following graph illustrates the behaviour of log1p:
- [graph log1p]
- [h4 Accuracy]
- For built in floating point types `log1p`
- should have approximately 1 __epsilon accuracy.
- [table_log1p]
- [h4 Testing]
- A mixture of spot test sanity checks, and random high precision test values
- calculated using NTL::RR at 1000-bit precision.
- [endsect] [/section:log1p log1p]
- [section:expm1 expm1]
- ``
- #include <boost/math/special_functions/expm1.hpp>
- ``
- namespace boost{ namespace math{
-
- template <class T>
- ``__sf_result`` expm1(T x);
-
- template <class T, class ``__Policy``>
- ``__sf_result`` expm1(T x, const ``__Policy``&);
-
- }} // namespaces
-
- Returns e[super x] - 1.
- The return type of this function is computed using the __arg_promotion_rules:
- the return is `double` when /x/ is an integer type and T otherwise.
- [optional_policy]
- 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
- rational approximations (for up to 128-bit long doubles), otherwise via
- 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 (POSIX) implementation of this function.
- The following graph illustrates the behaviour of expm1:
- [graph expm1]
-
- [h4 Accuracy]
- For built in floating point types `expm1`
- should have approximately 1 epsilon accuracy.
- [table_expm1]
- [h4 Testing]
- A mixture of spot test sanity checks, and random high precision test values
- calculated using NTL::RR at 1000-bit precision.
- [endsect] [/section:expm1 expm1]
- [section:cbrt cbrt]
- ``
- #include <boost/math/special_functions/cbrt.hpp>
- ``
- namespace boost{ namespace math{
-
- template <class T>
- ``__sf_result`` cbrt(T x);
-
- template <class T, class ``__Policy``>
- ``__sf_result`` cbrt(T x, const ``__Policy``&);
-
- }} // namespaces
-
- Returns the cubed root of x: x[super 1/3] or [cbrt]x.
- The return type of this function is computed using the __arg_promotion_rules:
- the return is `double` when /x/ is an integer type and T otherwise.
- [optional_policy]
- Implemented using Halley iteration.
- The following graph illustrates the behaviour of cbrt:
- [graph cbrt]
-
- [h4 Accuracy]
- For built in floating-point types `cbrt` should have approximately 2 epsilon accuracy.
- [table_cbrt]
- [h4 Testing]
- A mixture of spot test sanity checks, and random high precision test values
- calculated using NTL::RR at 1000-bit precision.
- [endsect] [/section:cbrt cbrt]
- [section:sqrt1pm1 sqrt1pm1]
- ``
- #include <boost/math/special_functions/sqrt1pm1.hpp>
- ``
- namespace boost{ namespace math{
-
- template <class T>
- ``__sf_result`` sqrt1pm1(T x);
-
- template <class T, class ``__Policy``>
- ``__sf_result`` sqrt1pm1(T x, const ``__Policy``&);
-
- }} // namespaces
-
- Returns `sqrt(1+x) - 1`.
- The return type of this function is computed using the __arg_promotion_rules:
- the return is `double` when /x/ is an integer-type and T otherwise.
- [optional_policy]
- This function is useful when you need the difference between `sqrt(x)` and 1, when
- /x/ is itself close to 1.
- Implemented in terms of `log1p` and `expm1`.
- The following graph illustrates the behaviour of sqrt1pm1:
- [graph sqrt1pm1]
- [h4 Accuracy]
- For built in floating-point types `sqrt1pm1`
- should have approximately 3 epsilon accuracy.
- [table_sqrt1pm1]
- [h4 Testing]
- A selection of random high precision test values
- calculated using NTL::RR at 1000-bit precision.
- [endsect] [/section:sqrt1pm1 sqrt1pm1]
- [section:powm1 powm1]
- ``
- #include <boost/math/special_functions/powm1.hpp>
- ``
- namespace boost{ namespace math{
-
- template <class T1, class T2>
- ``__sf_result`` powm1(T1 x, T2 y);
-
- template <class T1, class T2, class ``__Policy``>
- ``__sf_result`` powm1(T1 x, T2 y, const ``__Policy``&);
-
- }} // namespaces
-
- Returns x[super y ] - 1.
- The return type of this function is computed using the __arg_promotion_rules
- when T1 and T2 are different types.
- [optional_policy]
- There are two domains where this is useful: when /y/ is very small, or when
- /x/ is close to 1.
- Implemented in terms of `expm1`.
- The following graph illustrates the behaviour of powm1:
- [graph powm1]
- [h4 Accuracy]
- Should have approximately 2-3 epsilon accuracy.
- [table_powm1]
- [h4 Testing]
- A selection of random high precision test values
- calculated using NTL::RR at 1000-bit precision.
- [endsect] [/section:powm1 powm1]
- [section:hypot hypot]
- template <class T1, class T2>
- ``__sf_result`` hypot(T1 x, T2 y);
-
- template <class T1, class T2, class ``__Policy``>
- ``__sf_result`` hypot(T1 x, T2 y, const ``__Policy``&);
-
- __effects computes [equation hypot]
- in such a way as to avoid undue underflow and overflow.
- The return type of this function is computed using the __arg_promotion_rules
- when T1 and T2 are of different types.
- [optional_policy]
- When calculating [equation hypot] it's quite easy for the intermediate terms to either
- overflow or underflow, even though the result is in fact perfectly representable.
- [h4 Implementation]
- The function is even and symmetric in /x/ and /y/, so first take assume
- ['x,y > 0] and ['x > y] (we can permute the arguments if this is not the case).
- Then if ['x * [epsilon] >= y] we can simply return /x/.
- Otherwise the result is given by:
- [equation hypot2]
- [endsect] [/section:hypot hypot]
- [include pow.qbk]
- [endsect] [/section:powers Logs, Powers, Roots and Exponentials]
-
- [/
- Copyright 2006 John Maddock and Paul A. Bristow.
- 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).
- ]
|