math/doc/concepts.qbk

[section:use_NTL Using With NTL - a High-Precision Floating-Point Library]

The special functions and tools in this library can be used with
__NTL__RR (arbitrary precision),
[/@http://shoup.net/ntl/doc/RR.txt NTL::RR]
and to a lesser extent with
[@http://shoup.net/ntl/doc/quad_float.txt NTL::quad_float] (128-bit, using 106 significand bits).
[@http://shoup.net/ntl/ NTL: A Library for doing Number Theory by Victor Shoup]

In order to do so you will need to apply the following patch to NTL: libs/math/tools/ntl.diff
This patch adds trivial converting constructors to NTL::RR and NTL::quad_float,
and forces conversions to RR to proceed via `long double` rather than `double`.
The latter change is essential to accurately measure relative errors between
high precision calculations (using NTL::RR) and fixed precision calculations
(using `long double`).  These occur if, for example, you are generating additional
__lanczos's or rational approximations.

You will also need to include NTL via the header `<boost/math/tools/ntl.hpp>`
and include that header /before/ you include any of the special function headers.
Rationale: the header `<boost/math/tools/ntl.hpp>` includes some traits classes
and boilerplate code (mostly runtime substitutes for numeric_limits) that are
required by the special functions.  Unfortunately, some of the stricter compilers
require these definitions to be seen before the templates that will use them are
parsed.

Finally there is a high precision __lanczos suitable for use with NTL::RR,
used at 1000-bit precision in libs/math/tools/ntl_rr_lanczos.hpp.  The approximation
has a theoretical precision of > 90 decimal digits, and an experimental precision 
of > 100 decimal digits.  To use that approximation, just include that header before
any of the special function headers (if you don't use it, you'll get a slower, but
fully generic implementation for all of the gamma-like functions).

[endsect][/section:use_NTL Using With NTL - a High Precision Floating-Point Library]

[section:real_concept Conceptual Requirements]

std_real_concept is an archetype for built-in Real types.

The main purpose in providing this type is to verify
that std lib 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.

If ::pow is found rather than std::pow say, then the code
will silently compile, but truncation of long doubles to
double will cause a significant loss of precision.
A template instantiated with std_real_concept will *only*
compile if it std::whatever is in scope.

real_concept is an archetype for User defined Real types.

This file defines the features, constructors, operators, functions...
that are essential to use mathematical and statistical functions.
The template typename "RealType" is used where this type
(as well as the normal built-in types, float, double & long double)
can be used.
That this is the minimum set is confirmed by use as a type
in tests of all functions & distributions, for example:
  test_spots(0.F); & test_spots(0.);  for float and double, but also
  test_spots(boost::math::concepts::real_concept(0.));
  
NTL quad_float type is an example of a type meeting the requirements,
but note minor additions are needed - see ntl.diff and documentation
"Using With NTL - a High-Precision Floating-Point Library".

TODO.

See boost/math/concepts/real_concept.hpp for the current concept-archetype
test case.

real_concept basically requires:

* The usual arithmetic operations.
* The usual comparison operations.
* The usual math functions (those in <cmath>).
* Either `std::numeric_limits` support (the easy way), or a small number
helper functions that provide the same functionality at runtime
rather than compile time (see boost/math/tools/precision.hpp).
* Promotion from the built-in floating point types to T, and the function 
`real_cast` that converts from T to a narrower floating-point type
(see boost/math/tools/real_cast.hpp).

For efficient and accurate results, a __lanczos is also highly desirable.
You may be able to adapt an existing approximation from 
boost/math/special_functions/lanczos.hpp: 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 
libs/math/tools/lanczos_generator.cpp to find a suitable
approximation for your type T.

[warning
1  Real concept type T assumes that the number of significand bits
is the same as long double,
*unless* std::numeric_limits<T>::is_specialized
to provide std::numeric_limits<T>::digits.\n
2  If std::numeric_limits<T> is *NOT specialized* to provide std::numeric_limits<T>::digits
(or in future max_digits10) then the default float precision of 6 decimal digits
will be used by other Boost programs including:\n
* Boost.test giving misleading error messages like\n
"difference between {9.79796} and {9.79796} exceeds 5.42101e-19%".\n
* Boost.lexical cast to decimal digit string types\n
and Boost.serialization output causing potentially serious loss of accuracy.\n
Although it might seem the real_concept would best require std::numeric_limits
to be specialized for all types to provide digits, this is not sensible for
NTL::RR and similar classes where the number of digits is a runtime 
parameter (for numeric_limits it has to be fixed at compile time).
(One could still define digits, digits10, epsilon etc to be suitable values,
but one would have to ensure that the precision chosen at runtime,
for example, using the NTL function NTL::setprecision(40), matched
that chosen at compile time by these definitions,
for example, std::numeric_limits<RR>::digits10 = 40;).\n
To mitigate the problems caused by lack of full numeric_limits specialization,
boost::math::tools:: provides some compile time asserts which will alert
the user by failure to compile unless
both numeric_limits<T>::is_specilized and numeric_limits<T>::digits.
]


[endsect][/section:real_concept Conceptual Requirements]


[section:concept_check Concept Checking]

The test program is distribution_concept_check.cpp 
The concept checks and archetypes
(see the Boost Concept Check lib for more info)
are in boost/math/concepts/distributions.hpp.

Implementations of distributions require them to be:

CopyConstructible and Assignable.

All support the following non-member accessor functions

pdf
cdf
quantile
mean
mode
standard_deviation
variance
hazard
chf
coefficient_of_variation
skewness
kurtosis
kurtosis_excess

Their existence (but not proper function) is 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 no need for any code 
changes.  Likewise hazard/chf/coefficient_of_variation are implemented in 
there too.

[endsect][/section:concept_check Concept Checking]

[/ 
  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).
]