bump version to 12.2.2-pve1

[ceph.git] / ceph / src / boost / libs / math / doc / policies / policy.qbk

[mathpart policy Policies: Controlling Precision, Error Handling etc]

[section:pol_overview Policy Overview]
[policy_overview]
[endsect] [/section:pol_overview Policy Overview]

[include policy_tutorial.qbk]

[section:pol_ref Policy Reference]

[section:error_handling_policies Error Handling Policies]

There are two orthogonal aspects to error handling:

* What to do (if anything) with the error.
* What kind of error is being raised.

[h4 Available Actions When an Error is Raised]

What to do with the error is encapsulated by an enumerated type:

   namespace boost { namespace math { namespace policies {
   
   enum error_policy_type
   {
      throw_on_error = 0, // throw an exception.
      errno_on_error = 1, // set ::errno & return 0, NaN, infinity or best guess.
      ignore_error = 2, // return 0, NaN, infinity or best guess.
      user_error = 3  // call a user-defined error handler.
   };

   }}} // namespaces
   
The various enumerated values have the following meanings:

[h5 throw_on_error]

Will throw one of the following exceptions, depending upon the
 type of the error:
    [table
       [[Error Type][Exception]]
       [[Domain Error][std::domain_error]]
       [[Pole Error][std::domain_error]]
       [[Overflow Error][std::overflow_error]]
       [[Underflow Error][std::underflow_error]]
       [[Denorm Error][std::underflow_error]]
       [[Evaluation Error][boost::math::evaluation_error]]
       [[Indeterminate Result Error][std::domain_error]]
    ]

[h5 errno_on_error]

Will set global __errno `::errno` to one of the following values depending 
upon the error type (often EDOM = 33 and ERANGE = 34),
and then return the same value as if the error
had been ignored:
 [table
    [[Error Type][errno value]]
    [[Domain Error][EDOM]]
    [[Pole Error][EDOM]]
    [[Overflow Error][ERANGE]]
    [[Underflow Error][ERANGE]]
    [[Denorm Error][ERANGE]]
    [[Evaluation Error][EDOM]]
    [[Indeterminate Result Error][EDOM]]
 ]

[h5 ignore_error]

Will return one of the values below depending on the error type (`::errno` is NOT changed)::
 [table
    [[Error Type][Returned Value]]
    [[Domain Error][std::numeric_limits<T>::quiet_NaN()]]
    [[Pole Error][std::numeric_limits<T>::quiet_NaN()]]
    [[Overflow Error][std::numeric_limits<T>::infinity()]]
    [[Underflow Error][0]]
    [[Denorm Error][The denormalised value.]]
    [[Evaluation Error][The best guess (perhaps NaN) as to the result: which
          may be significantly in error.]]
    [[Indeterminate Result Error][Depends on the function where the error occurred]]
 ]

[h5 user_error]

Will call a user defined error handler: these are forward declared
in boost/math/policies/error_handling.hpp, but the actual definitions
must be provided by the user:

   namespace boost{ namespace math{ namespace policies{

   template <class T>
   T user_domain_error(const char* function, const char* message, const T& val);

   template <class T>
   T user_pole_error(const char* function, const char* message, const T& val);

   template <class T>
   T user_overflow_error(const char* function, const char* message, const T& val);

   template <class T>
   T user_underflow_error(const char* function, const char* message, const T& val);

   template <class T>
   T user_denorm_error(const char* function, const char* message, const T& val);

   template <class T>
   T user_rounding_error(const char* function, const char* message, const T& val);

   template <class T>
   T user_evaluation_error(const char* function, const char* message, const T& val);

   template <class T>
   T user_indeterminate_result_error(const char* function, const char* message, const T& val);

   }}} // namespaces

