libs/math/doc/concepts/concepts.qbk

   1 [section:high_precision Using Boost.Math with High-Precision Floating-Point Libraries]
   2
   3 The special functions, distributions, constants and tools in this library
   4 can be used with a number of high-precision libraries, including:
   5
   6 * __multiprecision
   7 * __e_float
   8 * __NTL
   9 * __GMP
  10 * __MPFR
  11 * __gcc_quad_type
  12 * Intel _Quad type
  13
  14 The last four have some license restrictions;
  15 only __multiprecision when using the `cpp_float` backend
  16 can provide an unrestricted [@http://www.boost.org/LICENSE_1_0.txt Boost] license.
  17
  18 At present, the price of a free license is slightly lower speed.
  19
  20 Of course, the main cost of higher precision is very much decreased
  21 (usually at least hundred-fold) computation speed, and big increases in memory use.
  22
  23 Some libraries offer true
  24 [@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary-precision arithmetic]
  25 where the precision is limited only by available memory and compute time, but most are used
  26 at some arbitrarily-fixed precision, say 100 decimal digits, like __multiprecision `cpp_dec_float_100`.
  27
  28 __multiprecision can operate in both ways, but the most popular choice is likely to be about a hundred
  29 decimal digits, though examples of computing about a million digits have been demonstrated.
  30
  31 [section:why_high_precision  Why use a high-precision library rather than built-in floating-point types?]
  32
  33 For nearly all applications, the built-in floating-point types, `double`
  34 (and `long double` if this offers higher precision than `double`)
  35 offer enough precision, typically a dozen decimal digits.
  36
  37 Some reasons why one would want to use a higher precision:
  38
  39 * A much more precise result (many more digits) is just a requirement.
  40 * The range of the computed value exceeds the range of the type: factorials are the textbook example.
  41 * Using `double` is (or may be) too inaccurate.
  42 * Using `long double` (or may be) is too inaccurate.
  43 * Using an extended-precision type implemented in software as
  44 [@http://en.wikipedia.org/wiki/Double-double_(arithmetic)#Double-double_arithmetic double-double]
  45 ([@http://en.wikipedia.org/wiki/Darwin_(operating_system) Darwin]) is sometimes unpredictably inaccurate.
  46 * Loss of precision or inaccuracy caused by extreme arguments or
  47 [@http://en.wikipedia.org/wiki/Loss_of_significance cancellation errors].
  48 * An accuracy as good as possible for a chosen built-in floating-point type is required.
  49 * As a reference value, for example, to determine the inaccuracy
  50 of a value computed with a built-in floating point type,
  51 (perhaps even using some quick'n'dirty algorithm).
  52 The accuracy of many functions and distributions in Boost.Math has been measured in this way
  53 from tables of very high precision (up to 1000 decimal digits).
  54
  55 Many functions and distributions have differences from exact values
  56 that are only a few least significant bits - computation noise.
  57 Others, often those for which analytical solutions are not available,
  58 require approximations and iteration:
  59 these may lose several decimal digits of precision.
  60
  61 Much larger loss of precision can occur for [@http://en.wikipedia.org/wiki/Boundary_case boundary]
  62 or [@http://en.wikipedia.org/wiki/Corner_case corner cases],
  63 often caused by [@http://en.wikipedia.org/wiki/Loss_of_significance cancellation errors].
  64
  65 (Some of the worst and most common examples of
  66 [@http://en.wikipedia.org/wiki/Loss_of_significance cancellation error or loss of significance]
  67 can be avoided by using __complements: see __why_complements).
  68
  69 If you require a value which is as accurate as can be represented in the floating-point type,
  70 and is thus the
  71 [@https://en.wikipedia.org/wiki/Floating-point_arithmetic#Representable_numbers,_conversion_and_rounding closest representable value]
  72 correctly rounded to nearest,
  73 and has an error less than 1/2 a
  74 [@http://en.wikipedia.org/wiki/Least_significant_bit least significant bit] or
  75 [@http://en.wikipedia.org/wiki/Unit_in_the_last_place ulp]
  76 it may be useful to use a higher-precision type,
  77 for example, `cpp_dec_float_50`, to generate this value.
  78 Conversion of this value to a built-in floating-point type ('float', `double` or `long double`)
  79 will not cause any further loss of precision.
  80 A decimal digit string will also be 'read' precisely by the compiler
  81 into a built-in floating-point type to the nearest representable value.
  82
  83 [note In contrast, reading a value from an `std::istream` into a built-in floating-point type
  84 is [*not guaranteed by the C++ Standard] to give the nearest representable value.]
  85
  86 William Kahan coined the term
  87 [@http://en.wikipedia.org/wiki/Rounding#The_table-maker.27s_dilemma Table-Maker's Dilemma]
  88 for the problem of correctly rounding functions.
  89 Using a much higher precision (50 or 100 decimal digits)
  90 is a practical way of generating (almost always) correctly rounded values.
  91
  92 [endsect] [/section:why_high_precision  Why use a high-precision library rather than built-in floating-point types?]
  93
  94 [section:use_multiprecision Using Boost.Multiprecision]
  95
  96 [*All new projects are recommended to use __multiprecision.]
  97
  98 [import ../../example/big_seventh.cpp]
  99
 100 [big_seventh_example_1]
 101 [big_seventh_example_2]
 102 The full source of this example is at [@../../example/big_seventh.cpp big_seventh.cpp]
 103
 104 [import ../../example/fft_sines_table.cpp]
 105
 106 [fft_sines_table_example_1]
 107 [fft_sines_table_example_2]
 108 [fft_sines_table_example_3
 109 ]
 110
 111 The table output is:
 112
 113 [fft_sines_table_example_output]
 114
 115 [fft_sines_table_example_check]
 116
 117 The full source of this example is at [@../../example/fft_sines_table.cpp fft_sines_table.cpp]
 118
 119 [/TODO another example needed here]
 120
 121 [/import ../../example/ibeta_mp_example.cpp]
 122
 123 [/ibeta_mp_example_1]
 124
 125 [/The program output is:]
 126
 127 [/ibeta_mp_output_1]
 128
 129 [endsect] [/section:use_multiprecision Using Boost.Multiprecision]
 130
 131 [section:float128 Using with GCC's __float128 datatype]
 132
 133 At present support for GCC's native `__float128` datatype is extremely limited: the numeric constants
 134 will all work with that type, and that's about it.  If you want to use the distributions or special
 135 functions then you will need to provide your own wrapper header that:
 136
 137 * Provides `std::numeric_limits<__float128>` support.
 138 * Provides overloads of the standard library math functions for type `__float128`
 139 and which forward to the libquadmath equivalents.
 140
 141 Ultimately these facilities should be provided by GCC and `libstdc++`.
 142
 143 [endsect] [/section:float128 Using with GCC's __float128 datatype]
 144
 145
 146 [section:use_mpfr Using With MPFR or GMP - High-Precision Floating-Point Library]
 147
 148 The special functions and tools in this library can be used with
 149 [@http://www.mpfr.org MPFR] (an arbitrary precision number type based on the __GMP),
 150 either via the bindings in [@../../../../boost/math/bindings/mpfr.hpp boost/math/bindings/mpfr.hpp],
 151 or via [@../../../../boost/math/bindings/mpfr.hpp boost/math/bindings/mpreal.hpp].
 152
 153 [*New projects are recommended to use __multiprecision with GMP/MPFR backend instead.]
 154
 155 In order to use these bindings you will need to have installed [@http://www.mpfr.org MPFR]
 156 plus its dependency the [@http://gmplib.org GMP library].  You will also need one of the
 157 two supported C++ wrappers for MPFR:
 158 [@http://math.berkeley.edu/~wilken/code/gmpfrxx/ gmpfrxx (or mpfr_class)],
 159 or [@http://www.holoborodko.com/pavel/mpfr/ mpfr-C++ (mpreal)].
 160
 161 Unfortunately neither `mpfr_class` nor `mpreal` quite satisfy our conceptual requirements,
 162 so there is a very thin set of additional interfaces and some helper traits defined in
 163 [@../../../../boost/math/bindings/mpfr.hpp boost/math/bindings/mpfr.hpp] and
 164 [@../../../../boost/math/bindings/mpreal.hpp boost/math/bindings/mpreal.hpp]
 165 that you should use in place of including 'gmpfrxx.h' or 'mpreal.h' directly.
 166 The classes `mpfr_class` or `mpreal` are
 167 then usable unchanged once this header is included, so for example `mpfr_class`'s
 168 performance-enhancing expression templates are preserved and fully supported by this library:
 169
 170    #include <boost/math/bindings/mpfr.hpp>
 171    #include <boost/math/special_functions/gamma.hpp>
 172
 173    int main()
 174    {
 175       mpfr_class::set_dprec(500); // 500 bit precision
 176       //
 177       // Note that the argument to tgamma is
 178       // an expression template - that's just fine here.
 179       //
 180       mpfr_class v = boost::math::tgamma(sqrt(mpfr_class(2)));
 181       std::cout << std::setprecision(50) << v << std::endl;
 182    }
 183
 184 Alternatively use with `mpreal` would look like:
 185
 186    #include <boost/math/bindings/mpreal.hpp>
 187    #include <boost/math/special_functions/gamma.hpp>
 188
 189    int main()
 190    {
 191       mpfr::mpreal::set_precision(500); // 500 bit precision
 192       mpfr::mpreal v = boost::math::tgamma(sqrt(mpfr::mpreal(2)));
 193       std::cout << std::setprecision(50) << v << std::endl;
 194    }
 195
 196 There is a concept checking test program for mpfr support
 197 [@../../../../libs/math/test/mpfr_concept_check.cpp here] and
 198 [@../../../../libs/math/test/mpreal_concept_check.cpp here].
 199
 200 [endsect] [/section:use_mpfr Using With MPFR / GMP - a High-Precision Floating-Point Library]
 201
 202 [section:e_float Using e_float Library]
 203
 204 __multiprecision was a development from the __e_float library by Christopher Kormanyos.
 205
 206 e_float can still be used with Boost.Math library via the header:
 207
 208    <boost/math/bindings/e_float.hpp>
 209
 210 And the type `boost::math::ef::e_float`:
 211 this type is a thin wrapper class around ::e_float which provides the necessary
 212 syntactic sugar to make everything "just work".
 213
 214 There is also a concept checking test program for e_float support
 215 [@../../../../libs/math/test/e_float_concept_check.cpp here].
 216
 217 [*New projects are recommended to use __multiprecision with `cpp_float` backend instead.]
 218
 219 [endsect] [/section:e_float Using e_float Library]
 220
 221 [section:use_ntl Using NTL Library]
 222
 223 [@http://shoup.net/ntl/doc/RR.txt NTL::RR]
 224 (an arbitrarily-fixed precision floating-point number type),
 225 can be used via the bindings in
 226 [@../../../../boost/math/bindings/rr.hpp boost/math/bindings/rr.hpp].
 227 For details, see [@http://shoup.net/ntl/ NTL: A Library for doing Number Theory by
 228 Victor Shoup].
 229
 230 [*New projects are recommended to use __multiprecision instead.]
 231
 232 Unfortunately `NTL::RR` doesn't quite satisfy our conceptual requirements,
 233 so there is a very thin wrapper class `boost::math::ntl::RR` defined in
 234 [@../../../../boost/math/bindings/rr.hpp boost/math/bindings/rr.hpp] that you
 235 should use in place of `NTL::RR`.  The class is intended to be a drop-in
 236 replacement for the "real" NTL::RR that adds some syntactic sugar to keep
 237 this library happy, plus some of the standard library functions not implemented
 238 in NTL.
 239
 240 For those functions that are based upon the __lanczos, the bindings
 241 defines a series of approximations with up to 61 terms and accuracy
 242 up to approximately 3e-113.  This therefore sets the upper limit for accuracy
 243 to the majority of functions defined this library when used with `NTL::RR`.
 244
 245 There is a concept checking test program for NTL support
 246 [@../../../../libs/math/test/ntl_concept_check.cpp here].
 247
 248 [endsect] [/section:use_ntl Using With NTL - a High-Precision Floating-Point Library]
 249
 250 [section:using_test Using without expression templates for Boost.Test and others]
 251
 252 As noted in the __multiprecision documentation, certain program constructs will not compile
 253 when using expression templates.  One example that many users may encounter
 254 is Boost.Test (1.54 and earlier) when using macro BOOST_CHECK_CLOSE and BOOST_CHECK_CLOSE_FRACTION.
 255
 256 If, for example, you wish to use any multiprecision type like `cpp_dec_float_50`
 257 in place of `double` to give more precision,
 258 you will need to override the default `boost::multiprecision::et_on` with
 259 `boost::multiprecision::et_off`.
 260
 261 [import ../../example/test_cpp_float_close_fraction.cpp]
 262
 263 [expression_template_1]
 264
 265 A full example code is at [@../../example/test_cpp_float_close_fraction.cpp test_cpp_float_close_fraction.cpp]
 266
 267 [endsect] [/section:using_test Using without expression templates for Boost.Test and others]
 268 [endsect] [/section:high_precision Using With High-Precision Floating-Point Libraries]
 269
 270 [section:real_concepts Conceptual Requirements for Real Number Types]
 271
 272 The functions and statistical distributions in this library can be used with
 273 any type ['RealType] that meets the conceptual requirements given below.  All
 274 the built-in floating-point types like `double` will meet these requirements.
 275 (Built-in types are also called __fundamental_types).
 276
 277 User-defined types that meet the conceptual requirements can also be used.
 278 For example, with [link math_toolkit.high_precision.use_ntl a thin wrapper class]
 279 one of the types provided with [@http://shoup.net/ntl/ NTL (RR)] can be used.
 280 But now that __multiprecision library is available,
 281 this has become the preferred real-number type,
 282 typically __cpp_dec_float or __cpp_bin_float.
 283
 284 Submissions of binding to other extended precision types would also still be welcome.
 285
 286 The guiding principal behind these requirements is that a ['RealType]
 287 behaves just like a built-in floating-point type.
 288
 289 [h4 Basic Arithmetic Requirements]
 290
 291 These requirements are common to all of the functions in this library.
 292
 293 In the following table /r/ is an object of type `RealType`, /cr/ and
 294 /cr2/ are objects
 295 of type `const RealType`, and /ca/ is an object of type `const arithmetic-type`
 296 (arithmetic types include all the built in integers and floating point types).
 297
 298 [table
 299 [[Expression][Result Type][Notes]]
 300 [[`RealType(cr)`][RealType]
 301       [RealType is copy constructible.]]
 302 [[`RealType(ca)`][RealType]
 303       [RealType is copy constructible from the arithmetic types.]]
 304 [[`r = cr`][RealType&][Assignment operator.]]
 305 [[`r = ca`][RealType&][Assignment operator from the arithmetic types.]]
 306 [[`r += cr`][RealType&][Adds cr to r.]]
 307 [[`r += ca`][RealType&][Adds ar to r.]]
 308 [[`r -= cr`][RealType&][Subtracts cr from r.]]
 309 [[`r -= ca`][RealType&][Subtracts ca from r.]]
 310 [[`r *= cr`][RealType&][Multiplies r by cr.]]
 311 [[`r *= ca`][RealType&][Multiplies r by ca.]]
 312 [[`r /= cr`][RealType&][Divides r by cr.]]
 313 [[`r /= ca`][RealType&][Divides r by ca.]]
 314 [[`-r`][RealType][Unary Negation.]]
 315 [[`+r`][RealType&][Identity Operation.]]
 316 [[`cr + cr2`][RealType][Binary Addition]]
 317 [[`cr + ca`][RealType][Binary Addition]]
 318 [[`ca + cr`][RealType][Binary Addition]]
 319 [[`cr - cr2`][RealType][Binary Subtraction]]
 320 [[`cr - ca`][RealType][Binary Subtraction]]
 321 [[`ca - cr`][RealType][Binary Subtraction]]
 322 [[`cr * cr2`][RealType][Binary Multiplication]]
 323 [[`cr * ca`][RealType][Binary Multiplication]]
 324 [[`ca * cr`][RealType][Binary Multiplication]]
 325 [[`cr / cr2`][RealType][Binary Subtraction]]
 326 [[`cr / ca`][RealType][Binary Subtraction]]
 327 [[`ca / cr`][RealType][Binary Subtraction]]
 328 [[`cr == cr2`][bool][Equality Comparison]]
 329 [[`cr == ca`][bool][Equality Comparison]]
 330 [[`ca == cr`][bool][Equality Comparison]]
 331 [[`cr != cr2`][bool][Inequality Comparison]]
 332 [[`cr != ca`][bool][Inequality Comparison]]
 333 [[`ca != cr`][bool][Inequality Comparison]]
 334 [[`cr <= cr2`][bool][Less than equal to.]]
 335 [[`cr <= ca`][bool][Less than equal to.]]
 336 [[`ca <= cr`][bool][Less than equal to.]]
 337 [[`cr >= cr2`][bool][Greater than equal to.]]
 338 [[`cr >= ca`][bool][Greater than equal to.]]
 339 [[`ca >= cr`][bool][Greater than equal to.]]
 340 [[`cr < cr2`][bool][Less than comparison.]]
 341 [[`cr < ca`][bool][Less than comparison.]]
 342 [[`ca < cr`][bool][Less than comparison.]]
 343 [[`cr > cr2`][bool][Greater than comparison.]]
 344 [[`cr > ca`][bool][Greater than comparison.]]
 345 [[`ca > cr`][bool][Greater than comparison.]]
 346 [[`boost::math::tools::digits<RealType>()`][int]
 347       [The number of digits in the significand of RealType.]]
 348 [[`boost::math::tools::max_value<RealType>()`][RealType]
 349       [The largest representable number by type RealType.]]
 350 [[`boost::math::tools::min_value<RealType>()`][RealType]
 351       [The smallest representable number by type RealType.]]
 352 [[`boost::math::tools::log_max_value<RealType>()`][RealType]
 353       [The natural logarithm of the largest representable number by type RealType.]]
 354 [[`boost::math::tools::log_min_value<RealType>()`][RealType]
 355       [The natural logarithm of the smallest representable number by type RealType.]]
 356 [[`boost::math::tools::epsilon<RealType>()`][RealType]
 357       [The machine epsilon of RealType.]]
 358 ]
 359
 360 Note that:
 361
 362 # The functions `log_max_value` and `log_min_value` can be
 363 synthesised from the others, and so no explicit specialisation is required.
 364 # The function `epsilon` can be synthesised from the others, so no
 365 explicit specialisation is required provided the precision
 366 of RealType does not vary at runtime (see the header
 367 [@../../../../boost/math/bindings/rr.hpp boost/math/bindings/rr.hpp]
 368 for an example where the precision does vary at runtime).
 369 # The functions `digits`, `max_value` and `min_value`, all get synthesised
 370 automatically from `std::numeric_limits`.  However, if `numeric_limits`
 371 is not specialised for type RealType, then you will get a compiler error
 372 when code tries to use these functions, /unless/ you explicitly specialise them.
 373 For example if the precision of RealType varies at runtime, then
 374 `numeric_limits` support may not be appropriate, see
 375 [@../../../../boost/math/bindings/rr.hpp boost/math/bindings/rr.hpp] for examples.
 376
 377 [warning
 378 If `std::numeric_limits<>` is *not specialized*
 379 for type /RealType/ then the default float precision of 6 decimal digits
 380 will be used by other Boost programs including:
 381
 382 Boost.Test: giving misleading error messages like
 383
 384 ['"difference between {9.79796} and {9.79796} exceeds 5.42101e-19%".]
 385
 386 Boost.LexicalCast and Boost.Serialization when converting the number
 387 to a string, causing potentially serious loss of accuracy on output.
 388
 389 Although it might seem obvious that RealType should require `std::numeric_limits`
 390 to be specialized, this is not sensible for
 391 `NTL::RR` and similar classes where the  [*number of digits is a runtime parameter]
 392 (whereas for `numeric_limits` everything has to be fixed at compile time).
 393 ]
 394
 395 [h4 Standard Library Support Requirements]
 396
 397 Many (though not all) of the functions in this library make calls
 398 to standard library functions, the following table summarises the
 399 requirements.  Note that most of the functions in this library
 400 will only call a small subset of the functions listed here, so if in
 401 doubt whether a user-defined type has enough standard library
 402 support to be useable the best advise is to try it and see!
 403
 404 In the following table /r/ is an object of type `RealType`,
 405 /cr1/ and /cr2/ are objects of type `const RealType`, and
 406 /i/ is an object of type `int`.
 407
 408 [table
 409 [[Expression][Result Type]]
 410 [[`fabs(cr1)`][RealType]]
 411 [[`abs(cr1)`][RealType]]
 412 [[`ceil(cr1)`][RealType]]
 413 [[`floor(cr1)`][RealType]]
 414 [[`exp(cr1)`][RealType]]
 415 [[`pow(cr1, cr2)`][RealType]]
 416 [[`sqrt(cr1)`][RealType]]
 417 [[`log(cr1)`][RealType]]
 418 [[`frexp(cr1, &i)`][RealType]]
 419 [[`ldexp(cr1, i)`][RealType]]
 420 [[`cos(cr1)`][RealType]]
 421 [[`sin(cr1)`][RealType]]
 422 [[`asin(cr1)`][RealType]]
 423 [[`tan(cr1)`][RealType]]
 424 [[`atan(cr1)`][RealType]]
 425 [[`fmod(cr1)`][RealType]]
 426 [[`round(cr1)`][RealType]]
 427 [[`iround(cr1)`][int]]
 428 [[`trunc(cr1)`][RealType]]
 429 [[`itrunc(cr1)`][int]]
 430 ]
 431
 432 Note that the table above lists only those standard library functions known to
 433 be used (or likely to be used in the near future) by this library.
 434 The following functions: `acos`, `atan2`, `fmod`, `cosh`, `sinh`, `tanh`, `log10`,
 435 `lround`, `llround`, `ltrunc`, `lltrunc` and `modf`
 436 are not currently used, but may be if further special functions are added.
 437
 438 Note that the `round`, `trunc` and `modf` functions are not part of the
 439 current C++ standard: they are part of the additions added to C99 which will
 440 likely be in the next C++ standard.  There are Boost versions of these provided
 441 as a backup, and the functions are always called unqualified so that
 442 argument-dependent-lookup can take place.
 443
 444 In addition, for efficient and accurate results, a __lanczos is highly desirable.
 445 You may be able to adapt an existing approximation from
 446 [@../../../../boost/math/special_functions/lanczos.hpp
 447 boost/math/special_functions/lanczos.hpp] or
 448 [@../../../../boost/math/bindings/detail/big_lanczos.hpp
 449 boost/math/bindings/detail/big_lanczos.hpp]:
 450 in the former case you will need change
 451 `static_cast`'s to `lexical_cast`'s, and the constants to /strings/
 452 (in order to ensure the coefficients aren't truncated to `long doubl`e)
 453 and then specialise `lanczos_traits` for type T.  Otherwise you may have to hack
 454 [@../../tools/lanczos_generator.cpp
 455 libs/math/tools/lanczos_generator.cpp] to find a suitable
 456 approximation for your RealType.  The code will still compile if you don't do
 457 this, but both accuracy and efficiency will be somewhat compromised in any
 458 function that makes use of the gamma\/beta\/erf family of functions.
 459
 460 [endsect] [/section:real_concepts Conceptual Requirements for Real Number Types]
 461
 462 [section:dist_concept Conceptual Requirements for Distribution Types]
 463
 464 A ['DistributionType] is a type that implements the following conceptual
 465 requirements, and encapsulates a statistical distribution.
 466
 467 Please note that this documentation should not be used as a substitute
 468 for the
 469 [link math_toolkit.dist_ref reference documentation], and
 470 [link math_toolkit.stat_tut tutorial] of the statistical
 471 distributions.
 472
 473 In the following table, ['d] is an object of type `DistributionType`,
 474 ['cd] is an object of type `const DistributionType` and ['cr] is an
 475 object of a type convertible to `RealType`.
 476
 477 [table
 478 [[Expression][Result Type][Notes]]
 479 [[DistributionType::value_type][RealType]
 480       [The real-number type /RealType/ upon which the distribution operates.]]
 481 [[DistributionType::policy_type][RealType]
 482       [The __Policy to use when evaluating functions that depend on this distribution.]]
 483 [[d = cd][Distribution&][Distribution types are assignable.]]
 484 [[Distribution(cd)][Distribution][Distribution types are copy constructible.]]
 485 [[pdf(cd, cr)][RealType][Returns the PDF of the distribution.]]
 486 [[cdf(cd, cr)][RealType][Returns the CDF of the distribution.]]
 487 [[cdf(complement(cd, cr))][RealType]
 488       [Returns the complement of the CDF of the distribution,
 489       the same as: `1-cdf(cd, cr)`]]
 490 [[quantile(cd, cr)][RealType][Returns the quantile (or percentile) of the distribution.]]
 491 [[quantile(complement(cd, cr))][RealType]
 492       [Returns the quantile (or percentile) of the distribution, starting from
 493       the complement of the probability, the same as: `quantile(cd, 1-cr)`]]
 494 [[chf(cd, cr)][RealType][Returns the cumulative hazard function of the distribution.]]
 495 [[hazard(cd, cr)][RealType][Returns the hazard function of the distribution.]]
 496 [[kurtosis(cd)][RealType][Returns the kurtosis of the distribution.]]
 497 [[kurtosis_excess(cd)][RealType][Returns the kurtosis excess of the distribution.]]
 498 [[mean(cd)][RealType][Returns the mean of the distribution.]]
 499 [[mode(cd)][RealType][Returns the mode of the distribution.]]
 500 [[skewness(cd)][RealType][Returns the skewness of the distribution.]]
 501 [[standard_deviation(cd)][RealType][Returns the standard deviation of the distribution.]]
 502 [[variance(cd)][RealType][Returns the variance of the distribution.]]
 503 ]
 504
 505 [endsect] [/ section:dist_concept Conceptual Requirements for Distribution Types]
 506
 507 [section:archetypes Conceptual Archetypes for Reals and Distributions]
 508
 509 There are a few concept archetypes available:
 510
 511 * Real concept for floating-point types.
 512 * Distribution concept for statistical distributions.
 513
 514 [h5:real_concept Real concept]
 515
 516 `std_real_concept` is an archetype for theReal types,
 517 including the built-in float, double, long double.
 518
 519 ``#include <boost/concepts/std_real_concept.hpp>``
 520
 521    namespace boost{
 522    namespace math{
 523    namespace concepts
 524    {
 525      class std_real_concept;
 526    }
 527    }} // namespaces
 528
 529
 530 The main purpose in providing this type is to verify
 531 that standard library functions are found via a using declaration -
 532 bringing those functions into the current scope -
 533 and not just because they happen to be in global scope.
 534
 535 In order to ensure that a call to say `pow` can be found
 536 either via argument dependent lookup, or failing that then
 537 in the std namespace: all calls to standard library functions
 538 are unqualified, with the std:: versions found via a `using` declaration
 539 to make them visible in the current scope.  Unfortunately it's all
 540 to easy to forget the `using` declaration, and call the double version of
 541 the function that happens to be in the global scope by mistake.
 542
 543 For example if the code calls ::pow rather than std::pow,
 544 the code will cleanly compile, but truncation of long doubles to
 545 double will cause a significant loss of precision.
 546 In contrast a template instantiated with std_real_concept will *only*
 547 compile if the all the standard library functions used have
 548 been brought into the current scope with a using declaration.
 549
 550 [h6 Testing the real concept]
 551
 552 There is a test program
 553 [@../../test/std_real_concept_check.cpp libs/math/test/std_real_concept_check.cpp]
 554 that instantiates every template in this library with type
 555 `std_real_concept` to verify its usage of standard library functions.
 556
 557 ``#include <boost/math/concepts/real_concept.hpp>``
 558
 559    namespace boost{
 560    namespace math{
 561    namespace concepts{
 562
 563    class real_concept;
 564
 565    }}} // namespaces
 566
 567 `real_concept` is an archetype for
 568 [link math_toolkit.real_concepts user defined real types],
 569 it declares its standard library functions in its own
 570 namespace: these will only be found if they are called unqualified
 571 allowing argument dependent lookup to locate them.  In addition
 572 this type is useable at runtime:
 573 this allows code that would not otherwise be exercised by the built-in
 574 floating point types to be tested.  There is no std::numeric_limits<>
 575 support for this type, since numeric_limits is not a conceptual requirement
 576 for [link math_toolkit.real_concepts RealType]s.
 577
 578 NTL RR is an example of a type meeting the requirements that this type
 579 models, but note that use of a thin wrapper class is required: refer to
 580 [link math_toolkit.high_precision.use_ntl "Using With NTL - a High-Precision Floating-Point Library"].
 581
 582 There is no specific test case for type `real_concept`, instead, since this
 583 type is usable at runtime, each individual test case as well as testing
 584 `float`, `double` and `long double`, also tests `real_concept`.
 585
 586 [h6:distribution_concept Distribution Concept]
 587
 588 Distribution Concept models statistical distributions.
 589
 590 ``#include <boost/math/concepts/distribution.hpp>``
 591
 592    namespace boost{
 593    namespace math{
 594    namespace concepts
 595    {
 596      template <class RealType>
 597      class distribution_archetype;
 598
 599      template <class Distribution>
 600      struct DistributionConcept;
 601
 602    }}} // namespaces
 603
 604 The class template `distribution_archetype` is a model of the
 605 [link math_toolkit.dist_concept Distribution concept].
 606
 607 The class template `DistributionConcept` is a
 608 [@../../../../libs/concept_check/index.html concept checking class]
 609 for distribution types.
 610
 611 [h6 Testing the distribution concept]
 612
 613 The test program
 614 [@../../test/compile_test/distribution_concept_check.cpp distribution_concept_check.cpp]
 615 is responsible for using `DistributionConcept` to verify that all the
 616 distributions in this library conform to the
 617 [link math_toolkit.dist_concept Distribution concept].
 618
 619 The class template `DistributionConcept` verifies the existence
 620 (but not proper function) of the non-member accessors
 621 required by the [link math_toolkit.dist_concept Distribution concept].
 622 These are checked by calls like
 623
 624   v = pdf(dist, x); // (Result v is ignored).
 625
 626 And in addition, those that accept two arguments do the right thing when the
 627 arguments are of different types (the result type is always the same as the
 628 distribution's value_type).  (This is implemented by some additional
 629 forwarding-functions in derived_accessors.hpp, so that there is no need for
 630 any code changes.  Likewise boilerplate versions of the
 631 hazard\/chf\/coefficient_of_variation functions are implemented in
 632 there too.)
 633
 634 [endsect] [/section:archetypes Conceptual Archetypes for Reals and Distributions]
 635 [/
 636   Copyright 2006, 2010, 2012 John Maddock and Paul A. Bristow.
 637   Distributed under the Boost Software License, Version 1.0.
 638   (See accompanying file LICENSE_1_0.txt or copy at
 639   http://www.boost.org/LICENSE_1_0.txt).
 640 ]
 641
 642
 643
 644