Subject: [Boost-commit] svn:boost r78805 - trunk/libs/math/doc/sf_and_dist
Date: 2012-06-04 09:24:45
Date: 2012-06-04 09:24:44 EDT (Mon, 04 Jun 2012)
New Revision: 78805
Various small changes about revised error handling and checking ready for 1.51
Text files modified:
trunk/libs/math/doc/sf_and_dist/error_handling.qbk | 7 ++++
trunk/libs/math/doc/sf_and_dist/implementation.qbk | 55 +++++++++++++++++++++++++++++++++++++++
trunk/libs/math/doc/sf_and_dist/math.qbk | 2 +
trunk/libs/math/doc/sf_and_dist/roadmap.qbk | 8 +++++
4 files changed, 70 insertions(+), 2 deletions(-)
--- trunk/libs/math/doc/sf_and_dist/error_handling.qbk (original)
+++ trunk/libs/math/doc/sf_and_dist/error_handling.qbk 2012-06-04 09:24:44 EDT (Mon, 04 Jun 2012)
@@ -9,6 +9,9 @@
* What kind of error has been raised?
* What should be done when the error is raised?
+[warning The default error actions are to throw an exception with an informative error message.
+If you do not try to catch the exception, you will not see the message!]
The kinds of errors that can be raised are:
@@ -153,6 +156,8 @@
rather than following C-compatible behaviour and setting `::errno`.
* Numeric underflow and denormalised results were not considered to be
fatal errors in most cases, so it was felt that these should be ignored.
+* If there is more than one error,
+only the first detected will be reported in the throw message.
[heading Finding More Information]
@@ -390,7 +395,7 @@
[endsect][/section:error_handling Error Handling]
- Copyright 2006 - 2010 John Maddock and Paul A. Bristow.
+ Copyright 2006 - 2012 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
--- trunk/libs/math/doc/sf_and_dist/implementation.qbk (original)
+++ trunk/libs/math/doc/sf_and_dist/implementation.qbk 2012-06-04 09:24:44 EDT (Mon, 04 Jun 2012)
@@ -207,7 +207,18 @@
However in a few cases, for example normal, where we felt it obvious,
we have permitted argument(s) to be infinity,
-provided infinity is implemented for the realType on that implementation.
+provided infinity is implemented for the `RealType` on that implementation,
+and it is supported and tested by the distribution.
+The range for these distributions is set to infinity if supported by the platform,
+(by testing `std::numeric_limits<RealType>::has_infinity`)
+else the maximum value provided for the `RealType` by Boost.Math.
+Testing for has_infinity is obviously important for arbitrary precision types
+where infinity makes much less sense than for IEEE754 floating-point.
+So far we have not set `support()` function (only range)
+on the grounds that the PDF is uninteresting/zero for infinities.
Users who require special handling of infinity (or other specific value) can,
of course, always intercept this before calling a distribution or function
@@ -394,6 +405,48 @@
unfortunately it appears to suffer from very poor accuracy in areas where
the underlying special function is known to be difficult to implement.
+[h4 Testing for Invalid Parameters to Functions and Constructors]
+After finding that some 'bad' parameters (like NaN) were not throwing
+a `domain_error` exception as they should, a function
+`check_out_of_range` (in `test_out_of_range.hpp`)
+was devised by JM to check
+(using Boost.Test's BOOST_CHECK_THROW macro)
+that bad parameters passed to constructors and functions throw `domain_error` exceptions.
+Usage is `check_out_of_range< DistributionType >(list-of-params);`
+Where list-of-params is a list of *valid* parameters from which the distribution can be constructed
+- ie the same number of args are passed to the function,
+as are passed to the distribution constructor.
+The values of the parameters are not important, but must be *valid* to pass the contructor checks;
+the default values are suitable, but must be explicitly provided, for example:
+ check_out_of_range<extreme_value_distribution<RealType> >(1, 2);
+Checks made are:
+* Infinity or NaN (if available) passed in place of each of the valid params.
+* Infinity or NaN (if available) as a random variable.
+* Out-of-range random variable passed to pdf and cdf
+(ie outside of "range(DistributionType)").
+* Out-of-range probability passed to quantile function and complement.
+but does *not* check finite but out-of-range parameters to the constructor
+because these are specific to each distribution, for example:
+ BOOST_CHECK_THROW(pdf(pareto_distribution<RealType>(0, 1), 0), std::domain_error);
+ BOOST_CHECK_THROW(pdf(pareto_distribution<RealType>(1, 0), 0), std::domain_error);
+checks `scale` and `shape` parameters are both > 0
+by checking that `domain_error` exception is thrown if either are == 0.
+(Use of `check_out_of_range` function may mean that some previous tests are now redundant).
+It was also noted that if more than one parameter is bad,
+then only the first detected will be reported by the error message.
[h4 Creating and Managing the Equations]
Equations that fit on a single line can most easily be produced by inline Quickbook code
--- trunk/libs/math/doc/sf_and_dist/math.qbk (original)
+++ trunk/libs/math/doc/sf_and_dist/math.qbk 2012-06-04 09:24:44 EDT (Mon, 04 Jun 2012)
@@ -249,6 +249,7 @@
[def __F_distrib [link math_toolkit.dist.dist_ref.dists.f_dist Fisher F Distribution]]
[def __gamma_distrib [link math_toolkit.dist.dist_ref.dists.gamma_dist Gamma Distribution]]
[def __geometric_distrib [link math_toolkit.dist.dist_ref.dists.geometric_dist Geometric Distribution]]
+[def __hypergeometric_distrib [link math_toolkit.dist.dist_ref.dists.hypergeometric_dist hypergeometric Distribution]]
[def __inverse_gamma_distrib [link math_toolkit.dist.dist_ref.dists.inverse_gamma_dist Inverse Gamma Distribution]]
[def __inverse_gaussian_distrib [link math_toolkit.dist.dist_ref.dists.inverse_gaussian_dist Inverse Gaussian Distribution]]
[def __inverse_chi_squared_distrib [link math_toolkit.dist.dist_ref.dists.inverse_chi_squared_dist Inverse chi squared Distribution]]
@@ -263,6 +264,7 @@
[def __non_central_t_distrib [link math_toolkit.dist.dist_ref.dists.nc_t_dist noncentral T distribution]]
[def __normal_distrib [link math_toolkit.dist.dist_ref.dists.normal_dist Normal Distribution]]
[def __poisson_distrib [link math_toolkit.dist.dist_ref.dists.poisson_dist Poisson Distribution]]
+[def __pareto_distrib [link math_toolkit.dist.dist_ref.dists.pareto_dist Pareto Distribution]]
[def __students_t_distrib [link math_toolkit.dist.dist_ref.dists.students_t_dist Students t Distribution]]
[def __skew_normal_distrib [link math_toolkit.dist.dist_ref.dists.skew_normal_dist Skew Normal Distribution]]
[def __weibull_distrib [link math_toolkit.dist.dist_ref.dists.weibull_dist Weibull Distribution]]
--- trunk/libs/math/doc/sf_and_dist/roadmap.qbk (original)
+++ trunk/libs/math/doc/sf_and_dist/roadmap.qbk 2012-06-04 09:24:44 EDT (Mon, 04 Jun 2012)
@@ -1,5 +1,13 @@
+* Corrected failure to detect bad parameters in many distributions
+[@https://svn.boost.org/trac/boost/ticket/6934 #6934] (reported by Florian Schoppmann)
+by adding a function check_out_of_range to test many possible bad parameters.
+This test revealed several distributions where the checks for bad parameters were ineffective,
+and these have been rectified.
* Promoted math constants to be 1st class citizens,
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