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 19Returns the sine of ['[pi][thin]x]. [/thin space to avoid collision of italic chars.] 20 21The return type of this function is computed using the __arg_promotion_rules: 22the return is `double` when /x/ is an integer type and T otherwise. 23 24[optional_policy] 25 26This 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 48Returns the cosine of ['[pi][thin]x]. 49 50The return type of this function is computed using the __arg_promotion_rules: 51the return is `double` when /x/ is an integer type and T otherwise. 52 53[optional_policy] 54 55This 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 77Returns the natural logarithm of /x+1/. 78 79The return type of this function is computed using the __arg_promotion_rules: 80the return is `double` when /x/ is an integer type and T otherwise. 81[optional_policy] 82 83There are many situations where it is desirable to compute `log(x+1)`. 84However, for small /x/ then /x+1/ suffers from catastrophic cancellation errors 85so that /x+1 == 1/ and /log(x+1) == 0/, when in fact for very small x, the 86best approximation to /log(x+1)/ would be /x/. `log1p` calculates the best 87approximation to `log(1+x)` using a Taylor series expansion for accuracy 88(less than __te). 89Alternatively note that there are faster methods available, 90for example using the equivalence: 91 92[:['log(1+x) == (log(1+x) * x) / ((1+x) - 1)]] 93 94However, experience has shown that these methods tend to fail quite spectacularly 95once the compiler's optimizations are turned on, consequently they are 96used only when known not to break with a particular compiler. 97In contrast, the series expansion method seems to be reasonably 98immune to optimizer-induced errors. 99 100Finally when macro BOOST_HAS_LOG1P is defined then the `float/double/long double` 101specializations of this template simply forward to the platform's 102native (POSIX) implementation of this function. 103 104The following graph illustrates the behaviour of log1p: 105 106[graph log1p] 107 108[h4 Accuracy] 109 110For built in floating point types `log1p` 111should have approximately 1 __epsilon accuracy. 112 113[table_log1p] 114 115[h4 Testing] 116 117A mixture of spot test sanity checks, and random high precision test values 118calculated 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 138Returns e[super x] - 1. 139 140The return type of this function is computed using the __arg_promotion_rules: 141the return is `double` when /x/ is an integer type and T otherwise. 142 143[optional_policy] 144 145For small /x/, then __ex is very close to 1, as a result calculating __exm1 results 146in catastrophic cancellation errors when /x/ is small. `expm1` calculates __exm1 using 147rational approximations (for up to 128-bit long doubles), otherwise via 148a series expansion when x is small (giving an accuracy of less than __te). 149 150Finally when BOOST_HAS_EXPM1 is defined then the `float/double/long double` 151specializations of this template simply forward to the platform's 152native (POSIX) implementation of this function. 153 154The following graph illustrates the behaviour of expm1: 155 156[graph expm1] 157 158[h4 Accuracy] 159 160For built in floating point types `expm1` 161should have approximately 1 epsilon accuracy. 162 163[table_expm1] 164 165[h4 Testing] 166 167A mixture of spot test sanity checks, and random high precision test values 168calculated 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 188Returns the cubed root of x: x[super 1/3] or [cbrt]x. 189 190The return type of this function is computed using the __arg_promotion_rules: 191the return is `double` when /x/ is an integer type and T otherwise. 192 193[optional_policy] 194 195Implemented using Halley iteration. 196 197The following graph illustrates the behaviour of cbrt: 198 199[graph cbrt] 200 201[h4 Accuracy] 202 203For built in floating-point types `cbrt` should have approximately 2 epsilon accuracy. 204 205[table_cbrt] 206 207[h4 Testing] 208 209A mixture of spot test sanity checks, and random high precision test values 210calculated 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 229Returns `sqrt(1+x) - 1`. 230 231The return type of this function is computed using the __arg_promotion_rules: 232the return is `double` when /x/ is an integer-type and T otherwise. 233 234[optional_policy] 235 236This function is useful when you need the difference between `sqrt(x)` and 1, when 237/x/ is itself close to 1. 238 239Implemented in terms of `log1p` and `expm1`. 240 241The following graph illustrates the behaviour of sqrt1pm1: 242 243[graph sqrt1pm1] 244 245[h4 Accuracy] 246 247For built in floating-point types `sqrt1pm1` 248should have approximately 3 epsilon accuracy. 249 250[table_sqrt1pm1] 251 252[h4 Testing] 253 254A selection of random high precision test values 255calculated 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 274Returns x[super y ] - 1. 275 276The return type of this function is computed using the __arg_promotion_rules 277when T1 and T2 are different types. 278 279[optional_policy] 280 281There are two domains where this is useful: when /y/ is very small, or when 282/x/ is close to 1. 283 284Implemented in terms of `expm1`. 285 286The following graph illustrates the behaviour of powm1: 287 288[graph powm1] 289 290[h4 Accuracy] 291 292Should have approximately 2-3 epsilon accuracy. 293 294[table_powm1] 295 296[h4 Testing] 297 298A selection of random high precision test values 299calculated 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] 312in such a way as to avoid undue underflow and overflow. 313 314The return type of this function is computed using the __arg_promotion_rules 315when T1 and T2 are of different types. 316 317[optional_policy] 318 319When calculating [equation hypot] it's quite easy for the intermediate terms to either 320overflow or underflow, even though the result is in fact perfectly representable. 321 322[h4 Implementation] 323 324The 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 327Then if ['x * [epsilon] >= y] we can simply return /x/. 328 329Otherwise 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 346