[Boost-commit] svn:boost r78805 - trunk/libs/math/doc/sf_and_dist

Subject: [Boost-commit] svn:boost r78805 - trunk/libs/math/doc/sf_and_dist
From: pbristow_at_[hidden]
Date: 2012-06-04 09:24:45

Author: pbristow
Date: 2012-06-04 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	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:
 
 [variablelist
@@ -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
   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	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

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	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]]

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	2012-06-04 09:24:44 EDT (Mon, 04 Jun 2012)
@@ -1,5 +1,13 @@
 [template history[]
 
+[h4 Boost-1.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 Boost-1.50]
 
 * Promoted math constants to be 1st class citizens,