libs/math/doc/sf/powers.qbk

   1 [section:powers Basic Functions]
   2
   3 [section:sin_pi sin_pi]
   4
   5 ``
   6 #include <boost/math/special_functions/sin_pi.hpp>
   7 ``
   8
   9    namespace boost{ namespace math{
  10
  11    template <class T>
  12    ``__sf_result`` sin_pi(T x);
  13
  14    template <class T, class ``__Policy``>
  15    ``__sf_result`` sin_pi(T x, const ``__Policy``&);
  16
  17    }} // namespaces
  18
  19 Returns the sine of ['[pi][thin]x]. [/thin space to avoid collision of italic chars.]
  20
  21 The return type of this function is computed using the __arg_promotion_rules:
  22 the return is `double` when /x/ is an integer type and T otherwise.
  23
  24 [optional_policy]
  25
  26 This function performs exact all-integer arithmetic argument reduction before computing the sine of ['[pi][sdot]x].
  27
  28 [table_sin_pi]
  29
  30 [endsect] [/section:sin_pi sin_pi]
  31
  32 [section:cos_pi cos_pi]
  33
  34 ``
  35 #include <boost/math/special_functions/cos_pi.hpp>
  36 ``
  37
  38    namespace boost{ namespace math{
  39
  40    template <class T>
  41    ``__sf_result`` cos_pi(T x);
  42
  43    template <class T, class ``__Policy``>
  44    ``__sf_result`` cos_pi(T x, const ``__Policy``&);
  45
  46    }} // namespaces
  47
  48 Returns the cosine of ['[pi][thin]x].
  49
  50 The return type of this function is computed using the __arg_promotion_rules:
  51 the return is `double` when /x/ is an integer type and T otherwise.
  52
  53 [optional_policy]
  54
  55 This function performs exact all-integer arithmetic argument reduction before computing the cosine of ['[pi][cdot]x].
  56
  57 [table_cos_pi]
  58
  59 [endsect] [/section:cos_pi cos_pi]
  60
  61 [section:log1p log1p]
  62
  63 ``
  64 #include <boost/math/special_functions/log1p.hpp>
  65 ``
  66
  67    namespace boost{ namespace math{
  68
  69    template <class T>
  70    ``__sf_result`` log1p(T x);
  71
  72    template <class T, class ``__Policy``>
  73    ``__sf_result`` log1p(T x, const ``__Policy``&);
  74
  75    }} // namespaces
  76
  77 Returns the natural logarithm of /x+1/.
  78
  79 The return type of this function is computed using the __arg_promotion_rules:
  80 the return is `double` when /x/ is an integer type and T otherwise.
  81 [optional_policy]
  82
  83 There are many situations where it is desirable to compute `log(x+1)`.
  84 However, for small /x/ then /x+1/ suffers from catastrophic cancellation errors
  85 so that /x+1 == 1/ and /log(x+1) == 0/, when in fact for very small x, the
  86 best approximation to /log(x+1)/ would be /x/.  `log1p` calculates the best
  87 approximation to `log(1+x)` using a Taylor series expansion for accuracy
  88 (less than __te).
  89 Alternatively note that there are faster methods available,
  90 for example using the equivalence:
  91
  92 [:['log(1+x) == (log(1+x) * x) / ((1+x) - 1)]]
  93
  94 However, experience has shown that these methods tend to fail quite spectacularly
  95 once the compiler's optimizations are turned on, consequently they are
  96 used only when known not to break with a particular compiler.
  97 In contrast, the series expansion method seems to be reasonably
  98 immune to optimizer-induced errors.
  99
 100 Finally when macro BOOST_HAS_LOG1P is defined then the `float/double/long double`
 101 specializations of this template simply forward to the platform's
 102 native (POSIX) implementation of this function.
 103
 104 The following graph illustrates the behaviour of log1p:
 105
 106 [graph log1p]
 107
 108 [h4 Accuracy]
 109
 110 For built in floating point types `log1p`
 111 should have approximately 1 __epsilon accuracy.
 112
 113 [table_log1p]
 114
 115 [h4 Testing]
 116
 117 A mixture of spot test sanity checks, and random high precision test values
 118 calculated using NTL::RR at 1000-bit precision.
 119
 120 [endsect] [/section:log1p log1p]
 121
 122 [section:expm1 expm1]
 123
 124 ``
 125 #include <boost/math/special_functions/expm1.hpp>
 126 ``
 127
 128    namespace boost{ namespace math{
 129
 130    template <class T>
 131    ``__sf_result`` expm1(T x);
 132
 133    template <class T, class ``__Policy``>
 134    ``__sf_result`` expm1(T x, const ``__Policy``&);
 135
 136    }} // namespaces
 137
 138 Returns e[super x] - 1.
 139
 140 The return type of this function is computed using the __arg_promotion_rules:
 141 the return is `double` when /x/ is an integer type and T otherwise.
 142
 143 [optional_policy]
 144
 145 For small /x/, then __ex is very close to 1, as a result calculating __exm1 results
 146 in catastrophic cancellation errors when /x/ is small.  `expm1` calculates __exm1 using
 147 rational approximations (for up to 128-bit long doubles), otherwise via
 148 a series expansion when x is small (giving an accuracy of less than __te).
 149
 150 Finally when BOOST_HAS_EXPM1 is defined then the `float/double/long double`
 151 specializations of this template simply forward to the platform's
 152 native (POSIX) implementation of this function.
 153
 154 The following graph illustrates the behaviour of expm1:
 155
 156 [graph expm1]
 157
 158 [h4 Accuracy]
 159
 160 For built in floating point types `expm1`
 161 should have approximately 1 epsilon accuracy.
 162
 163 [table_expm1]
 164
 165 [h4 Testing]
 166
 167 A mixture of spot test sanity checks, and random high precision test values
 168 calculated using NTL::RR at 1000-bit precision.
 169
 170 [endsect] [/section:expm1 expm1]
 171
 172 [section:cbrt cbrt]
 173
 174 ``
 175 #include <boost/math/special_functions/cbrt.hpp>
 176 ``
 177
 178    namespace boost{ namespace math{
 179
 180    template <class T>
 181    ``__sf_result`` cbrt(T x);
 182
 183    template <class T, class ``__Policy``>
 184    ``__sf_result`` cbrt(T x, const ``__Policy``&);
 185
 186    }} // namespaces
 187
 188 Returns the cubed root of x: x[super 1/3] or [cbrt]x.
 189
 190 The return type of this function is computed using the __arg_promotion_rules:
 191 the return is `double` when /x/ is an integer type and T otherwise.
 192
 193 [optional_policy]
 194
 195 Implemented using Halley iteration.
 196
 197 The following graph illustrates the behaviour of cbrt:
 198
 199 [graph cbrt]
 200
 201 [h4 Accuracy]
 202
 203 For built in floating-point types `cbrt` should have approximately 2 epsilon accuracy.
 204
 205 [table_cbrt]
 206
 207 [h4 Testing]
 208
 209 A mixture of spot test sanity checks, and random high precision test values
 210 calculated using NTL::RR at 1000-bit precision.
 211
 212 [endsect] [/section:cbrt cbrt]
 213
 214 [section:sqrt1pm1 sqrt1pm1]
 215
 216 ``
 217 #include <boost/math/special_functions/sqrt1pm1.hpp>
 218 ``
 219    namespace boost{ namespace math{
 220
 221    template <class T>
 222    ``__sf_result`` sqrt1pm1(T x);
 223
 224    template <class T, class ``__Policy``>
 225    ``__sf_result`` sqrt1pm1(T x, const ``__Policy``&);
 226
 227    }} // namespaces
 228
 229 Returns `sqrt(1+x) - 1`.
 230
 231 The return type of this function is computed using the __arg_promotion_rules:
 232 the return is `double` when /x/ is an integer-type and T otherwise.
 233
 234 [optional_policy]
 235
 236 This function is useful when you need the difference between `sqrt(x)` and 1, when
 237 /x/ is itself close to 1.
 238
 239 Implemented in terms of `log1p` and `expm1`.
 240
 241 The following graph illustrates the behaviour of sqrt1pm1:
 242
 243 [graph sqrt1pm1]
 244
 245 [h4 Accuracy]
 246
 247 For built in floating-point types `sqrt1pm1`
 248 should have approximately 3 epsilon accuracy.
 249
 250 [table_sqrt1pm1]
 251
 252 [h4 Testing]
 253
 254 A selection of random high precision test values
 255 calculated using NTL::RR at 1000-bit precision.
 256
 257 [endsect] [/section:sqrt1pm1 sqrt1pm1]
 258
 259 [section:powm1 powm1]
 260
 261 ``
 262 #include <boost/math/special_functions/powm1.hpp>
 263 ``
 264    namespace boost{ namespace math{
 265
 266    template <class T1, class T2>
 267    ``__sf_result`` powm1(T1 x, T2 y);
 268
 269    template <class T1, class T2, class ``__Policy``>
 270    ``__sf_result`` powm1(T1 x, T2 y, const ``__Policy``&);
 271
 272    }} // namespaces
 273
 274 Returns x[super y ] - 1.
 275
 276 The return type of this function is computed using the __arg_promotion_rules
 277 when T1 and T2 are different types.
 278
 279 [optional_policy]
 280
 281 There are two domains where this is useful: when /y/ is very small, or when
 282 /x/ is close to 1.
 283
 284 Implemented in terms of `expm1`.
 285
 286 The following graph illustrates the behaviour of powm1:
 287
 288 [graph powm1]
 289
 290 [h4 Accuracy]
 291
 292 Should have approximately 2-3 epsilon accuracy.
 293
 294 [table_powm1]
 295
 296 [h4 Testing]
 297
 298 A selection of random high precision test values
 299 calculated using NTL::RR at 1000-bit precision.
 300
 301 [endsect] [/section:powm1 powm1]
 302
 303 [section:hypot hypot]
 304
 305    template <class T1, class T2>
 306    ``__sf_result`` hypot(T1 x, T2 y);
 307
 308    template <class T1, class T2, class ``__Policy``>
 309    ``__sf_result`` hypot(T1 x, T2 y, const ``__Policy``&);
 310
 311 __effects computes [equation hypot]
 312 in such a way as to avoid undue underflow and overflow.
 313
 314 The return type of this function is computed using the __arg_promotion_rules
 315 when T1 and T2 are of different types.
 316
 317 [optional_policy]
 318
 319 When calculating [equation hypot] it's quite easy for the intermediate terms to either
 320 overflow or underflow, even though the result is in fact perfectly representable.
 321
 322 [h4 Implementation]
 323
 324 The function is even and symmetric in /x/ and /y/, so first take assume
 325 ['x,y > 0] and ['x > y] (we can permute the arguments if this is not the case).
 326
 327 Then if ['x * [epsilon] >= y] we can simply return /x/.
 328
 329 Otherwise the result is given by:
 330
 331 [equation hypot2]
 332
 333 [endsect] [/section:hypot hypot]
 334
 335 [include pow.qbk]
 336
 337 [endsect] [/section:powers Logs, Powers, Roots and Exponentials]
 338
 339 [/
 340   Copyright 2006 John Maddock and Paul A. Bristow.
 341   Distributed under the Boost Software License, Version 1.0.
 342   (See accompanying file LICENSE_1_0.txt or copy at
 343   http://www.boost.org/LICENSE_1_0.txt).
 344 ]
 345