| [section:use_ntl Using With NTL - a High-Precision Floating-Point Library] |
| |
| The special functions and tools in this library can be used with |
| [@http://shoup.net/ntl/doc/RR.txt NTL::RR (an arbitrary precision number type)], |
| via the bindings in [@../../../../../boost/math/bindings/rr.hpp boost/math/bindings/rr.hpp]. |
| [@http://shoup.net/ntl/ See also NTL: A Library for doing Number Theory by |
| Victor Shoup] |
| |
| Unfortunately `NTL::RR` doesn't quite satisfy our conceptual requirements, |
| so there is a very thin wrapper class `boost::math::ntl::RR` defined in |
| [@../../../../../boost/math/bindings/rr.hpp boost/math/bindings/rr.hpp] that you |
| should use in place of `NTL::RR`. The class is intended to be a drop-in |
| replacement for the "real" NTL::RR that adds some syntactic sugar to keep |
| this library happy, plus some of the standard library functions not implemented |
| in NTL. |
| |
| For those functions that are based upon the __lanczos, the bindings |
| defines a series of approximations with up to 61 terms and accuracy |
| up to approximately 3e-113. This therefore sets the upper limit for accuracy |
| to the majority of functions defined this library when used with `NTL::RR`. |
| |
| There is a concept checking test program for NTL support |
| [@../../../../../libs/math/test/ntl_concept_check.cpp here]. |
| |
| [endsect][/section:use_ntl Using With NTL - a High Precision Floating-Point Library] |
| |
| [section:use_mpfr Using With MPFR / GMP - a High-Precision Floating-Point Library] |
| |
| The special functions and tools in this library can be used with |
| [@http://www.mpfr.org MPFR (an arbitrary precision number type based on the GMP library)], |
| via the bindings in [@../../../../../boost/math/bindings/mpfr.hpp boost/math/bindings/mpfr.hpp]. |
| |
| In order to use these binings you will need to have installed [@http://www.mpfr.org MPFR] |
| plus it's dependency the [@http://gmplib.org GMP library] and the C++ wrapper for MPFR known as |
| [@http://math.berkeley.edu/~wilken/code/gmpfrxx/ gmpfrxx (or mpfr_class)]. |
| |
| Unfortunately `mpfr_class` doesn't quite satisfy our conceptual requirements, |
| so there is a very thin set of additional interfaces and some helper traits defined in |
| [@../../../../../boost/math/bindings/mpfr.hpp boost/math/bindings/mpfr.hpp] that you |
| should use in place of including 'gmpfrxx.h' directly. The existing mpfr_class is |
| then usable unchanged once this header is included, so it's performance-enhancing |
| expression templates are preserved and fully supported by this library: |
| |
| #include <boost/math/bindings/mpfr.hpp> |
| #include <boost/math/special_functions/gamma.hpp> |
| |
| int main() |
| { |
| mpfr_class::set_dprec(500); // 500 bit precision |
| // |
| // Note that the argument to tgamma is an expression template, |
| // that's just fine here: |
| // |
| mpfr_class v = boost::math::tgamma(sqrt(mpfr_class(2))); |
| std::cout << std::setprecision(50) << v << std::endl; |
| } |
| |
| |
| For those functions that are based upon the __lanczos, the bindings |
| defines a series of approximations with up to 61 terms and accuracy |
| up to approximately 3e-113. This therefore sets the upper limit for accuracy |
| to the majority of functions defined this library when used with `mpfr_class`. |
| |
| There is a concept checking test program for mpfr support |
| [@../../../../../libs/math/test/mpfr_concept_check.cpp here]. |
| |
| [endsect][/section:use_mpfr Using With MPFR / GMP - a High-Precision Floating-Point Library] |
| |
| [section:concepts Conceptual Requirements for Real Number Types] |
| |
| The functions, and statistical distributions in this library can be used with |
| any type /RealType/ that meets the conceptual requirements given below. All |
| the built in floating point types will meet these requirements. |
| User defined types that meet the requirements can also be used. For example, |
| with [link math_toolkit.using_udt.use_ntl a thin wrapper class] one of the types |
| provided with [@http://shoup.net/ntl/ NTL (RR)] can be used. Submissions |
| of binding to other extended precision types would also be most welcome! |
| |
| The guiding principal behind these requirements, is that a /RealType/ |
| behaves just like a built in floating point type. |
| |
| [h4 Basic Arithmetic Requirements] |
| |
| These requirements are common to all of the functions in this library. |
| |
| In the following table /r/ is an object of type `RealType`, /cr/ and |
| /cr2/ are objects |
| of type `const RealType`, and /ca/ is an object of type `const arithmetic-type` |
| (arithmetic types include all the built in integers and floating point types). |
| |
| [table |
| [[Expression][Result Type][Notes]] |
| [[`RealType(cr)`][RealType] |
| [RealType is copy constructible.]] |
| [[`RealType(ca)`][RealType] |
| [RealType is copy constructible from the arithmetic types.]] |
| [[`r = cr`][RealType&][Assignment operator.]] |
| [[`r = ca`][RealType&][Assignment operator from the arithmetic types.]] |
| [[`r += cr`][RealType&][Adds cr to r.]] |
| [[`r += ca`][RealType&][Adds ar to r.]] |
| [[`r -= cr`][RealType&][Subtracts cr from r.]] |
| [[`r -= ca`][RealType&][Subtracts ca from r.]] |
| [[`r *= cr`][RealType&][Multiplies r by cr.]] |
| [[`r *= ca`][RealType&][Multiplies r by ca.]] |
| [[`r /= cr`][RealType&][Divides r by cr.]] |
| [[`r /= ca`][RealType&][Divides r by ca.]] |
| [[`-r`][RealType][Unary Negation.]] |
| [[`+r`][RealType&][Identity Operation.]] |
| [[`cr + cr2`][RealType][Binary Addition]] |
| [[`cr + ca`][RealType][Binary Addition]] |
| [[`ca + cr`][RealType][Binary Addition]] |
| [[`cr - cr2`][RealType][Binary Subtraction]] |
| [[`cr - ca`][RealType][Binary Subtraction]] |
| [[`ca - cr`][RealType][Binary Subtraction]] |
| [[`cr * cr2`][RealType][Binary Multiplication]] |
| [[`cr * ca`][RealType][Binary Multiplication]] |
| [[`ca * cr`][RealType][Binary Multiplication]] |
| [[`cr / cr2`][RealType][Binary Subtraction]] |
| [[`cr / ca`][RealType][Binary Subtraction]] |
| [[`ca / cr`][RealType][Binary Subtraction]] |
| [[`cr == cr2`][bool][Equality Comparison]] |
| [[`cr == ca`][bool][Equality Comparison]] |
| [[`ca == cr`][bool][Equality Comparison]] |
| [[`cr != cr2`][bool][Inequality Comparison]] |
| [[`cr != ca`][bool][Inequality Comparison]] |
| [[`ca != cr`][bool][Inequality Comparison]] |
| [[`cr <= cr2`][bool][Less than equal to.]] |
| [[`cr <= ca`][bool][Less than equal to.]] |
| [[`ca <= cr`][bool][Less than equal to.]] |
| [[`cr >= cr2`][bool][Greater than equal to.]] |
| [[`cr >= ca`][bool][Greater than equal to.]] |
| [[`ca >= cr`][bool][Greater than equal to.]] |
| [[`cr < cr2`][bool][Less than comparison.]] |
| [[`cr < ca`][bool][Less than comparison.]] |
| [[`ca < cr`][bool][Less than comparison.]] |
| [[`cr > cr2`][bool][Greater than comparison.]] |
| [[`cr > ca`][bool][Greater than comparison.]] |
| [[`ca > cr`][bool][Greater than comparison.]] |
| [[`boost::math::tools::digits<RealType>()`][int] |
| [The number of digits in the significand of RealType.]] |
| [[`boost::math::tools::max_value<RealType>()`][RealType] |
| [The largest representable number by type RealType.]] |
| [[`boost::math::tools::min_value<RealType>()`][RealType] |
| [The smallest representable number by type RealType.]] |
| [[`boost::math::tools::log_max_value<RealType>()`][RealType] |
| [The natural logarithm of the largest representable number by type RealType.]] |
| [[`boost::math::tools::log_min_value<RealType>()`][RealType] |
| [The natural logarithm of the smallest representable number by type RealType.]] |
| [[`boost::math::tools::epsilon<RealType>()`][RealType] |
| [The machine epsilon of RealType.]] |
| ] |
| |
| Note that: |
| |
| # The functions `log_max_value` and `log_min_value` can be |
| synthesised from the others, and so no explicit specialisation is required. |
| # The function `epsilon` can be synthesised from the others, so no |
| explicit specialisation is required provided the precision |
| of RealType does not vary at runtime (see the header |
| [@../../../../../boost/math/bindings/rr.hpp boost/math/bindings/rr.hpp] |
| for an example where the precision does vary at runtime). |
| # The functions `digits`, `max_value` and `min_value`, all get synthesised |
| automatically from `std::numeric_limits`. However, if `numeric_limits` |
| is not specialised for type RealType, then you will get a compiler error |
| when code tries to use these functions, /unless/ you explicitly specialise them. |
| For example if the precision of RealType varies at runtime, then |
| `numeric_limits` support may not be appropriate, see |
| [@../../../../../boost/math/bindings/rr.hpp boost/math/bindings/rr.hpp] for examples. |
| |
| [warning |
| If `std::numeric_limits<>` is *not specialized* |
| for type /RealType/ then the default float precision of 6 decimal digits |
| will be used by other Boost programs including: |
| |
| Boost.Test: giving misleading error messages like |
| |
| ['"difference between {9.79796} and {9.79796} exceeds 5.42101e-19%".] |
| |
| Boost.LexicalCast and Boost.Serialization when converting the number |
| to a string, causing potentially serious loss of accuracy on output. |
| |
| Although it might seem obvious that RealType should require `std::numeric_limits` |
| to be specialized, this is not sensible for |
| `NTL::RR` and similar classes where the number of digits is a runtime |
| parameter (where as for `numeric_limits` it has to be fixed at compile time). |
| ] |
| |
| [h4 Standard Library Support Requirements] |
| |
| Many (though not all) of the functions in this library make calls |
| to standard library functions, the following table summarises the |
| requirements. Note that most of the functions in this library |
| will only call a small subset of the functions listed here, so if in |
| doubt whether a user defined type has enough standard library |
| support to be useable the best advise is to try it and see! |
| |
| In the following table /r/ is an object of type `RealType`, |
| /cr1/ and /cr2/ are objects of type `const RealType`, and |
| /i/ is an object of type `int`. |
| |
| [table |
| [[Expression][Result Type]] |
| [[`fabs(cr1)`][RealType]] |
| [[`abs(cr1)`][RealType]] |
| [[`ceil(cr1)`][RealType]] |
| [[`floor(cr1)`][RealType]] |
| [[`exp(cr1)`][RealType]] |
| [[`pow(cr1, cr2)`][RealType]] |
| [[`sqrt(cr1)`][RealType]] |
| [[`log(cr1)`][RealType]] |
| [[`frexp(cr1, &i)`][RealType]] |
| [[`ldexp(cr1, i)`][RealType]] |
| [[`cos(cr1)`][RealType]] |
| [[`sin(cr1)`][RealType]] |
| [[`asin(cr1)`][RealType]] |
| [[`tan(cr1)`][RealType]] |
| [[`atan(cr1)`][RealType]] |
| [[`fmod(cr1)`][RealType]] |
| [[`round(cr1)`][RealType]] |
| [[`iround(cr1)`][int]] |
| [[`trunc(cr1)`][RealType]] |
| [[`itrunc(cr1)`][int]] |
| ] |
| |
| Note that the table above lists only those standard library functions known to |
| be used (or likely to be used in the near future) by this library. |
| The following functions: `acos`, `atan2`, `fmod`, `cosh`, `sinh`, `tanh`, `log10`, |
| `lround`, `llround`, ltrunc`, `lltrunc` and `modf` |
| are not currently used, but may be if further special functions are added. |
| |
| Note that the `round`, `trunc` and `modf` functions are not part of the |
| current C++ standard: they are part of the additions added to C99 which will |
| likely be in the next C++ standard. There are Boost versions of these provided |
| as a backup, and the functions are always called unqualified so that |
| argument-dependent-lookup can take place. |
| |
| In addition, for efficient and accurate results, a __lanczos is highly desirable. |
| You may be able to adapt an existing approximation from |
| [@../../../../../boost/math/special_functions/lanczos.hpp |
| boost/math/special_functions/lanczos.hpp] or |
| [@../../../../../boost/math/bindings/detail/big_lanczos.hpp |
| boost/math/bindings/detail/big_lanczos.hpp]: |
| in the former case you will need change |
| static_cast's to lexical_cast's, and the constants to /strings/ |
| (in order to ensure the coefficients aren't truncated to long double) |
| and then specialise `lanczos_traits` for type T. Otherwise you may have to hack |
| [@../../../tools/lanczos_generator.cpp |
| libs/math/tools/lanczos_generator.cpp] to find a suitable |
| approximation for your RealType. The code will still compile if you don't do |
| this, but both accuracy and efficiency will be greatly compromised in any |
| function that makes use of the gamma\/beta\/erf family of functions. |
| |
| [endsect] |
| |
| [section:dist_concept Conceptual Requirements for Distribution Types] |
| |
| A /DistributionType/ is a type that implements the following conceptual |
| requirements, and encapsulates a statistical distribution. |
| |
| Please note that this documentation should not be used as a substitute |
| for the |
| [link math_toolkit.dist.dist_ref reference documentation], and |
| [link math_toolkit.dist.stat_tut tutorial] of the statistical |
| distributions. |
| |
| In the following table, /d/ is an object of type `DistributionType`, |
| /cd/ is an object of type `const DistributionType` and /cr/ is an |
| object of a type convertible to `RealType`. |
| |
| [table |
| [[Expression][Result Type][Notes]] |
| [[DistributionType::value_type][RealType] |
| [The real-number type /RealType/ upon which the distribution operates.]] |
| [[DistributionType::policy_type][RealType] |
| [The __Policy to use when evaluating functions that depend on this distribution.]] |
| [[d = cd][Distribution&][Distribution types are assignable.]] |
| [[Distribution(cd)][Distribution][Distribution types are copy constructible.]] |
| [[pdf(cd, cr)][RealType][Returns the PDF of the distribution.]] |
| [[cdf(cd, cr)][RealType][Returns the CDF of the distribution.]] |
| [[cdf(complement(cd, cr))][RealType] |
| [Returns the complement of the CDF of the distribution, |
| the same as: `1-cdf(cd, cr)`]] |
| [[quantile(cd, cr)][RealType][Returns the quantile of the distribution.]] |
| [[quantile(complement(cd, cr))][RealType] |
| [Returns the quantile of the distribution, starting from |
| the complement of the probability, the same as: `quantile(cd, 1-cr)`]] |
| [[chf(cd, cr)][RealType][Returns the cumulative hazard function of the distribution.]] |
| [[hazard(cd, cr)][RealType][Returns the hazard function of the distribution.]] |
| [[kurtosis(cd)][RealType][Returns the kurtosis of the distribution.]] |
| [[kurtosis_excess(cd)][RealType][Returns the kurtosis excess of the distribution.]] |
| [[mean(cd)][RealType][Returns the mean of the distribution.]] |
| [[mode(cd)][RealType][Returns the mode of the distribution.]] |
| [[skewness(cd)][RealType][Returns the skewness of the distribution.]] |
| [[standard_deviation(cd)][RealType][Returns the standard deviation of the distribution.]] |
| [[variance(cd)][RealType][Returns the variance of the distribution.]] |
| ] |
| |
| [endsect] |
| |
| [section:archetypes Conceptual Archetypes and Testing] |
| |
| There are several concept archetypes available: |
| |
| ``#include <boost/concepts/std_real_concept.hpp>`` |
| |
| namespace boost{ |
| namespace math{ |
| namespace concepts{ |
| |
| class std_real_concept; |
| |
| }}} // namespaces |
| |
| `std_real_concept` is an archetype for the built-in Real types. |
| |
| The main purpose in providing this type is to verify |
| that standard library functions are found via a using declaration - |
| bringing those functions into the current scope - and not |
| just because they happen to be in global scope. |
| |
| In order to ensure that a call to say `pow` can be found |
| either via argument dependent lookup, or failing that then |
| in the std namespace: all calls to standard library functions |
| are unqualified, with the std:: versions found via a using declaration |
| to make them visible in the current scope. Unfortunately it's all |
| to easy to forget the using declaration, and call the double version of |
| the function that happens to be in the global scope by mistake. |
| |
| For example if the code calls ::pow rather than std::pow, |
| the code will cleanly compile, but truncation of long doubles to |
| double will cause a significant loss of precision. |
| In contrast a template instantiated with std_real_concept will *only* |
| compile if the all the standard library functions used have |
| been brought into the current scope with a using declaration. |
| |
| There is a test program |
| [@../../../test/std_real_concept_check.cpp libs/math/test/std_real_concept_check.cpp] |
| that instantiates every template in this library with type |
| `std_real_concept` to verify it's usage of standard library functions. |
| |
| ``#include <boost/math/concepts/real_concept.hpp>`` |
| |
| namespace boost{ |
| namespace math{ |
| namespace concepts{ |
| |
| class real_concept; |
| |
| }}} // namespaces |
| |
| `real_concept` is an archetype for [link math_toolkit.using_udt.concepts |
| user defined real types], it |
| declares it's standard library functions in it's own |
| namespace: these will only be found if they are called unqualified |
| allowing argument dependent lookup to locate them. In addition |
| this type is useable at runtime: |
| this allows code that would not otherwise be exercised by the built-in |
| floating point types to be tested. There is no std::numeric_limits<> |
| support for this type, since this is not a conceptual requirement |
| for [link math_toolkit.using_udt.concepts RealType]'s. |
| |
| NTL RR is an example of a type meeting the requirements that this type |
| models, but note that use of a thin wrapper class is required: refer to |
| [link math_toolkit.using_udt.use_ntl "Using With NTL - a High-Precision Floating-Point Library"]. |
| |
| There is no specific test case for type `real_concept`, instead, since this |
| type is usable at runtime, each individual test case as well as testing |
| `float`, `double` and `long double`, also tests `real_concept`. |
| |
| ``#include <boost/math/concepts/distribution.hpp>`` |
| |
| namespace boost{ |
| namespace math{ |
| namespace concepts{ |
| |
| template <class RealType> |
| class distribution_archetype; |
| |
| template <class Distribution> |
| struct DistributionConcept; |
| |
| }}} // namespaces |
| |
| The class template `distribution_archetype` is a model of the |
| [link math_toolkit.using_udt.dist_concept Distribution concept]. |
| |
| The class template `DistributionConcept` is a |
| [@../../../../../libs/concept_check/index.html concept checking class] |
| for distribution types. |
| |
| The test program |
| [@../../../test/compile_test/distribution_concept_check.cpp distribution_concept_check.cpp] |
| is responsible for using `DistributionConcept` to verify that all the |
| distributions in this library conform to the |
| [link math_toolkit.using_udt.dist_concept Distribution concept]. |
| |
| The class template `DistributionConcept` verifies the existence |
| (but not proper function) of the non-member accessors |
| required by the [link math_toolkit.using_udt.dist_concept Distribution concept]. |
| These are checked by calls like |
| |
| v = pdf(dist, x); // (Result v is ignored). |
| |
| And in addition, those that accept two arguments do the right thing when the |
| arguments are of different types (the result type is always the same as the |
| distribution's value_type). (This is implemented by some additional |
| forwarding-functions in derived_accessors.hpp, so that there is no need for |
| any code changes. Likewise boilerplate versions of the |
| hazard\/chf\/coefficient_of_variation functions are implemented in |
| there too.) |
| |
| [endsect][/section:archetypes Conceptual Archetypes and Testing] |
| |
| |
| [/ |
| 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). |
| ] |
| |
| |
| |
| |
