concepts.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

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
[@../../../tools/ntl_rr_lanczos.hpp libs/math/tools/ntl_rr_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 
[@../../../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).
]