
BoostCommit : 
Subject: [Boostcommit] svn:boost r78805  trunk/libs/math/doc/sf_and_dist
From: pbristow_at_[hidden]
Date: 20120604 09:24:45
Author: pbristow
Date: 20120604 09:24:44 EDT (Mon, 04 Jun 2012)
New Revision: 78805
URL: http://svn.boost.org/trac/boost/changeset/78805
Log:
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()
Modified: trunk/libs/math/doc/sf_and_dist/error_handling.qbk
==============================================================================
 trunk/libs/math/doc/sf_and_dist/error_handling.qbk (original)
+++ trunk/libs/math/doc/sf_and_dist/error_handling.qbk 20120604 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:
[variablelist
@@ 153,6 +156,8 @@
rather than following Ccompatible 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
http://www.boost.org/LICENSE_1_0.txt).
Modified: trunk/libs/math/doc/sf_and_dist/implementation.qbk
==============================================================================
 trunk/libs/math/doc/sf_and_dist/implementation.qbk (original)
+++ trunk/libs/math/doc/sf_and_dist/implementation.qbk 20120604 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 floatingpoint.
+
+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 >(listofparams);`
+Where listofparams 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.
+* Outofrange random variable passed to pdf and cdf
+(ie outside of "range(DistributionType)").
+* Outofrange probability passed to quantile function and complement.
+
+but does *not* check finite but outofrange 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
Modified: trunk/libs/math/doc/sf_and_dist/math.qbk
==============================================================================
 trunk/libs/math/doc/sf_and_dist/math.qbk (original)
+++ trunk/libs/math/doc/sf_and_dist/math.qbk 20120604 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]]
Modified: trunk/libs/math/doc/sf_and_dist/roadmap.qbk
==============================================================================
 trunk/libs/math/doc/sf_and_dist/roadmap.qbk (original)
+++ trunk/libs/math/doc/sf_and_dist/roadmap.qbk 20120604 09:24:44 EDT (Mon, 04 Jun 2012)
@@ 1,5 +1,13 @@
[template history[]
+[h4 Boost1.51]
+
+* 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.
+
[h4 Boost1.50]
* Promoted math constants to be 1st class citizens,
BoostCommit 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