policy.qbk

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

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]
[endsect][/section:policy Policies]

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