Note that the strings ['function] and ['message] may contain "%1%" format specifiers
designed to be used in conjunction with Boost.Format.  
If these strings are to be presented to the program's end-user then 
the "%1%" format specifier
should be replaced with the name of type T in the ['function] string, and 
if there is a %1% specifier in the ['message] string then it 
should be replaced with the value of ['val].

There is more information on user-defined error handlers in
the [link math_toolkit.pol_tutorial.user_def_err_pol 
tutorial here].

[h4 Kinds of Error Raised]                  

There are six kinds of error reported by this library,
which are summarised in the following table:

[table
[[Error Type]
   [Policy Class]
      [Description]]
[[Domain Error]
   [boost::math::policies::domain_error<['action]>]
      [Raised when more or more arguments are outside the 
      defined range of the function.

      Defaults to `boost::math::policies::domain_error<throw_on_error>`

      When the action is set to ['throw_on_error] 
      then throws `std::domain_error`]]
[[Pole Error]
   [boost::math::policies::pole_error<['action]>]
      [Raised when more or more arguments would cause the function
      to be evaluated at a pole.

      Defaults to `boost::math::policies::pole_error<throw_on_error>`

      When the action is ['throw_on_error] then
      throw a `std::domain_error`]]
[[Overflow Error]
   [boost::math::policies::overflow_error<['action]>]
      [Raised when the result of the function is outside
      the representable range of the floating point type used.

      Defaults to `boost::math::policies::overflow_error<throw_on_error>`.

      When the action is ['throw_on_error] then throws a `std::overflow_error`.]]
[[Underflow Error]
   [boost::math::policies::underflow_error<['action]>]
      [Raised when the result of the function is too small
      to be represented in the floating point type used.

      Defaults to `boost::math::policies::underflow_error<ignore_error>`

      When the specified action is ['throw_on_error] then
      throws a `std::underflow_error`]]
[[Denorm Error]
   [boost::math::policies::denorm_error<['action]>]
      [Raised when the result of the function is a
      denormalised value.

      Defaults to `boost::math::policies::denorm_error<ignore_error>`

      When the action is ['throw_on_error] then throws a `std::underflow_error`]]
[[Rounding Error]
   [boost::math::policies::rounding_error<['action]>]
      [Raised When one of the rounding functions __round, __trunc or __modf is
      called with an argument that has no integer representation, or
      is too large to be represented in the result type

      Defaults to `boost::math::policies::rounding_error<throw_on_error>`

      When the action is ['throw_on_error] then throws `boost::math::rounding_error`]]
[[Evaluation Error]
   [boost::math::policies::evaluation_error<['action]>]
      [Raised when the result of the function is well defined and
      finite, but we were unable to compute it.  Typically
      this occurs when an iterative method fails to converge.
      Of course ideally this error should never be raised: feel free
      to report it as a bug if it is!

      Defaults to `boost::math::policies::evaluation_error<throw_on_error>`

      When the action is ['throw_on_error] then throws `boost::math::evaluation_error`]]
[[Indeterminate Result Error]
   [boost::math::policies::indeterminate_result_error<['action]>]
      [Raised when the result of a function is not defined for the values that
      were passed to it.

      Defaults to `boost::math::policies::indeterminate_result_error<ignore_error>`

      When the action is ['throw_on_error] then throws `std::domain_error`]]
]

[h4 Examples]

Suppose we want a call to `tgamma` to behave in a C-compatible way and set global
`::errno` rather than throw an exception, we can achieve this at the call site
using:

[import ../../example/policy_ref_snip1.cpp]

[policy_ref_snip1]
   
Suppose we want a statistical distribution to return infinities,
rather than throw exceptions, then we can use:

[import ../../example/policy_ref_snip2.cpp]

[policy_ref_snip2]

[endsect] [/section:error_handling_policies Error Handling Policies]

[section:internal_promotion Internal Floating-point Promotion Policies]

Normally when evaluating a function at say `float` precision, maximal
accuracy is assured by conducting the calculation at `double` precision
internally, and then rounding the result.  There are two policies that
control whether internal promotion to a higher precision floating-point type takes place, or not:

[table
[[Policy][Meaning]]
[[`boost::math::policies::promote_float<B>`]
   [Indicates whether `float` arguments should be promoted to `double`
   precision internally: defaults to `boost::math::policies::promote_float<true>`]]
[[`boost::math::policies::promote_double<B>`]
   [Indicates whether `double` arguments should be promoted to `long double`
   precision internally: defaults to `boost::math::policies::promote_double<true>`]]
]

[h4 Examples]

Suppose we want `tgamma` to be evaluated without internal promotion to
`long double`, then we could use:

[import ../../example/policy_ref_snip3.cpp]
[policy_ref_snip3]
   
Alternatively, suppose we want a distribution to perform calculations
without promoting `float` to `double`, then we could use:

[import ../../example/policy_ref_snip4.cpp]
[policy_ref_snip4]
   
[endsect] [/section:internal_promotion Internal Promotion Policies]

[section:assert_undefined Mathematically Undefined Function Policies]

There are some functions that are generic
(they are present for all the statistical distributions supported)
but which may be mathematically undefined for certain distributions, but defined for others.

For example, the Cauchy distribution does not have a meaningful mean,
so what should

   mean(cauchy<>());
   
return, and should such an expression even compile at all?

The default behaviour is for all such functions to not compile at all
 - in fact they will raise a 
[@http://www.boost.org/libs/static_assert/index.html static assertion]
 - but by changing the policy
we can have them return the result of a domain error instead
(which may well throw an exception, depending on the error handling policy). 

This behaviour is controlled by the `assert_undefined<>` policy:

   namespace boost{ namespace math{ namespace policies {

   template <bool b>
   class assert_undefined;

   }}} //namespaces

For example:

   #include <boost/math/distributions/cauchy.hpp>
   
   using namespace boost::math::policies;
   using namespace boost::math;
   
   // This will not compile, cauchy has no mean!
   double m1 = mean(cauchy()); 
   
   // This will compile, but raises a domain error!
   double m2 = mean(cauchy_distribution<double, policy<assert_undefined<false> > >());

`policy<assert_undefined<false>` behaviour can also be obtained by defining the macro

  #define BOOST_MATH_ASSERT_UNDEFINED_POLICY false
  
at the head of the file - see __policy_macros. 
 
[endsect][/section:assert_undefined Mathematically Undefined Function Policies]

[section:discrete_quant_ref Discrete Quantile Policies]

If a statistical distribution is ['discrete] then the random variable
can only have integer values - this leaves us with a problem when calculating
quantiles - we can either ignore the discreteness of the distribution and return
a real value, or we can round to an integer.  As it happens, computing integer
values can be substantially faster than calculating a real value, so there are
definite advantages to returning an integer, but we do then need to decide
how best to round the result.  The `discrete_quantile` policy defines how
discrete quantiles work, and how integer results are rounded:

   enum discrete_quantile_policy_type
   {
      real,
      integer_round_outwards, // default
      integer_round_inwards,
      integer_round_down,
      integer_round_up,
      integer_round_nearest
   };
   
   template <discrete_quantile_policy_type>
   struct discrete_quantile;
   
The values that `discrete_quantile` can take have the following meanings:

[h5 real]

Ignores the discreteness of the distribution, and returns a real-valued 
result.  For example:

[import ../../example/policy_ref_snip5.cpp]
[policy_ref_snip5]
   
Results in `x = 27.3898` and `y = 68.1584`.

[h5 integer_round_outwards]

This is the default policy: an integer value is returned so that:

* Lower quantiles (where the probability is less than 0.5) are rounded
down.
* Upper quantiles (where the probability is greater than 0.5) are rounded up.

This is normally the safest rounding policy, since it ensures that both
one and two sided intervals are guaranteed to have ['at least] 
the requested coverage.  For example:

[import ../../example/policy_ref_snip6.cpp]
[policy_ref_snip6]
   
Results in `x = 27` (rounded down from 27.3898) and `y = 69` (rounded up from 68.1584).

The variables x and y are now defined so that:

   cdf(negative_binomial(20), x) <= 0.05
   cdf(negative_binomial(20), y) >= 0.95
   
In other words we guarantee ['at least 90% coverage in the central region overall], 
and also ['no more than 5% coverage in each tail].

[h5 integer_round_inwards]

This is the opposite of ['integer_round_outwards]: an integer value is returned so that:

* Lower quantiles (where the probability is less than 0.5) are rounded
['up].
* Upper quantiles (where the probability is greater than 0.5) are rounded ['down].

For example:

[import ../../example/policy_ref_snip7.cpp]

[policy_ref_snip7]
   
Results in `x = 28` (rounded up from 27.3898) and `y = 68` (rounded down from 68.1584).

The variables x and y are now defined so that:

   cdf(negative_binomial(20), x) >= 0.05
   cdf(negative_binomial(20), y) <= 0.95
   
In other words we guarantee ['at no more than 90% coverage in the central region overall], 
and also ['at least 5% coverage in each tail].

[h5 integer_round_down]

Always rounds down to an integer value, no matter whether it's an upper 
or a lower quantile.

[h5 integer_round_up]

Always rounds up to an integer value, no matter whether it's an upper 
or a lower quantile.

[h5 integer_round_nearest]

Always rounds to the nearest integer value, no matter whether it's an upper 
or a lower quantile.  This will produce the requested coverage
['in the average case], but for any specific example may results in
either significantly more or less coverage than the requested amount.
For example:

For example:

[import ../../example/policy_ref_snip8.cpp]

[policy_ref_snip8]

Results in `x = 27` (rounded from 27.3898) and `y = 68` (rounded from 68.1584).

[endsect][/section:discrete_quant_ref Discrete Quantile Policies]

[section:precision_pol Precision Policies]

There are two equivalent policies that effect the ['working precision]
used to calculate results, these policies both default to 0 - meaning
calculate to the maximum precision available in the type being used
 - but can be set to other values to cause lower levels of precision 
to be used. One might want to trade precision for evaluation speed.

   namespace boost{ namespace math{ namespace policies{
   
   template <int N>
   digits10;
   
   template <int N>
   digits2;
   
   }}} // namespaces
   
As you would expect, ['digits10] specifies the number of decimal digits
to use, and ['digits2] the number of binary digits.  Internally, whichever
is used, the precision is always converted to ['binary digits].

These policies are specified at compile-time, because many of the special
functions use compile-time-dispatch to select which approximation to use
based on the precision requested and the numeric type being used.

For example we could calculate `tgamma` to approximately 5 decimal digits using:

[import ../../example/policy_ref_snip9.cpp]

[policy_ref_snip9]
   
Or again using helper function `make_policy`:

[import ../../example/policy_ref_snip10.cpp]

[policy_ref_snip10]

And for a quantile of a distribution to approximately 25-bit precision:

[import ../../example/policy_ref_snip11.cpp]

[policy_ref_snip11]

[endsect][/section:precision_pol Precision Policies]

[section:iteration_pol Iteration Limits Policies]

There are two policies that effect the iterative algorithms
used to implement the special functions in this library:

   template <unsigned long limit = BOOST_MATH_MAX_SERIES_ITERATION_POLICY>
   class max_series_iterations;
   
   template <unsigned long limit = BOOST_MATH_MAX_ROOT_ITERATION_POLICY>
   class max_root_iterations;

The class `max_series_iterations` determines the maximum number of
iterations permitted in a series evaluation, before the special
function gives up and returns the result of __evaluation_error.

The class `max_root_iterations` determines the maximum number
of iterations permitted in a root-finding algorithm before the special
function gives up and returns the result of __evaluation_error.

[endsect] [/section:iteration_pol Iteration Limits Policies]

[section:policy_defaults Using Macros to Change the Policy Defaults]

You can use the various macros below to change any (or all) of the policies.

You can make a local change by placing a macro definition *before*
a function or distribution #include.

[caution There is a danger of One-Definition-Rule violations if you 
add ad-hoc macros to more than one source files: these must be set the same in *every 
translation unit*.]

[caution If you place it after the #include it will have no effect,
(and it will affect only any other following #includes).
This is probably not what you intend!]

If you want to alter the defaults for any or all of 
the policies for *all* functions and distributions, installation-wide,
then you can do so by defining various macros in
[@../../../../boost/math/tools/user.hpp boost/math/tools/user.hpp].

[h5 BOOST_MATH_DOMAIN_ERROR_POLICY]

Defines what happens when a domain error occurs, if not defined then
defaults to `throw_on_error`, but can be set to any of the enumerated
actions for error handing: `throw_on_error`, `errno_on_error`, 
`ignore_error` or `user_error`.

[h5 BOOST_MATH_POLE_ERROR_POLICY]

Defines what happens when a pole error occurs, if not defined then
defaults to `throw_on_error`, but can be set to any of the enumerated
actions for error handing: `throw_on_error`, `errno_on_error`, 
`ignore_error` or `user_error`.

[h5 BOOST_MATH_OVERFLOW_ERROR_POLICY]

Defines what happens when an overflow error occurs, if not defined then
defaults to `throw_on_error`, but can be set to any of the enumerated
actions for error handing: `throw_on_error`, `errno_on_error`, 
`ignore_error` or `user_error`.

[h5 BOOST_MATH_ROUNDING_ERROR_POLICY]

Defines what happens when a rounding error occurs, if not defined then
defaults to `throw_on_error`, but can be set to any of the enumerated
actions for error handing: `throw_on_error`, `errno_on_error`, 
`ignore_error` or `user_error`.

[h5 BOOST_MATH_EVALUATION_ERROR_POLICY]

Defines what happens when an internal evaluation error occurs, if not defined then
defaults to `throw_on_error`, but can be set to any of the enumerated
actions for error handing: `throw_on_error`, `errno_on_error`, 
`ignore_error` or `user_error`.

[h5 BOOST_MATH_UNDERFLOW_ERROR_POLICY]

Defines what happens when an overflow error occurs, if not defined then
defaults to `ignore_error`, but can be set to any of the enumerated
actions for error handing: `throw_on_error`, `errno_on_error`, 
`ignore_error` or `user_error`.

[h5 BOOST_MATH_DENORM_ERROR_POLICY]

Defines what happens when a denormalisation error occurs, if not defined then
defaults to `ignore_error`, but can be set to any of the enumerated
actions for error handing: `throw_on_error`, `errno_on_error`, 
`ignore_error` or `user_error`.

[h5 BOOST_MATH_INDETERMINATE_RESULT_ERROR_POLICY]

Defines what happens when the result is indeterminate, but where there
is none the less a convention for the result.  If not defined then
defaults to `ignore_error`, but can be set to any of the enumerated
actions for error handing: `throw_on_error`, `errno_on_error`, 
`ignore_error` or `user_error`.

[h5 BOOST_MATH_DIGITS10_POLICY]

Defines how many decimal digits to use in internal computations: 
defaults to `0` - meaning use all available digits - but can be set
to some other decimal value.  Since setting this is likely to have
a substantial impact on accuracy, it's not generally recommended
that you change this from the default.

[h5 BOOST_MATH_PROMOTE_FLOAT_POLICY]

Determines whether `float` types get promoted to `double`
internally to ensure maximum precision in the result, defaults
to `true`, but can be set to `false` to turn promotion of
`float`'s off.

[h5 BOOST_MATH_PROMOTE_DOUBLE_POLICY]

Determines whether `double` types get promoted to `long double`
internally to ensure maximum precision in the result, defaults
to `true`, but can be set to `false` to turn promotion of
`double`'s off.

[h5 BOOST_MATH_DISCRETE_QUANTILE_POLICY]

Determines how discrete quantiles return their results: either
as an integer, or as a real value, can be set to one of the
enumerated values: `real`, `integer_round_outwards`, `integer_round_inwards`,
`integer_round_down`, `integer_round_up`, `integer_round_nearest`.  Defaults to
`integer_round_outwards`.

[h5 BOOST_MATH_ASSERT_UNDEFINED_POLICY]

Determines whether functions that are mathematically undefined
for a specific distribution compile or raise a static (i.e. compile-time)
assertion.  Defaults to `true`: meaning that any mathematically
undefined function will not compile.  When set to `false` then the function
will compile but return the result of a domain error: this can be useful
for some generic code, that needs to work with all distributions and determine
at runtime whether or not a particular property is well defined.

[h5 BOOST_MATH_MAX_SERIES_ITERATION_POLICY]

Determines how many series iterations a special function is permitted
to perform before it gives up and returns an __evaluation_error:
Defaults to 1000000.
   
[h5 BOOST_MATH_MAX_ROOT_ITERATION_POLICY]

Determines how many root-finding iterations a special function is permitted
to perform before it gives up and returns an __evaluation_error:
Defaults to 200.

[h5 Example]

Suppose we want overflow errors to set `::errno` and return an infinity,
discrete quantiles to return a real-valued result (rather than round to
integer), and for mathematically undefined functions to compile, but return
a domain error. Then we could add the following to boost/math/tools/user.hpp:

   #define BOOST_MATH_OVERFLOW_ERROR_POLICY errno_on_error
   #define BOOST_MATH_DISCRETE_QUANTILE_POLICY real
   #define BOOST_MATH_ASSERT_UNDEFINED_POLICY false
   
or we could place these definitions *before*

   #include <boost/math/distributions/normal.hpp>
     using boost::math::normal_distribution;

in a source .cpp file.

[endsect][/section:policy_defaults Changing the Policy Defaults]

[section:namespace_pol Setting Polices at Namespace Scope]

Sometimes what you really want to do is bring all the special functions,
or all the distributions into a specific namespace-scope, along with
a specific policy to use with them.  There are two macros defined to
assist with that:

   BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS(Policy)

and:

   BOOST_MATH_DECLARE_DISTRIBUTIONS(Type, Policy)
   
You can use either of these macros after including any special function
or distribution header.  For example:

[import ../../example/policy_ref_snip12.cpp]

[policy_ref_snip12]

In this example, using BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS results in
a set of thin inline forwarding functions being defined:

   template <class T>
   inline T tgamma(T a){ return ::boost::math::tgamma(a, mypolicy()); }
   
   template <class T>
   inline T lgamma(T a) ( return ::boost::math::lgamma(a, mypolicy()); }
   
and so on.  Note that while a forwarding function is defined for all the special
functions, however, unless you include the specific header for the special
function you use (or boost/math/special_functions.hpp to include everything), 
you will get linker errors from functions that are forward declared, but not
defined.

We can do the same thing with the distributions, but this time we need to
specify the floating-point type to use:

[import ../../example/policy_ref_snip13.cpp]

[policy_ref_snip13]
   
In this example the result of BOOST_MATH_DECLARE_DISTRIBUTIONS is to
declare a typedef for each distribution like this:

   typedef boost::math::cauchy_distribution<double, my_policy> cauchy;
   tyepdef boost::math::gamma_distribution<double, my_policy> gamma;
   
and so on.  The name given to each typedef is the name of the distribution
with the "_distribution" suffix removed.

[endsect][/section Changing the Policy Defaults]

[section:pol_ref_ref Policy Class Reference]

There's very little to say here, the `policy` class is just a rag-bag
compile-time container for a collection of policies:

```#include <boost/math/policies/policy.hpp>```


   namespace boost{
   namespace math{
   namespace policies
   
   template <class A1 = default_policy, 
             class A2 = default_policy, 
             class A3 = default_policy,
             class A4 = default_policy,
             class A5 = default_policy,
             class A6 = default_policy,
             class A7 = default_policy,
             class A8 = default_policy,
             class A9 = default_policy,
             class A10 = default_policy,
             class A11 = default_policy,
             class A12 = default_policy,
             class A13 = default_policy>
   struct policy
   {
   public:
      typedef ``['computed-from-template-arguments]`` domain_error_type;
      typedef ``['computed-from-template-arguments]`` pole_error_type;
      typedef ``['computed-from-template-arguments]`` overflow_error_type;
      typedef ``['computed-from-template-arguments]`` underflow_error_type;
      typedef ``['computed-from-template-arguments]`` denorm_error_type;
      typedef ``['computed-from-template-arguments]`` rounding_error_type;
      typedef ``['computed-from-template-arguments]`` evaluation_error_type;
      typedef ``['computed-from-template-arguments]`` indeterminate_result_error_type;
      typedef ``['computed-from-template-arguments]`` precision_type;
      typedef ``['computed-from-template-arguments]`` promote_float_type;
      typedef ``['computed-from-template-arguments]`` promote_double_type;
      typedef ``['computed-from-template-arguments]`` discrete_quantile_type;
      typedef ``['computed-from-template-arguments]`` assert_undefined_type;
   };

   template <...argument list...>
   typename normalise<policy<>, A1>::type make_policy(...argument list..);

   template <class Policy, 
             class A1 = default_policy, 
             class A2 = default_policy, 
             class A3 = default_policy,
             class A4 = default_policy,
             class A5 = default_policy,
             class A6 = default_policy,
             class A7 = default_policy,
             class A8 = default_policy,
             class A9 = default_policy,
             class A10 = default_policy,
             class A11 = default_policy,
             class A12 = default_policy,
             class A13 = default_policy>
   struct normalise
   {
      typedef ``computed-from-template-arguments`` type;
   };

The member typedefs of class `policy` are intended for internal use
but are documented briefly here for the sake of completeness.

   policy<...>::domain_error_type
   
Specifies how domain errors are handled, will be an instance of
`boost::math::policies::domain_error<>` with the template argument to
`domain_error` one of the `error_policy_type` enumerated values.

   policy<...>::pole_error_type
   
Specifies how pole-errors are handled, will be an instance of
`boost::math::policies::pole_error<>` with the template argument to
`pole_error` one of the `error_policy_type` enumerated values.

   policy<...>::overflow_error_type
   
Specifies how overflow errors are handled, will be an instance of
`boost::math::policies::overflow_error<>` with the template argument to
`overflow_error` one of the `error_policy_type` enumerated values.

   policy<...>::underflow_error_type
   
Specifies how underflow errors are handled, will be an instance of
`boost::math::policies::underflow_error<>` with the template argument to
`underflow_error` one of the `error_policy_type` enumerated values.

   policy<...>::denorm_error_type
   
Specifies how denorm errors are handled, will be an instance of
`boost::math::policies::denorm_error<>` with the template argument to
`denorm_error` one of the `error_policy_type` enumerated values.

   policy<...>::rounding_error_type
   
Specifies how rounding errors are handled, will be an instance of
`boost::math::policies::rounding_error<>` with the template argument to
`rounding_error` one of the `error_policy_type` enumerated values.

   policy<...>::evaluation_error_type
   
Specifies how evaluation errors are handled, will be an instance of
`boost::math::policies::evaluation_error<>` with the template argument to
`evaluation_error` one of the `error_policy_type` enumerated values.

   policy<...>::indeterminate_error_type

Specifies how indeterminate result errors are handled, will be an instance of
`boost::math::policies::indeterminate_result_error<>` with the template argument
to `indeterminate_result_error` one of the `error_policy_type` enumerated
values.

   policy<...>::precision_type
   
Specifies the internal precision to use in binary digits (uses zero
to represent whatever the default precision is).  Will be an instance
of `boost::math::policies::digits2<N>` which in turn inherits from 
`boost::mpl::int_<N>`.

   policy<...>::promote_float_type
   
Specifies whether or not to promote `float` arguments to `double` precision
internally.  Will be an instance of `boost::math::policies::promote_float<B>`
which in turn inherits from `boost::mpl::bool_<B>`.

   policy<...>::promote_double_type
   
Specifies whether or not to promote `double` arguments to `long double` precision
internally.  Will be an instance of `boost::math::policies::promote_float<B>`
which in turn inherits from `boost::mpl::bool_<B>`.

   policy<...>::discrete_quantile_type
   
Specifies how discrete quantiles are evaluated, will be an instance
of `boost::math::policies::discrete_quantile<>` instantiated with one of
the `discrete_quantile_policy_type` enumerated type.

   policy<...>::assert_undefined_type
   
Specifies whether mathematically-undefined properties are
asserted as compile-time errors, or treated as runtime errors
instead.  Will be an instance of `boost::math::policies::assert_undefined<B>`
which in turn inherits from `boost::math::mpl::bool_<B>`.


   template <...argument list...>
   typename normalise<policy<>, A1>::type make_policy(...argument list..);

`make_policy` is a helper function that converts a list of policies into
a normalised `policy` class.

   template <class Policy, 
             class A1 = default_policy, 
             class A2 = default_policy, 
             class A3 = default_policy,
             class A4 = default_policy,
             class A5 = default_policy,
             class A6 = default_policy,
             class A7 = default_policy,
             class A8 = default_policy,
             class A9 = default_policy,
             class A10 = default_policy,
             class A11 = default_policy,
             class A12 = default_policy,
             class A13 = default_policy>
   struct normalise
   {
      typedef ``computed-from-template-arguments`` type;
   };
   
The `normalise` class template converts one instantiation of the
`policy` class into a normalised form.  This is used internally
to reduce code bloat: so that instantiating a special function
on `policy<A,B>` or `policy<B,A>` actually both generate the same
code internally.  

Further more, `normalise` can be used to combine
a policy with one or more policies: for example many of the
special functions will use this to set policies which they don't
make use of to their default values, before forwarding to the actual
implementation.  In this way code bloat is reduced, since the
actual implementation depends only on the policy types that they
actually use.

[endsect][/section:pol_ref_ref Policy Class Reference]

[endsect][/section:pol_ref Policy Reference]
[endmathpart][/section:policy Policies]

[/ qbk
  Copyright 2007, 2010 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).
]