3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>Math Constants FAQs</title>
5 <link rel="stylesheet" href="../math.css" type="text/css">
6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
7 <link rel="home" href="../index.html" title="Math Toolkit 2.11.0">
8 <link rel="up" href="../constants.html" title="Chapter 4. Mathematical Constants">
9 <link rel="prev" href="new_const.html" title="Defining New Constants">
10 <link rel="next" href="../dist.html" title="Chapter 5. Statistical Distributions and Functions">
12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13 <table cellpadding="2" width="100%"><tr>
14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
15 <td align="center"><a href="../../../../../index.html">Home</a></td>
16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
22 <div class="spirit-nav">
23 <a accesskey="p" href="new_const.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../constants.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../dist.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
27 <a name="math_toolkit.constants_faq"></a><a class="link" href="constants_faq.html" title="Math Constants FAQs">Math Constants FAQs</a>
28 </h2></div></div></div>
30 <a name="math_toolkit.constants_faq.h0"></a>
31 <span class="phrase"><a name="math_toolkit.constants_faq.why_are_these_constants_chosen"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.why_are_these_constants_chosen">Why are
32 <span class="emphasis"><em>these</em></span> Constants Chosen?</a>
35 It is, of course, impossible to please everyone with a list like this.
38 Some of the criteria we have used are:
40 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
54 <a href="http://en.wikipedia.org/wiki/Mathematical_constant" target="_top">Used in
55 science and mathematics.</a>
58 No integer values (because so cheap to construct).
62 (You can easily define your own if found convenient, for example: <code class="computeroutput"><span class="identifier">FPT</span> <span class="identifier">one</span> <span class="special">=</span><span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">FPT</span><span class="special">>(</span><span class="number">42</span><span class="special">);</span></code>).
65 <a name="math_toolkit.constants_faq.h1"></a>
66 <span class="phrase"><a name="math_toolkit.constants_faq.how_are_constants_named"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.how_are_constants_named">How
67 are constants named?</a>
69 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
71 Not macros, so no upper case.
74 All lower case (following C++ standard names).
80 Underscore as _ delimiter between words.
83 Numbers spelt as words rather than decimal digits (except following pow).
86 Abbreviation conventions:
87 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
95 pow for pow function using decimal digits like pow23 for n<sup>2/3</sup>.
98 div for divided by or operator /.
100 <li class="listitem">
101 minus for operator -, plus for operator +.
103 <li class="listitem">
106 <li class="listitem">
107 cubed for cubed n<sup>3</sup>.
109 <li class="listitem">
110 words for greek, like π, ζ and Γ.
112 <li class="listitem">
113 words like half, third, three_quarters, sixth for fractions. (Digit(s)
116 <li class="listitem">
117 log10 for log<sub>10</sub>
119 <li class="listitem">
120 ln for log<sub>e</sub>
126 <a name="math_toolkit.constants_faq.h2"></a>
127 <span class="phrase"><a name="math_toolkit.constants_faq.how_are_the_constants_derived"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.how_are_the_constants_derived">How are
128 the constants derived?</a>
131 The constants have all been calculated using high-precision software working
132 with up to 300-bit precision giving about 100 decimal digits. (The precision
133 can be arbitrarily chosen and is limited only by compute time).
136 <a name="math_toolkit.constants_faq.h3"></a>
137 <span class="phrase"><a name="math_toolkit.constants_faq.how_accurate_are_the_constants"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.how_accurate_are_the_constants">How Accurate
138 are the constants?</a>
141 The minimum accuracy chosen (100 decimal digits) exceeds the accuracy of reasonably-foreseeable
142 floating-point hardware (256-bit) and should meet most high-precision computations.
145 <a name="math_toolkit.constants_faq.h4"></a>
146 <span class="phrase"><a name="math_toolkit.constants_faq.how_are_the_constants_tested"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.how_are_the_constants_tested">How are the
147 constants tested?</a>
149 <div class="orderedlist"><ol class="orderedlist" type="1">
150 <li class="listitem">
151 Comparison using Boost.Test BOOST_CHECK_CLOSE_FRACTION using long double
152 literals, with at least 35 decimal digits, enough to be accurate for all
153 long double implementations. The tolerance is usually twice <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span> <span class="identifier">epsilon</span></code>.
155 <li class="listitem">
156 Comparison with calculation at long double precision. This often requires
157 a slightly higher tolerance than two epsilon because of computational noise
158 from round-off etc, especially when trig and other functions are called.
160 <li class="listitem">
161 Comparison with independent published values, for example, using <a href="http://oeis.org/" target="_top">The On-Line Encyclopedia of Integer Sequences (OEIS)</a>
162 again using at least 35 decimal digits strings.
164 <li class="listitem">
165 Comparison with independely calculated values using arbitrary precision
166 tools like <a href="http://www.wolfram.com/mathematica/" target="_top">Mathematica</a>,
167 again using at least 35 decimal digits literal strings.
170 <div class="warning"><table border="0" summary="Warning">
172 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
173 <th align="left">Warning</th>
175 <tr><td align="left" valign="top"><p>
176 We have not yet been able to <span class="bold"><strong>check</strong></span> that
177 <span class="bold"><strong>all</strong></span> constants are accurate at the full arbitrary
178 precision, at present 100 decimal digits. But certain key values like <code class="computeroutput"><span class="identifier">e</span></code> and <code class="computeroutput"><span class="identifier">pi</span></code>
179 appear to be accurate and internal consistencies suggest that others are
184 <a name="math_toolkit.constants_faq.h5"></a>
185 <span class="phrase"><a name="math_toolkit.constants_faq.why_is_portability_important"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.why_is_portability_important">Why is Portability
189 Code written using math constants is easily portable even when using different
190 floating-point types with differing precision.
193 It is a mistake to expect that results of computations will be <span class="bold"><strong>identical</strong></span>,
194 but you can achieve the <span class="bold"><strong>best accuracy possible for the
195 floating-point type in use</strong></span>.
198 This has no extra cost to the user, but reduces irritating, and often confusing
199 and very hard-to-trace effects, caused by the intrinsically limited precision
200 of floating-point calculations.
203 A harmless symptom of this limit is a spurious least-significant digit; at
204 worst, slightly inaccurate constants sometimes cause iterating algorithms to
205 diverge wildly because internal comparisons just fail.
208 <a name="math_toolkit.constants_faq.h6"></a>
209 <span class="phrase"><a name="math_toolkit.constants_faq.what_is_the_internal_format_of_t"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.what_is_the_internal_format_of_t">What
210 is the Internal Format of the constants, and why?</a>
213 See <a class="link" href="tutorial.html" title="Tutorial">tutorial</a> above for normal
214 use, but this FAQ explains the internal details used for the constants.
217 Constants are stored as 100 decimal digit values. However, some compilers do
218 not accept decimal digits strings as long as this. So the constant is split
219 into two parts, with the first containing at least 128-bit long double precision
220 (35 decimal digits), and for consistency should be in scientific format with
224 The second part is the value of the constant expressed as a string literal,
225 accurate to at least 100 decimal digits (in practice that means at least 102
226 digits). Again for consistency use scientific format with a signed exponent.
229 For types with precision greater than a long double, then if T is constructible
230 <code class="computeroutput"><span class="identifier">T</span> </code>is constructible from a
231 <code class="computeroutput"><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span></code> then it's directly constructed from the string,
232 otherwise we fall back on lexical_cast to convert to type <code class="computeroutput"><span class="identifier">T</span></code>.
233 (Using a string is necessary because you can't use a numeric constant since
234 even a <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>
235 might not have enough digits).
238 So, for example, a constant like pi is internally defined as
240 <pre class="programlisting"><span class="identifier">BOOST_DEFINE_MATH_CONSTANT</span><span class="special">(</span><span class="identifier">pi</span><span class="special">,</span> <span class="number">3.141592653589793238462643383279502884e+00</span><span class="special">,</span> <span class="string">"3.14159265358979323846264338327950288419716939937510582097494459230781640628620899862803482534211706798214808651e+00"</span><span class="special">);</span>
243 In this case the significand is 109 decimal digits, ensuring 100 decimal digits
244 are exact, and exponent is zero.
247 See <a class="link" href="new_const.html" title="Defining New Constants">defining new constants</a> to
248 calculate new constants.
251 A macro definition like this can be pasted into user code where convenient,
252 or into <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">constants</span><span class="special">.</span><span class="identifier">hpp</span></code> if it
253 is to be added to the Boost.Math library.
256 <a name="math_toolkit.constants_faq.h7"></a>
257 <span class="phrase"><a name="math_toolkit.constants_faq.what_floating_point_types_could_"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.what_floating_point_types_could_">What
258 Floating-point Types could I use?</a>
261 Apart from the built-in floating-point types <code class="computeroutput"><span class="keyword">float</span></code>,
262 <code class="computeroutput"><span class="keyword">double</span></code>, <code class="computeroutput"><span class="keyword">long</span>
263 <span class="keyword">double</span></code>, there are several arbitrary
264 precision floating-point classes available, but most are not licensed for commercial
268 <a name="math_toolkit.constants_faq.h8"></a>
269 <span class="phrase"><a name="math_toolkit.constants_faq.boost_multiprecision_by_christop"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.boost_multiprecision_by_christop">Boost.Multiprecision
270 by Christopher Kormanyos</a>
273 This work is based on an earlier work called e-float: Algorithm 910: A Portable
274 C++ Multiple-Precision System for Special-Function Calculations, in ACM TOMS,
275 {VOL 37, ISSUE 4, (February 2011)} (C) ACM, 2011. <a href="http://doi.acm.org/10.1145/1916461.1916469" target="_top">http://doi.acm.org/10.1145/1916461.1916469</a>
276 <a href="https://svn.boost.org/svn/boost/sandbox/e_float/" target="_top">e_float</a>
277 but is now re-factored and available under the Boost license in the Boost-sandbox
278 at <a href="https://svn.boost.org/svn/boost/sandbox/multiprecision/" target="_top">multiprecision</a>
279 where it is being refined and prepared for review.
282 <a name="math_toolkit.constants_faq.h9"></a>
283 <span class="phrase"><a name="math_toolkit.constants_faq.boost_cpp_float_by_john_maddock_"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.boost_cpp_float_by_john_maddock_">Boost.cpp_float
284 by John Maddock using Expression Templates</a>
287 <a href="https://svn.boost.org/svn/boost/sandbox/big_number/" target="_top">Big Number</a>
288 which is a reworking of <a href="https://svn.boost.org/svn/boost/sandbox/e_float/" target="_top">e_float</a>
289 by Christopher Kormanyos to use expression templates for faster execution.
292 <a name="math_toolkit.constants_faq.h10"></a>
293 <span class="phrase"><a name="math_toolkit.constants_faq.ntl_class_quad_float"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.ntl_class_quad_float">NTL
297 <a href="http://shoup.net/ntl/" target="_top">NTL</a> by Victor Shoup has fixed and
298 arbitrary high precision fixed and floating-point types. However none of these
299 are licenced for commercial use.
301 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">NTL</span><span class="special">/</span><span class="identifier">quad_float</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span> <span class="comment">// quad precision 106-bit, about 32 decimal digits.</span>
302 <span class="keyword">using</span> <span class="identifier">NTL</span><span class="special">::</span><span class="identifier">to_quad_float</span><span class="special">;</span> <span class="comment">// Less precise than arbitrary precision NTL::RR.</span>
305 NTL class <code class="computeroutput"><span class="identifier">quad_float</span></code>, which
306 gives a form of quadruple precision, 106-bit significand (but without an extended
307 exponent range.) With an IEC559/IEEE 754 compatible processor, for example
308 Intel X86 family, with 64-bit double, and 53-bit significand, using the significands
309 of <span class="bold"><strong>two</strong></span> 64-bit doubles, if <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="keyword">double</span><span class="special">>::</span><span class="identifier">digits10</span></code> is 16, then we get about twice the
310 precision, so <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">quad_float</span><span class="special">>::</span><span class="identifier">digits10</span><span class="special">()</span></code>
311 should be 32. (the default <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">RR</span><span class="special">>::</span><span class="identifier">digits10</span><span class="special">()</span></code>
312 should be about 40). (which seems to agree with experiments). We output constants
313 (including some noisy bits, an approximation to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">RR</span><span class="special">>::</span><span class="identifier">max_digits10</span><span class="special">()</span></code>)
314 by adding 2 or 3 extra decimal digits, so using <code class="computeroutput"><span class="identifier">quad_float</span><span class="special">::</span><span class="identifier">SetOutputPrecision</span><span class="special">(</span><span class="number">32</span> <span class="special">+</span>
315 <span class="number">3</span><span class="special">);</span></code>
318 Apple Mac/Darwin uses a similar <span class="emphasis"><em>doubledouble</em></span> 106-bit for
319 its built-in <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>
322 <div class="note"><table border="0" summary="Note">
324 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
325 <th align="left">Note</th>
327 <tr><td align="left" valign="top"><p>
328 The precision of all <code class="computeroutput"><span class="identifier">doubledouble</span></code>
329 floating-point types is rather odd and values given are only approximate.
333 <span class="bold"><strong>New projects should use <a href="../../../../../libs/multiprecision/doc/html/index.html" target="_top">Boost.Multiprecision</a>.</strong></span>
336 <a name="math_toolkit.constants_faq.h11"></a>
337 <span class="phrase"><a name="math_toolkit.constants_faq.ntl_class_rr"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.ntl_class_rr">NTL
341 Arbitrary precision floating point with NTL class RR, default is 150 bit (about
342 50 decimal digits) used here with 300 bit to output 100 decimal digits, enough
343 for many practical non-'number-theoretic' C++ applications.
346 <a href="http://www.shoup.net/ntl/" target="_top">NTL A Library for doing Number Theory</a>
347 is <span class="bold"><strong>not licenced for commercial use</strong></span>.
350 This class is used in Boost.Math and is an option when using big_number projects
351 to calculate new math constants.
354 <span class="bold"><strong>New projects should use <a href="../../../../../libs/multiprecision/doc/html/index.html" target="_top">Boost.Multiprecision</a>.</strong></span>
357 <a name="math_toolkit.constants_faq.h12"></a>
358 <span class="phrase"><a name="math_toolkit.constants_faq.gmp_and_mpfr"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.gmp_and_mpfr">GMP
362 <a href="http://gmplib.org" target="_top">GMP</a> and <a href="http://www.mpfr.org/" target="_top">MPFR</a>
363 have also been used to compute constants, but are licensed under the <a href="http://www.gnu.org/copyleft/lesser.html" target="_top">Lesser GPL license</a> and
364 are <span class="bold"><strong>not licensed for commercial use</strong></span>.
367 <a name="math_toolkit.constants_faq.h13"></a>
368 <span class="phrase"><a name="math_toolkit.constants_faq.what_happened_to_a_previous_coll"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.what_happened_to_a_previous_coll">What
369 happened to a previous collection of constants proposed for Boost?</a>
372 A review concluded that the way in which the constants were presented did not
373 meet many peoples needs. None of the methods proposed met many users' essential
374 requirement to allow writing simply <code class="computeroutput"><span class="identifier">pi</span></code>
375 rather than <code class="computeroutput"><span class="identifier">pi</span><span class="special">()</span></code>.
376 Many science and engineering equations look difficult to read when because
377 function call brackets can be confused with the many other brackets often needed.
378 All the methods then proposed of avoiding the brackets failed to meet all needs,
379 often on grounds of complexity and lack of applicability to various realistic
383 So the simple namespace method, proposed on its own, but rejected at the first
384 review, has been added to allow users to have convenient access to float, double
385 and long double values, but combined with template struct and functions to
386 allow simultaneous use with other non-built-in floating-point types.
389 <a name="math_toolkit.constants_faq.h14"></a>
390 <span class="phrase"><a name="math_toolkit.constants_faq.why_do_the_constants_internally_"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.why_do_the_constants_internally_">Why do
391 the constants (internally) have a struct rather than a simple function?</a>
394 A function mechanism was provided by in previous versions of Boost.Math.
397 The new mechanism is to permit partial specialization. See Custom Specializing
398 a constant above. It should also allow use with other packages like <a href="http://www.ttmath.org/" target="_top">ttmath Bignum C++ library.</a>
401 <a name="math_toolkit.constants_faq.h15"></a>
402 <span class="phrase"><a name="math_toolkit.constants_faq.where_can_i_find_other_high_prec"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.where_can_i_find_other_high_prec">Where
403 can I find other high precision constants?</a>
405 <div class="orderedlist"><ol class="orderedlist" type="1">
406 <li class="listitem">
407 Constants with very high precision and good accuracy (>40 decimal digits)
408 from Simon Plouffe's web based collection <a href="http://pi.lacim.uqam.ca/eng/" target="_top">http://pi.lacim.uqam.ca/eng/</a>.
410 <li class="listitem">
411 <a href="https://oeis.org/" target="_top">The On-Line Encyclopedia of Integer Sequences
414 <li class="listitem">
415 Checks using printed text optically scanned values and converted from:
416 D. E. Knuth, Art of Computer Programming, Appendix A, Table 1, Vol 1, ISBN
419 <li class="listitem">
420 M. Abrahamovitz & I. E. Stegun, National Bureau of Standards, Handbook
421 of Mathematical Functions, a reference source for formulae now superceded
424 <li class="listitem">
425 Frank W. Olver, Daniel W. Lozier, Ronald F. Boisvert, Charles W. Clark,
426 NIST Handbook of Mathemetical Functions, Cambridge University Press, ISBN
427 978-0-521-14063-8, 2010.
429 <li class="listitem">
430 John F Hart, Computer Approximations, Kreiger (1978) ISBN 0 88275 642 7.
432 <li class="listitem">
433 Some values from Cephes Mathematical Library, Stephen L. Moshier and CALC100
434 100 decimal digit Complex Variable Calculator Program, a DOS utility.
436 <li class="listitem">
437 Xavier Gourdon, Pascal Sebah, 50 decimal digits constants at <a href="http://numbers.computation.free.fr/Constants/constants.html" target="_top">Number,
438 constants and computation</a>.
442 <a name="math_toolkit.constants_faq.h16"></a>
443 <span class="phrase"><a name="math_toolkit.constants_faq.where_are_physical_constants"></a></span><a class="link" href="constants_faq.html#math_toolkit.constants_faq.where_are_physical_constants">Where are
444 Physical Constants?</a>
447 Not here in this Boost.Math collection, because physical constants:
449 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
450 <li class="listitem">
451 Are measurements, not truely constants.
453 <li class="listitem">
454 Are not truly constant and keeping changing as mensuration technology improves.
456 <li class="listitem">
457 Have a instrinsic uncertainty.
459 <li class="listitem">
460 Mathematical constants are stored and represented at varying precision,
461 but should never be inaccurate.
465 Some physical constants may be available in Boost.Units.
468 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
469 <td align="left"></td>
470 <td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar
471 Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
472 Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
473 Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
474 Daryle Walker and Xiaogang Zhang<p>
475 Distributed under the Boost Software License, Version 1.0. (See accompanying
476 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
481 <div class="spirit-nav">
482 <a accesskey="p" href="new_const.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../constants.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../dist.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>