policy.qbk

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

   double m1 = mean(cauchy()); 
   
   // This will compile, but raises a domain error!
   double m2 = mean(cauchy_distribution<double, policy<assert_undefined<false> > >());
 
[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.

   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 ['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-hock 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