| |
| |
| [mathpart constants..Mathematical Constants] |
| |
| [section:constants_intro Introduction] |
| |
| Boost.Math provides a collection of mathematical constants. |
| |
| [h4 Why use Boost.Math mathematical constants?] |
| |
| * Readable. For the very many jobs just using built-in like `double`, you can just write expressions like |
| ``double area = pi * r * r;`` |
| (If that's all you want, jump direct to [link math_toolkit.tutorial.non_templ use in non-template code]!) |
| * Effortless - avoiding a search of reference sources. |
| * Usable with both builtin floating point types, and user-defined, possibly extended precision, types such as |
| NTL, MPFR/GMP, mp_float: in the latter case the constants are computed to the necessary precision and then cached. |
| * Accurate - ensuring that the values are as accurate as possible for the |
| chosen floating-point type |
| * No loss of accuracy from repeated rounding of intermediate computations. |
| * Result is computed with higher precision and only rounded once. |
| * Less risk of inaccurate result from functions pow, trig and log at [@http://en.wikipedia.org/wiki/Corner_case corner cases]. |
| * Less risk of [@http://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html cancellation error]. |
| * Portable - as possible between different systems using different floating-point precisions: |
| see [link math_toolkit.tutorial.templ use in template code]. |
| * Tested - by comparison with other published sources, or separately computed at long double precision. |
| * Faster - can avoid (re-)calculation at runtime. |
| * If the value returned is a builtin type then it's returned by value as a `constexpr` (C++11 feature, if available). |
| * If the value is computed and cached (or constructed from a string representation and cached), then it's returned by constant reference.[br] |
| This can be significant if: |
| * Functions pow, trig or log are used. |
| * Inside an inner loop. |
| * Using a high-precision UDT like __multiprecision. |
| * Compiler optimizations possible with built-in types, especially `double`, are not available. |
| |
| [endsect] [/section:intro Introduction] |
| |
| [section:tutorial Tutorial] |
| |
| [section:non_templ Use in non-template code] |
| |
| When using the math constants at your chosen fixed precision in non-template code, |
| you can simply add a `using namespace` declaration, for example, |
| `using namespace boost::math::double_constants`, |
| to make the constants of the correct precision for your code |
| visible in the current scope, and then use each constant ['as a simple variable - sans brackets]: |
| |
| #include <boost/math/constants/constants.hpp> |
| |
| double area(double r) |
| { |
| using namespace boost::math::double_constants; |
| return pi * r * r; |
| } |
| |
| Had our function been written as taking a `float` rather than a `double`, |
| we could have written instead: |
| |
| #include <boost/math/constants/constants.hpp> |
| |
| float area(float r) |
| { |
| using namespace boost::math::float_constants; |
| return pi * r * r; |
| } |
| |
| Likewise, constants that are suitable for use at `long double` precision |
| are available in the namespace `boost::math::long_double_constants`. |
| |
| You can see the full list of available constants at [link math_toolkit.constants]. |
| |
| Some examples of using constants are at [@../../example/constants_eg1.cpp constants_eg1]. |
| |
| [endsect] [/section:non_templ Use in non-template code] |
| |
| [section:templ Use in template code] |
| |
| When using the constants inside a function template, we need to ensure that |
| we use a constant of the correct precision for our template parameters. |
| We can do this by calling the function-template versions, `pi<FPType>()`, of the constants |
| like this: |
| |
| #include <boost/math/constants/constants.hpp> |
| |
| template <class Real> |
| Real area(Real r) |
| { |
| using namespace boost::math::constants; |
| return pi<Real>() * r * r; |
| } |
| |
| Although this syntax is a little less "cute" than the non-template version, |
| the code is no less efficient |
| (at least for the built-in types `float`, `double` and `long double`) : |
| the function template versions of the constants are simple inline functions that |
| return a constant of the correct precision for the type used. In addition, these |
| functions are declared `constexp` for those compilers that support this, allowing |
| the result to be used in constant-expressions provided the template argument is a literal type. |
| |
| [tip Keep in mind the difference between the variable version, |
| just `pi`, and the template-function version: |
| the template-function requires both a <[~floating-point-type]> |
| and function call `()` brackets, for example: `pi<double>()`. |
| You cannot write `double p = pi<>()`, nor `double p = pi()`.] |
| |
| [note You can always use [*both] variable and template-function versions |
| [*provided calls are fully qualified], for example: |
| `` |
| double my_pi1 = boost::math::constants::pi<double>(); |
| double my_pi2 = boost::math::double_constants::pi; |
| `` |
| ] |
| |
| [warning It may be tempting to simply define |
| `` |
| using namespace boost::math::double_constants; |
| using namespace boost::math::constants; |
| `` |
| but if you do define two namespaces, this will, of course, create ambiguity! |
| `` |
| double my_pi = pi(); // error C2872: 'pi' : ambiguous symbol |
| double my_pi2 = pi; // Context does not allow for disambiguation of overloaded function |
| `` |
| Although the mistake above is fairly obvious, |
| it is also not too difficult to do this accidentally, or worse, create it in someone elses code. |
| |
| Therefore is it prudent to avoid this risk by [*localising the scope of such definitions], as shown above.] |
| |
| [tip Be very careful with the type provided as parameter. |
| For example, providing an [*integer] instead of a floating-point type can be disastrous (a C++ feature). |
| |
| ``cout << "Area = " << area(2) << endl; // Area = 12!!!`` |
| |
| You should get a compiler warning |
| [pre |
| warning : 'return' : conversion from 'double' to 'int', possible loss of data |
| ] [/pre] |
| Failure to heed this warning can lead to very wrong answers! |
| |
| You can also avoid this by being explicit about the type of `Area`. |
| ``cout << "Area = " << area<double>(2) << endl; // Area = 12.566371`` |
| ] |
| |
| [endsect] [/section:templ Use in template code] |
| |
| [section:user_def Use With User-Defined Types] |
| |
| The most common example of a high-precision user-defined type will probably be __multiprecision. |
| |
| The syntax for using the function-call constants with user-defined types is the same |
| as it is in the template class, which is to say we use: |
| |
| #include <boost/math/constants/constants.hpp> |
| |
| boost::math::constants::pi<UserDefinedType>(); |
| |
| For example: |
| |
| boost::math::constants::pi<boost::multiprecision::cpp_dec_float_50>(); |
| |
| giving [pi] with a precision of 50 decimal digits. |
| |
| However, since the precision of the user-defined type may be much greater than that |
| of the built-in floating point types, how the value returned is created is as follows: |
| |
| * If the precision of the type is known at compile time: |
| * If the precision is less than or equal to that of a `float` and the type is constructable from a `float` |
| then our code returns a `float` literal. If the user-defined type is a literal type |
| then the function call that returns the constant will be a `constexp`. |
| * If the precision is less than or equal to that of a `double` and the type is constructable from a `double` |
| then our code returns a `double` literal. If the user-defined type is a literal type |
| then the function call that returns the constant will be a `constexp`. |
| * If the precision is less than or equal to that of a `long double` and the type is constructable from a `long double` |
| then our code returns a `long double` literal. If the user-defined type is a literal type |
| then the function call that returns the constant will be a `constexp`. |
| * If the precision is less than or equal to that of a `__float128` (and the compiler supports such a type) |
| and the type is constructable from a `__float128` |
| then our code returns a `__float128` literal. If the user-defined type is a literal type |
| then the function call that returns the constant will be a `constexp`. |
| * If the precision is less than 100 decimal digits, then the constant will be constructed |
| (just the once, then cached in a thread-safe manner) from a string representation of the constant. |
| In this case the value is returned as a const reference to the cached value. |
| * Otherwise the value is computed (just once, then cached in a thread-safe manner). |
| In this case the value is returned as a const reference to the cached value. |
| * If the precision is unknown at compile time then: |
| * If the runtime precision (obtained from a call to `boost::math::tools::digits<T>()`) is |
| less than 100 decimal digits, then the constant is constructed "on the fly" from the string |
| representation of the constant. |
| * Otherwise the value is constructed "on the fly" by calculating then value of the constant |
| using the current default precision of the type. Note that this can make use of the constants |
| rather expensive. |
| |
| In addition, it is possible to pass a `Policy` type as a second template argument, and use this to control |
| the precision: |
| |
| #include <boost/math/constants/constants.hpp> |
| |
| typedef boost::math::policies::policy<boost::math::policies::digits2<80> > my_policy_type; |
| boost::math::constants::pi<MyType, my_policy_type>(); |
| |
| [note Boost.Math doesn't know how to control the internal precision of `MyType`, the policy |
| just controls how the selection process above is carried out, and the calculation precision |
| if the result is computed.] |
| |
| It is also possible to control which method is used to construct the constant by specialising |
| the traits class `construction_traits`: |
| |
| namespace boost{ namespace math{ namespace constant{ |
| |
| template <class T, class Policy> |
| struct construction_traits |
| { |
| typedef mpl::int_<N> type; |
| }; |
| |
| }}} // namespaces |
| |
| Where ['N] takes one of the following values: |
| |
| [table |
| [[['N]][Meaning]] |
| [[0][The precision is unavailable at compile time; |
| either construct from a decimal digit string or calculate on the fly depending upon the runtime precision.]] |
| [[1][Return a float precision constant.]] |
| [[2][Return a double precision constant.]] |
| [[3][Return a long double precision constant.]] |
| [[4][Construct the result from the string representation, and cache the result.]] |
| [[Any other value ['N]][Sets the compile time precision to ['N] bits.]] |
| ] |
| |
| [h5 Custom Specializing a constant] |
| |
| In addition, for user-defined types that need special handling, it's possible to partially-specialize |
| the internal structure used by each constant. For example, suppose we're using the C++ wrapper around MPFR |
| `mpfr_class`: this has its own representation of Pi which we may well wish to use in place of the above |
| mechanism. We can achieve this by specialising the class template `boost::math::constants::detail::constant_pi`: |
| |
| namespace boost{ namespace math{ namespace constants{ namespace detail{ |
| |
| template<> |
| struct constant_pi<mpfr_class> |
| { |
| template<int N> |
| static mpfr_class get(const mpl::int_<N>&) |
| { |
| // The template param N is one of the values in the table above, |
| // we can either handle all cases in one as is the case here, |
| // or overload "get" for the different options. |
| mpfr_class result; |
| mpfr_const_pi(result.get_mpfr_t(), GMP_RNDN); |
| return result; |
| } |
| }; |
| |
| }}}} // namespaces |
| |
| [h5 Diagnosing what meta-programmed code is doing] |
| |
| Finally, since it can be tricky to diagnose what meta-programmed code is doing, there is a |
| diagnostic routine that prints information about how this library will handle a specific type, |
| it can be used like this: |
| |
| #include <boost/math/constants/info.hpp> |
| |
| int main() |
| { |
| boost::math::constants::print_info_on_type<MyType>(); |
| } |
| |
| If you wish, you can also pass an optional std::ostream argument to the `print_info_on_type` function. |
| Typical output for a user-defined type looks like this: |
| |
| [pre |
| Information on the Implementation and Handling of |
| Mathematical Constants for Type class boost::math::concepts::real_concept |
| |
| Checking for std::numeric_limits<class boost::math::concepts::real_concept> specialisation: no |
| boost::math::policies::precision<class boost::math::concepts::real_concept, Policy> |
| reports that there is no compile type precision available. |
| boost::math::tools::digits<class boost::math::concepts::real_concept>() |
| reports that the current runtime precision is |
| 53 binary digits. |
| No compile time precision is available, the construction method |
| will be decided at runtime and results will not be cached |
| - this may lead to poor runtime performance. |
| Current runtime precision indicates that |
| the constant will be constructed from a string on each call. |
| ] |
| |
| [endsect] [/section:user_def Use With User Defined Types] |
| |
| [endsect] [/section:tutorial Tutorial] |
| |
| [section:constants The Mathematical Constants] |
| |
| This section lists the mathematical constants, their use(s) (and sometimes rationale for their inclusion). |
| [table Mathematical Constants |
| [[name] [formula] [Value (6 decimals)] [Uses and Rationale]] |
| [[[*Rational fractions]] [] [] [] ] |
| [[half] [1/2] [0.5] [] ] |
| [[third] [1/3] [0.333333] [] ] |
| [[two_thirds] [2/3] [0.66667] [] ] |
| [[three_quarters] [3/4] [0.75] [] ] |
| |
| [[[*two and related]] [] [] [] ] |
| [[root_two] [[radic]2] [1.41421] [] ] |
| [[root_three] [[radic]3] [1.73205] [] ] |
| [[half_root_two] [[radic]2 /2] [0.707106] [] ] |
| [[ln_two] [ln(2)] [0.693147] [] ] |
| [[ln_ten] [ln(10)] [2.30258] [] ] |
| [[ln_ln_two] [ln(ln(2))] [-0.366512] [Gumbel distribution median] ] |
| [[root_ln_four] [[radic]ln(4)] [1.177410] [] ] |
| [[one_div_root_two] [1/[radic]2] [0.707106] [] ] |
| |
| [[[*[pi] and related]] [] [] [] ] |
| [[pi] [pi] [3.14159] [Ubiquitous. Archimedes constant [@http://en.wikipedia.org/wiki/Pi [pi]]]] |
| [[half_pi] [[pi]/2] [1.570796] [] ] |
| [[third_pi] [[pi]/3] [1.04719] [] ] |
| [[sixth_pi] [[pi]/6] [0.523598] [] ] |
| [[two_pi] [2[pi]] [6.28318] [Many uses, most simply, circumference of a circle]] |
| [[two_thirds_pi] [2/3 [pi]] [2.09439] [[@http://en.wikipedia.org/wiki/Sphere#Volume_of_a_sphere volume of a hemi-sphere] = 4/3 [pi] r[cubed]]] |
| [[three_quarters_pi] [3/4 [pi]] [2.35619] [ = 3/4 [pi] ]] |
| [[four_thirds_pi] [4/3 [pi]] [4.18879] [[@http://en.wikipedia.org/wiki/Sphere#Volume_of_a_sphere volume of a sphere] = 4/3 [pi] r[cubed]]] |
| [[one_div_two_pi] [1/(2[pi])] [1.59155] [Widely used]] |
| [[root_pi] [[radic][pi]][1.77245] [Widely used]] |
| [[root_half_pi] [[radic] [pi]/2] [1.25331] [Widely used]] |
| [[root_two_pi][[radic] [pi]*2] [2.50662] [Widely used]] |
| [[one_div_root_pi] [1/[radic][pi]] [0.564189] [] ] |
| [[one_div_root_two_pi] [1/[radic](2[pi])] [0.398942] [] ] |
| [[root_one_div_pi] [[radic](1/[pi]] [0.564189] [] ] |
| [[pi_minus_three] [[pi]-3] [0.141593] [] ] |
| [[four_minus_pi] [4 -[pi]] [0.858407] [] ] |
| [[pi_pow_e] [[pi][super e]] [22.4591] [] ] |
| |
| [[pi_sqr] [[pi][super 2]] [9.86960] [] ] |
| [[pi_sqr_div_six] [[pi][super 2]/6] [1.64493] [] ] |
| [[pi_cubed] [[pi][super 3]] [31.00627] [] ] |
| [[cbrt_pi] [[radic][super 3] [pi]] [1.46459] [] ] |
| [[one_div_cbrt_pi] [1/[radic][super 3] [pi]] [0.682784] [] ] |
| |
| [[[*Euler's e and related]] [] [] [] ] |
| [[e] [e] [2.71828] [[@http://en.wikipedia.org/wiki/E_(mathematical_constant) Euler's constant e]] ] |
| [[exp_minus_half] [e [super -1/2]] [0.606530] [] ] |
| [[e_pow_pi] [e [super [pi]]] [23.14069] [] ] |
| [[root_e] [[radic] e] [1.64872] [] ] |
| [[log10_e] [log10(e)] [0.434294] [] ] |
| [[one_div_log10_e] [1/log10(e)] [2.30258] [] ] |
| |
| [[[*Trigonometric]] [] [] [] ] |
| [[degree] [radians = [pi] / 180] [0.017453] [] ] |
| [[radian] [degrees = 180 / [pi]] [57.2957] [] ] |
| [[sin_one] [sin(1)] [0.841470] [] ] |
| [[cos_one] [cos(1)] [0.54030] [] ] |
| [[sinh_one] [sinh(1)] [1.17520] [] ] |
| [[cosh_one] [cosh(1)] [1.54308] [] ] |
| |
| [[[*Phi]] [ Phidias golden ratio] [[@http://en.wikipedia.org/wiki/Golden_ratio Phidias golden ratio]] [] ] |
| [[phi] [(1 + [radic]5) /2] [1.61803] [finance] ] |
| [[ln_phi] [ln([phi])] [0.48121] [] ] |
| [[one_div_ln_phi] [1/ln([phi])] [2.07808] [] ] |
| |
| [[[*Euler's Gamma]] [] [] [] ] |
| [[euler] [euler] [0.577215] [[@http://en.wikipedia.org/wiki/Euler%E2%80%93Mascheroni_constant Euler-Mascheroni gamma constant]] ] |
| [[one_div_euler] [1/euler] [1.73245] [] ] |
| [[euler_sqr] [euler[super 2]] [0.333177] [] ] |
| |
| [[[*Misc]] [] [] [] ] |
| [[zeta_two] [[zeta](2)] [1.64493] [[@http://en.wikipedia.org/wiki/Riemann_zeta_function Riemann zeta function]] ] |
| [[zeta_three] [[zeta](3)] [1.20205] [[@http://en.wikipedia.org/wiki/Riemann_zeta_function Riemann zeta function]] ] |
| [[catalan] [['K]] [0.915965] [[@http://mathworld.wolfram.com/CatalansConstant.html Catalan (or Glaisher) combinatorial constant] ]] |
| [[glaisher] [['A]] [1.28242] [[@https://oeis.org/A074962/constant Decimal expansion of Glaisher-Kinkelin constant] ]] |
| [[khinchin] [['k]] [2.685452] [[@https://oeis.org/A002210/constant Decimal expansion of Khinchin constant] ]] |
| |
| [[extreme_value_skewness] [12[radic]6 [zeta](3)/ [pi][super 3]] [1.139547] [Extreme value distribution] ] |
| [[rayleigh_skewness] [2[radic][pi]([pi]-3)/(4 - [pi])[super 3/2]] [0.631110] [Rayleigh distribution skewness] ] |
| [[rayleigh_kurtosis_excess] [-(6[pi][super 2]-24[pi]+16)/(4-[pi])[super 2]] [0.245089] [[@http://en.wikipedia.org/wiki/Rayleigh_distribution Rayleigh distribution kurtosis excess]] ] |
| [[rayleigh_kurtosis] [3+(6[pi][super 2]-24[pi]+16)/(4-[pi])[super 2]] [3.245089] [Rayleigh distribution kurtosis] ] |
| |
| ] [/table] |
| |
| |
| [note Integer values are [*not included] in this list of math constants, however interesting, |
| because they can be so easily and exactly constructed, even for UDT, for example: `static_cast<cpp_float>(42)`.] |
| |
| [tip If you know the approximate value of the constant, you can search for the value to find Boost.Math chosen name in this table.] |
| [tip Bernoulli numbers are available at __bernoulli_numbers.] |
| [tip Factorials are available at __factorial.] |
| |
| [endsect] [/section:constants The constants] |
| |
| [section:new_const Defining New Constants] |
| |
| The library provides some helper code to assist in defining new constants; |
| the process for defining a constant called `my_constant` goes like this: |
| |
| 1. [*Define a function that calculates the value of the constant]. |
| This should be a template function, and be placed in `boost/math/constants/calculate_constants.hpp` |
| if the constant is to be added to this library, |
| or else defined at the top of your source file if not. |
| |
| The function should look like this: |
| |
| namespace boost{ namespace math{ namespace constants{ namespace detail{ |
| |
| template <class Real> |
| template <int N> |
| Real constant_my_constant<Real>::compute(BOOST_MATH_EXPLICIT_TEMPLATE_TYPE_SPEC(mpl::int_<N>)) |
| { |
| int required_precision = N ? N : tools::digits<Real>(); |
| Real result = /* value computed to required_precision bits */ ; |
| return result; |
| } |
| |
| }}}} // namespaces |
| |
| Then define a placeholder for the constant itself: |
| |
| namespace boost{ namespace math{ namespace constants{ |
| |
| BOOST_DEFINE_MATH_CONSTANT(my_constant, 0.0, "0"); |
| |
| }}} |
| |
| |
| For example, to calculate [pi]/2, add to `boost/math/constants/calculate_constants.hpp` |
| |
| template <class T> |
| template<int N> |
| inline T constant_half_pi<T>::compute(BOOST_MATH_EXPLICIT_TEMPLATE_TYPE_SPEC(mpl::int_<N>)) |
| { |
| BOOST_MATH_STD_USING |
| return pi<T, policies::policy<policies::digits2<N> > >() / static_cast<T>(2); |
| } |
| |
| Then to `boost/math/constants/constants.hpp` add: |
| |
| BOOST_DEFINE_MATH_CONSTANT(half_pi, 0.0, "0"); // Actual values are temporary, we'll replace them later. |
| |
| [note Previously defined constants like pi and e can be used, but by *not simply calling* `pi<T>()`; |
| specifying the precision via the policy |
| `pi<T, policies::policy<policies::digits2<N> > >()` |
| is essential to ensure full accuracy.] |
| |
| [warning Newly defined constants can only be used once they are included in |
| `boost/math/constants/constants.hpp`. So if you add |
| `template <class T, class N> T constant_my_constant{...}`, |
| then you cannot define `constant_my_constant` |
| until you add the temporary `BOOST_DEFINE_MATH_CONSTANT(my_constant, 0.0, "0")`. |
| Failing to do this will result in surprising compile errors: |
| `` |
| error C2143: syntax error : missing ';' before '<' |
| error C2433: 'constant_root_two_div_pi' : 'inline' not permitted on data declarations |
| error C2888: 'T constant_root_two_div_pi' : symbol cannot be defined within namespace 'detail' |
| error C2988: unrecognizable template declaration/definition |
| `` |
| ] |
| |
| 2. [*You will need an arbitrary precision type to use to calculate the value]. This library |
| currently supports either `cpp_float`, `NTL::RR` or `mpfr_class` used via the bindings in `boost/math/bindings`. |
| The default is to use `NTL::RR` unless you define an alternate macro, for example, |
| `USE_MPFR` or `USE_CPP_FLOAT` at the start of your program. |
| |
| 3. It is necessary to link to the Boost.Regex library, |
| and probably to your chosen arbitrary precision type library. |
| |
| 4. You need to add `libs\math\include_private` to your compiler's include path as the needed |
| header is not installed in the usual places by default (this avoids a cyclic dependency between |
| the Math and Multiprecision library's headers). |
| |
| 5. The complete program to generate the constant `half_pi` using function `calculate_half_pi` is then: |
| |
| #define USE_CPP_FLOAT // If required. |
| #include <boost/math/constants/generate.hpp> |
| |
| int main() |
| { |
| BOOST_CONSTANTS_GENERATE(half_pi); |
| } |
| |
| The output from the program is a snippet of C++ code |
| (actually a macro call) that can be cut and pasted |
| into `boost/math/constants/constants.hpp` or else into your own code, for example: |
| |
| [pre |
| BOOST_DEFINE_MATH_CONSTANT(half_pi, 1.570796326794896619231321691639751442e+00, "1.57079632679489661923132169163975144209858469968755291048747229615390820314310449931401741267105853399107404326e+00"); |
| ] |
| |
| This macro BOOST_DEFINE_MATH_CONSTANT inserts a C++ struct code snippet that |
| declares the `float`, `double` and `long double` versions of the constant, |
| plus a decimal digit string representation correct to 100 decimal |
| digits, and all the meta-programming machinery needed to select between them. |
| |
| The result of an expanded macro for Pi is shown below. |
| |
| [import ./pp_pi.hpp] |
| |
| [preprocessed_pi] |
| |
| |
| [endsect] [/section:new_const Defining New Constants] |
| |
| [section:constants_faq FAQs] |
| |
| [h4 Why are ['these] Constants Chosen?] |
| It is, of course, impossible to please everyone with a list like this. |
| |
| Some of the criteria we have used are: |
| |
| * Used in Boost.Math. |
| * Commonly used. |
| * Expensive to compute. |
| * Requested by users. |
| * [@http://en.wikipedia.org/wiki/Mathematical_constant Used in science and mathematics.] |
| * No integer values (because so cheap to construct).[br] |
| (You can easily define your own if found convenient, for example: `FPT one =static_cast<FPT>(42);`). |
| |
| [h4 How are constants named?] |
| * Not macros, so no upper case. |
| * All lower case (following C++ standard names). |
| * No CamelCase. |
| * Underscore as _ delimiter between words. |
| * Numbers spelt as words rather than decimal digits (except following pow). |
| * Abbreviation conventions: |
| * root for square root. |
| * cbrt for cube root. |
| * pow for pow function using decimal digits like pow23 for n[super 2/3]. |
| * div for divided by or operator /. |
| * minus for operator -, plus for operator +. |
| * sqr for squared. |
| * cubed for cubed n[super 3]. |
| * words for greek, like [pi], [zeta] and [Gamma]. |
| * words like half, third, three_quarters, sixth for fractions. (Digit(s) can get muddled). |
| * log10 for log[sub 10] |
| * ln for log[sub e] |
| |
| [h4 How are the constants derived?] |
| |
| The constants have all been calculated using high-precision software working |
| with up to 300-bit precision giving about 100 decimal digits. |
| (The precision can be arbitrarily chosen and is limited only by compute time). |
| |
| [h4 How Accurate are the constants?] |
| The minimum accuracy chosen (100 decimal digits) exceeds the |
| accuracy of reasonably-foreseeable floating-point hardware (256-bit) |
| and should meet most high-precision computations. |
| |
| [h4 How are the constants tested?] |
| |
| # Comparison using Boost.Test BOOST_CHECK_CLOSE_FRACTION using long double literals, |
| with at least 35 decimal digits, enough to be accurate for all long double implementations. |
| The tolerance is usually twice `long double epsilon`. |
| |
| # Comparison with calculation at long double precision. |
| This often requires a slightly higher tolerance than two epsilon |
| because of computational noise from round-off etc, |
| especially when trig and other functions are called. |
| |
| # Comparison with independent published values, |
| for example, using [@http://oeis.org/ The On-Line Encyclopedia of Integer Sequences (OEIS)] |
| again using at least 35 decimal digits strings. |
| |
| # Comparison with independely calculated values using arbitrary precision tools like |
| [@http://www.wolfram.com/mathematica/ Mathematica], again using at least 35 decimal digits literal strings. |
| |
| [warning We have not yet been able to [*check] that |
| [*all] constants are accurate at the full arbitrary precision, |
| at present 100 decimal digits. |
| But certain key values like `e` and `pi` appear to be accurate |
| and internal consistencies suggest that others are this accurate too. |
| ] |
| |
| [h4 Why is Portability important?] |
| |
| Code written using math constants is easily portable even when using different |
| floating-point types with differing precision. |
| |
| It is a mistake to expect that results of computations will be [*identical], but |
| you can achieve the [*best accuracy possible for the floating-point type in use]. |
| |
| This has no extra cost to the user, but reduces irritating, |
| and often confusing and very hard-to-trace effects, |
| caused by the intrinsically limited precision of floating-point calculations. |
| |
| A harmless symptom of this limit is a spurious least-significant digit; |
| at worst, slightly inaccurate constants sometimes cause iterating algorithms |
| to diverge wildly because internal comparisons just fail. |
| |
| [h4 What is the Internal Format of the constants, and why?] |
| |
| See [link math_toolkit.tutorial tutorial] above for normal use, |
| but this FAQ explains the internal details used for the constants. |
| |
| Constants are stored as 100 decimal digit values. |
| However, some compilers do not accept decimal digits strings as long as this. |
| So the constant is split into two parts, with the first containing at least |
| 128-bit long double precision (35 decimal digits), |
| and for consistency should be in scientific format with a signed exponent. |
| |
| The second part is the value of the constant expressed as a string literal, |
| accurate to at least 100 decimal digits (in practice that means at least 102 digits). |
| Again for consistency use scientific format with a signed exponent. |
| |
| For types with precision greater than a long double, |
| then if T is constructible `T `is constructible from a `const char*` |
| then it's directly constructed from the string, |
| otherwise we fall back on lexical_cast to convert to type `T`. |
| (Using a string is necessary because you can't use a numeric constant |
| since even a `long double` might not have enough digits). |
| |
| So, for example, a constant like pi is internally defined as |
| |
| BOOST_DEFINE_MATH_CONSTANT(pi, 3.141592653589793238462643383279502884e+00, "3.14159265358979323846264338327950288419716939937510582097494459230781640628620899862803482534211706798214808651e+00"); |
| |
| In this case the significand is 109 decimal digits, ensuring 100 decimal digits are exact, and exponent is zero. |
| |
| See [link math_toolkit.new_const defining new constants] to calculate new constants. |
| |
| A macro definition like this can be pasted into user code where convenient, |
| or into `boost/math/constants.hpp` if it is to be added to the Boost.Math library. |
| |
| [h4 What Floating-point Types could I use?] |
| |
| Apart from the built-in floating-point types `float`, `double`, `long double`, |
| there are several arbitrary precision floating-point classes available, |
| but most are not licensed for commercial use. |
| |
| [h5 Boost.Multiprecision by Christopher Kormanyos] |
| |
| This work is based on an earlier work called e-float: |
| Algorithm 910: A Portable C++ Multiple-Precision System for Special-Function Calculations, |
| in ACM TOMS, {VOL 37, ISSUE 4, (February 2011)} (C) ACM, 2011. |
| [@http://doi.acm.org/10.1145/1916461.1916469] |
| [@https://svn.boost.org/svn/boost/sandbox/e_float/ e_float] |
| but is now re-factored and available under the Boost license in the Boost-sandbox at |
| [@https://svn.boost.org/svn/boost/sandbox/multiprecision/ multiprecision] |
| where it is being refined and prepared for review. |
| |
| [h5 Boost.cpp_float by John Maddock using Expression Templates] |
| |
| [@https://svn.boost.org/svn/boost/sandbox/big_number/ Big Number] |
| which is a reworking of [@https://svn.boost.org/svn/boost/sandbox/e_float/ e_float] |
| by Christopher Kormanyos to use expression templates for faster execution. |
| |
| [h5 NTL class quad_float] |
| |
| [@http://shoup.net/ntl/ NTL] by Victor Shoup has fixed and arbitrary high precision fixed and floating-point types. |
| However none of these are licenced for commercial use. |
| |
| #include <NTL/quad_float.h> // quad precision 106-bit, about 32 decimal digits. |
| using NTL::to_quad_float; // Less precise than arbitrary precision NTL::RR. |
| |
| NTL class `quad_float`, which gives a form of quadruple precision, |
| 106-bit significand (but without an extended exponent range.) |
| With an IEC559/IEEE 754 compatible processor, |
| for example Intel X86 family, with 64-bit double, and 53-bit significand, |
| using the significands of [*two] 64-bit doubles, |
| if `std::numeric_limits<double>::digits10` is 16, |
| then we get about twice the precision, |
| so `std::numeric_limits<quad_float>::digits10()` should be 32. |
| (the default `std::numeric_limits<RR>::digits10()` should be about 40). |
| (which seems to agree with experiments). |
| We output constants (including some noisy bits, |
| an approximation to `std::numeric_limits<RR>::max_digits10()`) |
| by adding 2 extra decimal digits, so using `quad_float::SetOutputPrecision(32 + 2);` |
| |
| Apple Mac/Darwin uses a similar ['doubledouble] 106-bit for its built-in `long double` type. |
| |
| [note The precision of all `doubledouble` floating-point types is rather odd and values given are only approximate.] |
| |
| [*New projects should use __multiprecision.] |
| |
| [h5 NTL class RR] |
| |
| Arbitrary precision floating point with NTL class RR, |
| default is 150 bit (about 50 decimal digits) |
| used here with 300 bit to output 100 decimal digits, |
| enough for many practical non-'number-theoretic' C++ applications. |
| |
| __NTL is [*not licenced for commercial use]. |
| |
| This class is used in Boost.Math and is an option when using big_number projects to calculate new math constants. |
| |
| [*New projects should use __multiprecision.] |
| |
| [h5 GMP and MPFR] |
| |
| [@http://gmplib.org GMP] and [@http://www.mpfr.org/ MPFR] have also been used to compute constants, |
| but are licensed under the [@http://www.gnu.org/copyleft/lesser.html Lesser GPL license] |
| and are [*not licensed for commercial use]. |
| |
| [h4 What happened to a previous collection of constants proposed for Boost?] |
| |
| A review concluded that the way in which the constants were presented did not meet many peoples needs. |
| None of the methods proposed met many users' essential requirement to allow writing simply `pi` rather than `pi()`. |
| Many science and engineering equations look difficult to read when because function call brackets can be confused |
| with the many other brackets often needed. All the methods then proposed of avoiding the brackets failed to meet all needs, |
| often on grounds of complexity and lack of applicability to various realistic scenarios. |
| |
| So the simple namespace method, proposed on its own, but rejected at the first review, |
| has been added to allow users to have convenient access to float, double and long double values, |
| but combined with template struct and functions to allow simultaneous use |
| with other non-built-in floating-point types. |
| |
| |
| [h4 Why do the constants (internally) have a struct rather than a simple function?] |
| |
| A function mechanism was provided by in previous versions of Boost.Math. |
| |
| The new mechanism is to permit partial specialization. See Custom Specializing a constant above. |
| It should also allow use with other packages like [@http://www.ttmath.org/ ttmath Bignum C++ library.] |
| |
| [h4 Where can I find other high precision constants?] |
| |
| # Constants with very high precision and good accuracy (>40 decimal digits) |
| from Simon Plouffe's web based collection [@http://pi.lacim.uqam.ca/eng/]. |
| # [@https://oeis.org/ The On-Line Encyclopedia of Integer Sequences (OEIS)] |
| # Checks using printed text optically scanned values and converted from: |
| D. E. Knuth, Art of Computer Programming, Appendix A, Table 1, Vol 1, ISBN 0 201 89683 4 (1997) |
| # M. Abrahamovitz & I. E. Stegun, National Bureau of Standards, Handbook of Mathematical Functions, |
| a reference source for formulae now superceded by |
| # Frank W. Olver, Daniel W. Lozier, Ronald F. Boisvert, Charles W. Clark, NIST Handbook of Mathemetical Functions, Cambridge University Press, ISBN 978-0-521-14063-8, 2010. |
| # John F Hart, Computer Approximations, Kreiger (1978) ISBN 0 88275 642 7. |
| # Some values from Cephes Mathematical Library, Stephen L. Moshier |
| and CALC100 100 decimal digit Complex Variable Calculator Program, a DOS utility. |
| # Xavier Gourdon, Pascal Sebah, 50 decimal digits constants at [@http://numbers.computation.free.fr/Constants/constants.html Number, constants and computation]. |
| |
| [h4 Where are Physical Constants?] |
| |
| Not here in this Boost.Math collection, because physical constants: |
| |
| * Are measurements, not truely constants. |
| * Are not truly constant and keeping changing as mensuration technology improves. |
| * Have a instrinsic uncertainty. |
| * Mathematical constants are stored and represented at varying precision, but should never be inaccurate. |
| |
| Some physical constants may be available in Boost.Units. |
| |
| [endsect] [/section:FAQ FAQ] |
| |
| [endmathpart] [/section:constants Mathematical Constants] |
| |
| [/ |
| Copyright 2012 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). |
| ] |
| |
| |