1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
|
[section:powers Logs, Powers, Roots and Exponentials]
[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_pomotion_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 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.
[h4 Accuracy]
For built in floating point types `log1p`
should have approximately 1 epsilon accuracy.
[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]
``
#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_pomotion_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.
[h4 Accuracy]
For built in floating point types `expm1`
should have approximately 1 epsilon accuracy.
[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]
``
#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].
The return type of this function is computed using the __arg_pomotion_rules:
the return is `double` when /x/ is an integer type and T otherwise.
[optional_policy]
Implemented using Halley iteration.
[h4 Accuracy]
For built in floating-point types `cbrt`
should have approximately 2 epsilon accuracy.
[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: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_pomotion_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`.
[h4 Accuracy]
For built in floating-point types `sqrt1pm1`
should have approximately 3 epsilon accuracy.
[h4 Testing]
A selection of random high precision test values
calculated using NTL::RR at 1000-bit precision.
[endsect]
[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_pomotion_rules
when T1 and T2 are dufferent 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`.
[h4 Accuracy]
Should have approximately 2-3 epsilon accuracy.
[h4 Testing]
A selection of random high precision test values
calculated using NTL::RR at 1000-bit precision.
[endsect]
[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_pomotion_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][space] >= y] we can simply return /x/.
Otherwise the result is given by:
[equation hypot2]
[endsect]
[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).
]
|
