From 98acfb8a5d2d059bee5f967d7c171e9671b64971 Mon Sep 17 00:00:00 2001 From: "Paul A. Bristow" Date: Mon, 4 Jun 2012 13:24:44 +0000 Subject: [PATCH] Various small changes about revised error handling and checking ready for 1.51 [SVN r78805] --- doc/sf_and_dist/error_handling.qbk | 7 +++- doc/sf_and_dist/implementation.qbk | 55 +++++++++++++++++++++++++++++- doc/sf_and_dist/math.qbk | 2 ++ doc/sf_and_dist/roadmap.qbk | 8 +++++ 4 files changed, 70 insertions(+), 2 deletions(-) diff --git a/doc/sf_and_dist/error_handling.qbk b/doc/sf_and_dist/error_handling.qbk index 73f1a653a..b3001063e 100644 --- a/doc/sf_and_dist/error_handling.qbk +++ b/doc/sf_and_dist/error_handling.qbk @@ -9,6 +9,9 @@ Handling of errors by this library is split into two orthogonal parts: * 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 @@ this library. It was felt that: 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 @@ listed above on [link overflow_error overflow], [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). diff --git a/doc/sf_and_dist/implementation.qbk b/doc/sf_and_dist/implementation.qbk index 09a28941b..9f7b94da4 100644 --- a/doc/sf_and_dist/implementation.qbk +++ b/doc/sf_and_dist/implementation.qbk @@ -207,7 +207,18 @@ much more work to test, and much less readable. 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::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 @@ It is also the only independent source found for the Weibull distribution; 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 >(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(0, 1), 0), std::domain_error); + BOOST_CHECK_THROW(pdf(pareto_distribution(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 diff --git a/doc/sf_and_dist/math.qbk b/doc/sf_and_dist/math.qbk index 5e981bfce..9f74208ee 100644 --- a/doc/sf_and_dist/math.qbk +++ b/doc/sf_and_dist/math.qbk @@ -249,6 +249,7 @@ and use the function's name as the link text.] [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 @@ and use the function's name as the link text.] [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]] diff --git a/doc/sf_and_dist/roadmap.qbk b/doc/sf_and_dist/roadmap.qbk index 81524cd0d..c3f7894a0 100644 --- a/doc/sf_and_dist/roadmap.qbk +++ b/doc/sf_and_dist/roadmap.qbk @@ -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,