|
|
Boost-Commit : |
From: johnmaddock_at_[hidden]
Date: 2007-07-20 13:49:06
Author: johnmaddock
Date: 2007-07-20 13:49:05 EDT (Fri, 20 Jul 2007)
New Revision: 7494
URL: http://svn.boost.org/trac/boost/changeset/7494
Log:
Updated NTL::RR support to new policy framework.
Added first policy docs.
Added:
sandbox/math_toolkit/policy/libs/math/doc/policy.qbk
Text files modified:
sandbox/math_toolkit/policy/boost/math/tools/ntl.hpp | 56 ++++++++++++++++-----------------------
sandbox/math_toolkit/policy/libs/math/doc/distributions/binomial.qbk | 8 ++--
sandbox/math_toolkit/policy/libs/math/doc/math.qbk | 2 +
sandbox/math_toolkit/policy/libs/math/tools/ntl_rr_lanczos.hpp | 13 ++++-----
4 files changed, 35 insertions(+), 44 deletions(-)
Modified: sandbox/math_toolkit/policy/boost/math/tools/ntl.hpp
==============================================================================
--- sandbox/math_toolkit/policy/boost/math/tools/ntl.hpp (original)
+++ sandbox/math_toolkit/policy/boost/math/tools/ntl.hpp 2007-07-20 13:49:05 EDT (Fri, 20 Jul 2007)
@@ -60,7 +60,25 @@
} // namespace NTL
-namespace boost{ namespace math{ namespace tools{
+namespace boost{ namespace math{
+
+namespace policy{
+
+template<>
+inline int digits<NTL::RR, boost::math::policy::policy<> >(BOOST_EXPLICIT_TEMPLATE_TYPE_SPEC(NTL::RR))
+{
+ return NTL::RR::precision();
+}
+
+template<>
+inline int digits<NTL::RR, boost::math::policy::policy<boost::math::policy::detail::forwarding_arg1, boost::math::policy::detail::forwarding_arg2> >(BOOST_EXPLICIT_TEMPLATE_TYPE_SPEC(NTL::RR))
+{
+ return NTL::RR::precision();
+}
+
+}
+
+namespace tools{
template <>
inline float real_cast<float, NTL::RR>(NTL::RR t)
@@ -106,12 +124,6 @@
return static_cast<int>(real_cast<long double>(t));;
}
-template<>
-inline int digits<NTL::RR>(BOOST_EXPLICIT_TEMPLATE_TYPE_SPEC(NTL::RR))
-{
- return NTL::RR::precision();
-}
-
template <>
inline NTL::RR max_value<NTL::RR>(BOOST_EXPLICIT_TEMPLATE_TYPE_SPEC(NTL::RR))
{
@@ -173,27 +185,11 @@
template <>
inline NTL::RR epsilon<NTL::RR>(BOOST_EXPLICIT_TEMPLATE_TYPE_SPEC(NTL::RR))
{
- return ldexp(NTL::RR(1), 1-digits<NTL::RR>());
+ return ldexp(NTL::RR(1), 1-boost::math::policy::digits<NTL::RR, boost::math::policy::policy<> >());
}
} // namespace tools
-namespace policy{
-
-template<>
-inline int digits<NTL::RR, boost::math::policy::policy<> >(BOOST_EXPLICIT_TEMPLATE_TYPE_SPEC(NTL::RR))
-{
- return NTL::RR::precision();
-}
-
-template<>
-inline int digits<NTL::RR, boost::math::policy::policy<boost::math::policy::detail::forwarding_arg1, boost::math::policy::detail::forwarding_arg2> >(BOOST_EXPLICIT_TEMPLATE_TYPE_SPEC(NTL::RR))
-{
- return NTL::RR::precision();
-}
-
-}
-
//
// The number of digits precision in RR can vary with each call
// so we need to recalculate these with each call:
@@ -246,12 +242,6 @@
return to_quad_float(t);
}
-template<>
-inline int digits<NTL::quad_float>(BOOST_EXPLICIT_TEMPLATE_TYPE_SPEC(NTL::quad_float))
-{
- return 106;
-}
-
template <>
inline NTL::quad_float max_value<NTL::quad_float>(BOOST_EXPLICIT_TEMPLATE_TYPE_SPEC(NTL::quad_float))
{
@@ -314,7 +304,7 @@
NTL::RR(std::asin(boost::math::tools::real_cast<double>(z))),
NTL::RR(-boost::math::constants::pi<NTL::RR>()/2),
NTL::RR(boost::math::constants::pi<NTL::RR>()/2),
- boost::math::policy::digits<NTL::RR, policy::policy<> >());
+ boost::math::policy::digits<NTL::RR, boost::math::policy::policy<> >());
}
struct acos_root
@@ -340,7 +330,7 @@
NTL::RR(std::acos(boost::math::tools::real_cast<double>(z))),
NTL::RR(-boost::math::constants::pi<NTL::RR>()/2),
NTL::RR(boost::math::constants::pi<NTL::RR>()/2),
- boost::math::policy::digits<NTL::RR, policy::policy<> >());
+ boost::math::policy::digits<NTL::RR, boost::math::policy::policy<> >());
}
struct atan_root
@@ -367,7 +357,7 @@
NTL::RR(std::atan(boost::math::tools::real_cast<double>(z))),
-boost::math::constants::pi<NTL::RR>()/2,
boost::math::constants::pi<NTL::RR>()/2,
- boost::math::policy::digits<NTL::RR, policy::policy<> >());
+ boost::math::policy::digits<NTL::RR, boost::math::policy::policy<> >());
}
inline NTL::RR sinh(NTL::RR z)
Modified: sandbox/math_toolkit/policy/libs/math/doc/distributions/binomial.qbk
==============================================================================
--- sandbox/math_toolkit/policy/libs/math/doc/distributions/binomial.qbk (original)
+++ sandbox/math_toolkit/policy/libs/math/doc/distributions/binomial.qbk 2007-07-20 13:49:05 EDT (Fri, 20 Jul 2007)
@@ -302,22 +302,22 @@
[[__ccdf]
[The probability of obtaining [*more than k successes] from n trials
with success fraction p. For example:
-
+
`cdf(complement(binomial(n, p), k))`]]
[[__quantile]
[The [*greatest] number of successes that may be observed from n trials
with success fraction p, at probability P. Note that the value returned
is a real-number, and not an integer. Depending on the use case you may
want to take either the floor or ceiling of the result. For example:
-
-
+
`quantile(binomial(n, p), P)`]]
[[__quantile_c]
[The [*smallest] number of successes that may be observed from n trials
with success fraction p, at probability P. Note that the value returned
is a real-number, and not an integer. Depending on the use case you may
want to take either the floor or ceiling of the result. For example:
- ``quantile(complement(binomial(n, p), P))``]]
+
+`quantile(complement(binomial(n, p), P))``]]
]
[h4 Examples]
Modified: sandbox/math_toolkit/policy/libs/math/doc/math.qbk
==============================================================================
--- sandbox/math_toolkit/policy/libs/math/doc/math.qbk (original)
+++ sandbox/math_toolkit/policy/libs/math/doc/math.qbk 2007-07-20 13:49:05 EDT (Fri, 20 Jul 2007)
@@ -353,6 +353,8 @@
[include concepts.qbk]
[endsect][/section:Using_UDT Use with User Defined Floating-Point Types]
+[include policy.qbk]
+
[section:backgrounders Backgrounders]
[include implementation.qbk]
[include error.qbk][/relative error NOT handling]
Added: sandbox/math_toolkit/policy/libs/math/doc/policy.qbk
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/policy/libs/math/doc/policy.qbk 2007-07-20 13:49:05 EDT (Fri, 20 Jul 2007)
@@ -0,0 +1,717 @@
+
+[section:policy Policies]
+
+Policies are a powerful mechanism that allow you to customise the
+behaviour of this library according to your needs. Policies are a
+compile-time mechanism that allow you to change the behaviour of
+things such as error-handling or calculation precision either
+program wide, or at the call site.
+
+[section:pol_overview Policy Overview and Tutorial]
+
+[endsect]
+
+[section:pol_ref Policy Reference]
+
+[section:pol_ref_ref The Policy Class]
+
+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/policy/policy.hpp>```
+
+
+ namespace boost{
+ namespace math{
+ namespace policy{
+
+ 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>
+ 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]`` evaluation_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>
+ 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::policy::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::policy::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::policy::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::policy::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::policy::denorm_error<>` with the template argument to
+`denorm_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::policy::evaluation_error<>` with the template argument to
+`evaluation_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::policy::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::policy::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::policy::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::policy::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::policy::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>
+ 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.
+
+[endsect]
+
+[section 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 policy{
+
+ enum error_policy_type
+ {
+ throw_on_error = 0,
+ errno_on_error = 1,
+ ignore_error = 2,
+ user_error = 3
+ };
+
+ }}} // 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]]
+ ]
+
+[h5 errno_on_error]
+
+Will set ::errno to one of the following values depending
+upon the error type, 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]]
+ ]
+
+[h5 ignore_error]
+
+Will return a one of the values below depending on the error type:
+ [table
+ [[Error Type][errno 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 as to the result: which
+ may be significantly in error.]]
+ ]
+
+[h5 user_error]
+
+Will call a user defined error handler, these are forward declared
+in boost/math/policy/error_handling.hpp, but the actual definitions
+must be provided by the user:
+
+ 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_evaluation_error(const char* function, const char* message, const T& val);
+
+Note that the strings ['function] and ['message] 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 the
+specifier in the ['message] string should be replaced with the value of ['val].
+
+[h4 Kinds of Error Raised]
+
+There are five kinds of error reported by this library,
+which are summarised in the following table:
+
+[table
+[[Error Type]
+ [Policy Class]
+ [Description]]
+[[Domain Error]
+ [boost::math::policy::domain_error<['action]>]
+ [Raised when more or more arguments are outside the
+ defined range of the function.
+
+ Defaults to `boost::math::policy::domain_error<throw_on_error>`
+
+ When the action is set to ['throw_on_error]
+ then throws `std::domain_error`]]
+[[Pole Error]
+ [boost::math::policy::pole_error<['action]>]
+ [Raised when more or more arguments would cause the function
+ to be evaluated at a pole.
+
+ Defaults to `boost::math::policy::pole_error<throw_on_error>`
+
+ When the action is ['throw_on_error] then
+ throw a `std::domain_error`]]
+[[Overflow Error]
+ [boost::math::policy::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::policy::overflow_error<throw_on_error>`.
+
+ When the action is ['throw_on_error] then throws a `std::overflow_error`.]]
+[[Underflow Error]
+ [boost::math::policy::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::policy::underflow_error<ignore_error>`
+
+ When the specified action is ['throw_on_error] then
+ throws a `std::underflow_error`]]
+[[Denorm Error]
+ [boost::math::policy::denorm_error<['action]>]
+ [Raised when the result of the function is a
+ denormalised value.
+
+ Defaults to `boost::math::policy::denorm_error<ignore_error>`
+
+ When the action is ['throw_on_error] then throws a `std::underflow_error`]]
+[[Evaluation Error]
+ [boost::math::policy::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::policy::evaluation_error<throw_on_error>`
+
+ When the action is ['throw_on_error] then throws `boost::math::evaluation_error`]]
+]
+
+[h4 Examples]
+
+Suppose we want a call to `tgamma` to behave in a C-compatible way and set
+`errno` rather than throw an exception, we can achieve this at the call site
+using:
+
+ #include <boost/math/special_functions/gamma.hpp>
+
+ using namespace boost::math::policy;
+ using namespace boost::math;
+
+ // Define a policy:
+ typedef policy<
+ domain_error<errno_on_error>,
+ pole_error<errno_on_error>,
+ overflow_error<errno_on_error>,
+ evaluation_error<errno_on_error>
+ > my_policy;
+
+ // call the function:
+ double t = tgamma(some_value, my_policy());
+
+ // Alternatively we could use make_policy and define everything at the call site:
+ t = tgamma(some_value, make_policy(
+ domain_error<errno_on_error>(),
+ pole_error<errno_on_error>(),
+ overflow_error<errno_on_error>(),
+ evaluation_error<errno_on_error>()
+ ));
+
+Suppose we want a statistical distribution to return infinities
+rather than throw exceptions, then we can use:
+
+ #include <boost/math/distributions/normal.hpp>
+
+ using namespace boost::math::policy;
+ using namespace boost::math;
+
+ // Define a policy:
+ typedef policy<
+ overflow_error<ignore_error>
+ > my_policy;
+
+ // define the distribution:
+ typedef normal_distribution<double, my_policy> my_norm;
+
+ // get a quantile:
+ double q = quantile(my_norm(), 0.05);
+
+[endsect]
+
+[section:internal_promotion Internal 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
+effect whether internal promotion takes place or not:
+
+[table
+[[Policy][Meaning]]
+[[`boost::math::policy::promote_float<B>`]
+ [Indicates whether `float` arguments should be promoted to `double`
+ precision internally: defaults to `boost::math::policy::promote_float<true>`]]
+[[`boost::math::policy::promote_double<B>`]
+ [Indicates whether `double` arguments should be promoted to `long double`
+ precision internally: defaults to `boost::math::policy::promote_double<true>`]]
+]
+
+[h4 Examples]
+
+Suppose we want `tgamma` to be evaluated without internal promotion to
+`long double`, then we could use:
+
+ #include <boost/math/special_functions/gamma.hpp>
+
+ using namespace boost::math::policy;
+ using namespace boost::math;
+
+ // Define a policy:
+ typedef policy<
+ promote_double<false>
+ > my_policy;
+
+ // call the function:
+ double t = tgamma(some_value, my_policy());
+
+ // Alternatively we could use make_policy and define everything at the call site:
+ t = tgamma(some_value, make_policy(promote_double<false>()));
+
+Alternatively, suppose we want a distribution to perform calculations
+without promoting `float` to `double`, then we could use:
+
+ #include <boost/math/distributions/normal.hpp>
+
+ using namespace boost::math::policy;
+ using namespace boost::math;
+
+ // Define a policy:
+ typedef policy<
+ promote_float<false>
+ > my_policy;
+
+ // define the distribution:
+ typedef normal_distribution<float, my_policy> my_norm;
+
+ // get a quantile:
+ float q = quantile(my_norm(), 0.05f);
+
+[endsect]
+
+[section:assert_undefined Mathematically Undefined Function Policies]
+
+There are some functions that are generic - which is to say they are
+present for all the statistical distributions supported - but which
+may be mathematically undefined for certain distributions, but not others.
+
+For example the Cauchy distribution does not have a 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).
+
+This behaviour is controlled by the `assert_undefined<>` policy:
+
+ namespace boost{ namespace math{ namespace policy{
+
+ template <bool b>
+ class assert_undefined;
+
+ }}} //namespaces
+
+For example:
+
+ #include <boost/math/distributions/cauchy.hpp>
+
+ using namespace boost::math::policy;
+ 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> > >());
+
+[endsect]
+
+[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_outside,
+ integer_inside,
+ integer_below,
+ integer_above,
+ integer_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:
+
+ #include <boost/math/distributions/negative_binomial.hpp>
+
+ using namespace boost::math;
+ using namespace boost::math::policy;
+
+ typedef negative_binomial_distribution<
+ double,
+ policy<discrete_quantile<integer_inside> >
+ > dist_type;
+
+ double x, y;
+
+ // Lower quantile:
+ x = quantile(dist_type(20, 0.3), 0.05);
+ // Upper quantile:
+ y = quantile(complement(dist_type(20, 0.3), 0.05));
+
+Results in `x = 27.3898` and `y = 68.1584`.
+
+[h5 integer_outside]
+
+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:
+
+ #include <boost/math/distributions/negative_binomial.hpp>
+
+ using namespace boost::math;
+
+ double x, y;
+
+ // Lower quantile rounded down:
+ x = quantile(negative_binomial(20), 0.05);
+ // Upper quantile rounded up:
+ y = quantile(complement(negative_binomial(20), 0.05));
+
+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 cenrtal region overall],
+and also ['no more than 5% coverage in each tail].
+
+[h5 integer_inside]
+
+This is the opposite of ['integer_outside]: 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:
+
+ #include <boost/math/distributions/negative_binomial.hpp>
+
+ using namespace boost::math;
+ using namespace boost::math::policy;
+
+ typedef negative_binomial_distribution<
+ double,
+ policy<discrete_quantile<integer_inside> >
+ > dist_type;
+
+ double x, y;
+
+ // Lower quantile rounded up:
+ x = quantile(dist_type(20), 0.05);
+ // Upper quantile rounded down:
+ y = quantile(complement(dist_type(20), 0.05));
+
+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 cenrtal region overall],
+and also ['at least 5% coverage in each tail].
+
+[h5 integer_below]
+
+Always rounds down to an integer value, no matter whether it's an upper
+or a lower quantile.
+
+[h5 integer_above]
+
+Always rounds up to an integer value, no matter whether it's an upper
+or a lower quantile.
+
+[h5 integer_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:
+
+ #include <boost/math/distributions/negative_binomial.hpp>
+
+ using namespace boost::math;
+ using namespace boost::math::policy;
+
+ typedef negative_binomial_distribution<
+ double,
+ policy<discrete_quantile<integer_nearest> >
+ > dist_type;
+
+ double x, y;
+
+ // Lower quantile rounded up:
+ x = quantile(dist_type(20), 0.05);
+ // Upper quantile rounded down:
+ y = quantile(complement(dist_type(20), 0.05));
+
+Results in `x = 27` (rounded from 27.3898) and `y = 68` (rounded from 68.1584).
+
+[endsect]
+
+[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 policy{
+
+ 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:
+
+ #include <boost/math/special_functions/gamma.hpp>
+
+ using namespace boost::math;
+ using namespace boost::math::policy;
+
+ typedef policy<digits10<5> > pol;
+
+ double t = tgamma(12, pol());
+
+Or again using ['make_policy]:
+
+ #include <boost/math/special_functions/gamma.hpp>
+
+ using namespace boost::math;
+ using namespace boost::math::policy;
+
+ double t = tgamma(12, policy<digits10<5> >());
+
+And for a quantile of a distribution to approximately 25-bit precision:
+
+ #include <boost/math/distributions/normal.hpp>
+
+ using namespace boost::math;
+ using namespace boost::math::policy;
+
+ double q = quantile(
+ normal_distribution<double, policy<digits2<25> >(),
+ 0.05);
+
+[endsect]
+
+[endsect]
+
+[endsect]
Modified: sandbox/math_toolkit/policy/libs/math/tools/ntl_rr_lanczos.hpp
==============================================================================
--- sandbox/math_toolkit/policy/libs/math/tools/ntl_rr_lanczos.hpp (original)
+++ sandbox/math_toolkit/policy/libs/math/tools/ntl_rr_lanczos.hpp 2007-07-20 13:49:05 EDT (Fri, 20 Jul 2007)
@@ -881,18 +881,17 @@
namespace boost{ namespace math{ namespace lanczos{
-template<>
-struct lanczos_traits<NTL::RR>
+template<class Policy>
+struct lanczos<NTL::RR, Policy>
{
- typedef NTL::RR value_type;
#ifdef L13
- typedef lanczos13UDT evaluation_type;
+ typedef lanczos13UDT type;
#elif defined(L22)
- typedef lanczos22UDT evaluation_type;
+ typedef lanczos22UDT type;
#elif defined(L31)
- typedef lanczos31UDT evaluation_type;
+ typedef lanczos31UDT type;
#else
- typedef lanczos61UDT evaluation_type;
+ typedef lanczos61UDT type;
#endif
};
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk