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