|
|
Boost-Commit : |
From: john_at_[hidden]
Date: 2007-08-14 08:44:21
Author: johnmaddock
Date: 2007-08-14 08:44:20 EDT (Tue, 14 Aug 2007)
New Revision: 38654
URL: http://svn.boost.org/trac/boost/changeset/38654
Log:
Fixed some typos, and a few factual errors.
Text files modified:
sandbox/math_toolkit/libs/math/doc/distributions/error_handling_example.qbk | 22 ++++++---
sandbox/math_toolkit/libs/math/doc/distributions/negative_binomial_example.qbk | 4
sandbox/math_toolkit/libs/math/doc/error_handling.qbk | 69 +++++++++++++++-------------
sandbox/math_toolkit/libs/math/doc/policy.qbk | 10 ++--
sandbox/math_toolkit/libs/math/doc/policy_tutorial.qbk | 1
sandbox/math_toolkit/libs/math/doc/structure.qbk | 93 ++++++++++++++++++++++++++++++++-------
sandbox/math_toolkit/libs/math/example/negative_binomial_example1.cpp | 2
7 files changed, 135 insertions(+), 66 deletions(-)
Modified: sandbox/math_toolkit/libs/math/doc/distributions/error_handling_example.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/distributions/error_handling_example.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/distributions/error_handling_example.qbk 2007-08-14 08:44:20 EDT (Tue, 14 Aug 2007)
@@ -1,22 +1,28 @@
[section:error_eg Error Handling Example]
-See [link math_toolkit.special.error_handling error handling]
+See [link math_toolkit.special.error_handling error handling documentation]
for a detailed explanation of the mechanism of handling errors,
including the common "bad" arguments to distributions and functions,
and how to use __policy_section to control it.
-But, by default, *exceptions will be raised*,
-to get the most appropriate value, usually a NaN, or zero, returned you need to change the policy.
+But, by default, *exceptions will be raised*, for domain errors,
+pole errors, numeric overflow, and internal evaluation errors.
+To avoid the exceptions from getting thrown and instead get
+an appropriate value returned, usually a NaN (domain errors
+pole errors or internal errors), or infinity (from overflow),
+you need to change the policy.
-See [@../../example/error_handling_example.cpp error_handling_example.cpp] for the source code of an example.
+[import ../../example/error_handling_example.cpp]
-This example is detailed at the Policy tutorial in
-[link math_toolkit.policy.pol_tutorial.changing_policy_defaults Changing the Policy Defaults].
+[error_handling_example]
-[caution If throw is enabled (the default) but do NOT have try & catch block,
+[caution If throwing of exceptions is enabled (the default) but
+you do *not* have try & catch block,
then the program will terminate with an uncaught exception and probably abort.
+
Therefore to get the benefit of helpful error messages, enabling *all exceptions
-and using try & catch* is recommended for all applications.
+and using try & catch* is recommended for most applications.
+
However, for simplicity, the is not done for most examples.]
[endsect] [/section:error_eg Error Handling Example]
Modified: sandbox/math_toolkit/libs/math/doc/distributions/negative_binomial_example.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/distributions/negative_binomial_example.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/distributions/negative_binomial_example.qbk 2007-08-14 08:44:20 EDT (Tue, 14 Aug 2007)
@@ -196,11 +196,11 @@
and obtain the following mass (density) function of the distribution of houses (for n >= 5):
Obviously, the best case is that Pat makes sales on all the first five houses.
-What is the probability that Pat finishes ON the tenth house?
+What is the probability that Pat finishes /on the tenth house/?
f(10) = 0.1003290624, or about 1 in 10
-What is the probability that Pat finishes ON OR BEFORE reaching the eighth house?
+What is the probability that Pat finishes /on or before/ reaching the eighth house?
To finish on or before the eighth house,
Pat must finish at the fifth, sixth, seventh, or eighth house.
Modified: sandbox/math_toolkit/libs/math/doc/error_handling.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/error_handling.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/error_handling.qbk 2007-08-14 08:44:20 EDT (Tue, 14 Aug 2007)
@@ -16,14 +16,8 @@
in this library. See __user_error_handling.
There are also some pre-processor macro defines that can be used to
-__changing_policy_defaults changing policies defaults.
-
-The various kind of errors are described in more detail below.
-
-[h4 Example - using the macro BOOST_MATH_DOMAIN_ERROR_POLICY]
-
-[/import ../../example/error_handling_example.cpp] [/ already imported so use a link instead.]
-[/error_handling_example]
+[link math_toolkit.policy.pol_ref.policy_defaults
+change the policy defaults].
An example is at the Policy tutorial in
[link math_toolkit.policy.pol_tutorial.changing_policy_defaults Changing the Policy Defaults].
@@ -32,21 +26,24 @@
(negative degrees of freedom) to Student's t distribution
is at [@../../example/error_handling_example.cpp error_handling_example.cpp].
+The various kind of errors are described in more detail below.
+
[#domain_error][h4 Domain Errors]
When a special function is passed an argument that is outside the range
of values for which that function is defined, then the function returns
the result of:
- boost::math::tools::domain_error<T>(FunctionName, Message, Val);
+ boost::math::policy::raise_domain_error<T>(FunctionName, Message, Val, __Policy);
Where
`T` is the floating-point type passed to the function, `FunctionName` is the
name of the function, `Message` is an error message describing the problem,
-and Val is the value that was out of range.
+Val is the value that was out of range, and __Policy is the current policy
+in use for the function that was called.
The default policy behaviour of this function is to throw a
-std::domain_error C++ exception. But if the policy is to ignore
+std::domain_error C++ exception. But if the __Policy is to ignore
the error, or set global ::errno, then a NaN will be returned.
This behaviour is chosen to assist compatibility with the behaviour of
@@ -85,15 +82,16 @@
without a well defined residual value, then the function returns
the result of:
- boost::math::tools::pole_error<T>(FunctionName, Message, Val);
+ boost::math::policy::pole_error<T>(FunctionName, Message, Val, __Policy);
Where
`T` is the floating point type passed to the function, `FunctionName` is the
name of the function, `Message` is an error message describing the problem,
-and `Val` is the value of the argument that is at a pole.
+`Val` is the value of the argument that is at a pole, and __Policy is the
+current policy in use for the function that was called.
The default behaviour of this function is to throw a std::domain_error exception.
-But __error_policy can be used to change this, for example to ignore_error
+But __error_policy can be used to change this, for example to `ignore_error`
and return NaN.
Note that in order to support information-rich error messages when throwing
@@ -110,16 +108,18 @@
When the result of a special function is too large to fit in the argument
floating-point type, then the function returns the result of:
- boost::math::tools::overflow_error<T>(FunctionName, Message);
+ boost::math::policy::overflow_error<T>(FunctionName, Message, __Policy);
Where
`T` is the floating-point type passed to the function, `FunctionName` is the
-name of the function, and `Message` is an error message describing the problem.
+name of the function, `Message` is an error message describing the problem,
+and __Policy is the current policy
+in use for the function that was called.
The default policy for this function is that `std::overflow_error`
-C++ exception is thrown. But if, for example, an ignore_error policy
+C++ exception is thrown. But if, for example, an `ignore_error` policy
is used, then returns `std::numeric_limits<T>::infinity()`.
-However if the type `T` doesn't support infinities,
+In this situation if the type `T` doesn't support infinities,
the maximum value for the type is returned.
[#underflow_error][h4 Numeric Underflow]
@@ -127,40 +127,48 @@
If the result of a special function is known to be non-zero, but the
calculated result underflows to zero, then the function returns the result of:
- boost::math::tools::underflow_error<T>(FunctionName, Message);
+ boost::math::policy::underflow_error<T>(FunctionName, Message, __Policy);
Where
`T` is the floating point type passed to the function, `FunctionName` is the
-name of the function, and `Message` is an error message describing the problem.
+name of the function, `Message` is an error message describing the problem,
+and __Policy is the current policy
+in use for the called function.
-The default version of this function throws an `std::underflow_error`
-C++ exception. But with another policy, like ignore_error, returns zero.
+The default version of this function returns zero.
+But with another policy, like `throw_on_error`,
+throws an `std::underflow_error` C++ exception.
[#denorm_error][h4 Denormalisation Errors]
If the result of a special function is a denormalised value /z/ then the function
returns the result of:
- boost::math::tools::denorm_error<T>(z, FunctionName, Message);
+ boost::math::policy::denorm_error<T>(z, FunctionName, Message, __Policy);
Where
`T` is the floating point type passed to the function, `FunctionName` is the
-name of the function, and `Message` is an error message describing the problem.
+name of the function, `Message` is an error message describing the problem,
+and __Policy is the current policy
+in use for the called function.
-The default version of this function throws an `std::underflow_error`
-C++ exception. But with another policy, like ignore_error, returns /z/.
+The default version of this function returns /z/.
+But with another policy, like `throw_on_error`
+throws an `std::underflow_error` C++ exception.
[#evaluation_error][h4 Evaluation Errors]
When a special function calculates a result that is known to be erroneous,
or where the result is incalculable then it calls:
- boost::math::tools::evaluation_error<T>(FunctionName, Message, Val);
+ boost::math::policy::evaluation_error<T>(FunctionName, Message, Val, __Policy);
Where
`T` is the floating point type passed to the function, `FunctionName` is the
name of the function, `Message` is an error message describing the problem,
-and `Val` is the erroneous value.
+`Val` is the erroneous value,
+and __Policy is the current policy
+in use for the called function.
The default behaviour of this function is to throw a `std::evaluation_error`.
@@ -182,16 +190,13 @@
above may therefore occur not during evaluation, but when converting
the result to the narrower result type. The function:
- template <class T, class U>
+ template <class T, class __Policy, class U>
T checked_narrowing_cast(U const& val, const char* function);
Is used to perform these conversions, and will call the error handlers
listed above on [link overflow_error overflow],
[link underflow_error underflow] or [link denorm_error denormalisation].
-Obviously if T and U are the same type or if T is at least as wide as U,
-then no checks are performed.
-
[endsect][/section:error_handling Error Handling]
[/
Modified: sandbox/math_toolkit/libs/math/doc/policy.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/policy.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/policy.qbk 2007-08-14 08:44:20 EDT (Tue, 14 Aug 2007)
@@ -326,11 +326,11 @@
enum discrete_quantile_policy_type
{
real,
- integer_outside, // default
- integer_inside,
- integer_below,
- integer_above,
- integer_nearest
+ integer_round_outwards, // default
+ integer_round_inwards,
+ integer_round_down,
+ integer_round_up,
+ integer_round_nearest
};
template <discrete_quantile_policy_type>
Modified: sandbox/math_toolkit/libs/math/doc/policy_tutorial.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/policy_tutorial.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/policy_tutorial.qbk 2007-08-14 08:44:20 EDT (Tue, 14 Aug 2007)
@@ -143,7 +143,6 @@
rule: but only because we know there will always be a single
translation unit only: ['don't say that you weren't warned!]
-[import ../example/error_handling_example.cpp]
[error_handling_example]
[endsect][/section:changing_policy_defaults Changing the Policy Defaults]
Modified: sandbox/math_toolkit/libs/math/doc/structure.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/structure.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/structure.qbk 2007-08-14 08:44:20 EDT (Tue, 14 Aug 2007)
@@ -20,25 +20,61 @@
[h4 boost\/math]
-* \/*concepts* Prototype defining the *essential* features of a RealType class (see real_concept.hpp). Most applications will use `double` as the RealType (and short `typedef` names of distributions are reserved for this type where possible), a few will use `float` or `long double`, but it is also possible to use higher precision types like __NTL_RR or __NTL_quad_float that conform to the requirements specified by real_concept.
-
-* \/*constants* Templated definition of some highly accurate math constants (in constants.hpp).
+[variablelist
+[[\/concepts\/]
+ [Prototype defining the *essential* features of a RealType
+ class (see real_concept.hpp). Most applications will use `double`
+ as the RealType (and short `typedef` names of distributions are
+ reserved for this type where possible), a few will use `float` or
+ `long double`, but it is also possible to use higher precision types
+ like __NTL_RR that conform to the requirements specified by real_concept.]]
+
+[[\/constants\/]
+ [Templated definition of some highly accurate math
+ constants (in constants.hpp).]]
-* \/*special_functions* Math functions generally regarded as 'special', like beta, cbrt, erf, gamma, lgamma, tgamma ... (Some of these are specified in C++, and C99\/TR1, and perhaps TR2).
+[[\/distributions\/]
+ [Distributions used in mathematics and, especially, statistics:
+ Gaussian, Students-t, Fisher, Binomial etc]]
+
+[[\/policy\/]
+ [Policy framework, for handling user requested behaviour modifications.]]
-* \/*distributions* Distributions used in mathematics and, especially, statistics: Gaussian, Students-t, Fisher, Binomial ...
+[[\/special_functions\/]
+ [Math functions generally regarded as 'special', like beta,
+ cbrt, erf, gamma, lgamma, tgamma ... (Some of these are specified in
+ C++, and C99\/TR1, and perhaps TR2).]]
-* \/*tools* Tools used by functions, like evaluating polynomials, continued fractions, root finding, precision and limits, and by tests. Some will find application outside this package.
+[[\/tools\/]
+ [Tools used by functions, like evaluating polynomials, continued fractions,
+ root finding, precision and limits, and by tests. Some will
+ find application outside this package.]]
+]
-[h4 boost/libs]
-* \/*doc* Documentation source files in Quickbook format processed into html and pdf formats.
-
-* \/*examples* Examples and demos of using math functions and distributions.
-
-* \/*test* Test files, in various .cpp files, most using Boost.Test (some with test data as .ipp files, usually generated using NTL RR type with ample precision for the type, often for precisions suitable for up to 256-bit significand real types).
-
-* \/*tools* Programs used to generate test data. Also changes to the
-[@http://shoup.net/ntl/ NTL] released package to provide a few additional (and vital) extra features.
+[h4 boost\/libs]
+
+[variablelist
+[[\/doc\/]
+ [Documentation source files in Quickbook format processed into
+ html and pdf formats.]]
+
+[[\/examples\/]
+ [Examples and demos of using math functions and distributions.]]
+
+[[\/performance\/]
+ [Performance testing and tuning program.]]
+
+[[\/test\/]
+ [Test files, in various .cpp files, most using Boost.Test
+ (some with test data as .ipp files, usually generated using NTL RR
+ type with ample precision for the type, often for precisions
+ suitable for up to 256-bit significand real types).]]
+
+[[\/tools\/]
+ [Programs used to generate test data. Also changes to the
+ [@http://shoup.net/ntl/ NTL] released package to provide a few additional
+ (and vital) extra features.]]
+]
[h4 Namespaces for Boost Math Functions, Math Constants and Statistics Distributions]
@@ -67,8 +103,31 @@
[h4 Configuration Policy Macros - Controlling Handling Arguments, Undefined Functions, Throwing of Exceptions, Accuracy, ]
-See [link math_toolkit.policy Policy]
-on the default behaviour (that may well be suitable) and, if not, how to control it.
+There are some configuration macros that can be used to control how the
+library behaves. These are part of the Policy framework:
+
+Using policies you can control:
+
+* [link math_toolkit.policy.pol_ref.error_handling_policies How results from 'bad' arguments are handled],
+ including those that cannot be fully evaluated.
+* How [link math_toolkit.policy.pol_ref.internal_promotion accuracy is controlled by internal promotion] to use more precise types.
+* What working [link math_toolkit.policy.pol_ref.precision_pol precision] should be used to calculate results.
+* What do to when a [link math_toolkit.policy.pol_ref.assert_undefined mathematically undefined function]
+ is used: Should this raise a run-time or compile-time error?
+* Whether [link math_toolkit.policy.pol_ref.discrete_quant_ref discrete functions],
+ like the binomial, should return real or only integral values, and how they are rounded.
+
+You can control policies:
+
+* Using [link math_toolkit.policy.pol_ref.policy_defaults macros] to change any default policy.
+* At your chosen [link math_toolkit.policy.pol_ref.namespace_pol namespace scope] for distributions and/or functions.
+* In an ad-hoc manner [link math_toolkit.policy.pol_tutorial.ad_hoc_sf_policies
+by passing a specific policy to a special function], or to a
+[link math_toolkit.policy.pol_tutorial.ad_hoc_dist_policies statistical distribution].
+
+See also the
+[link math_toolkit.policy.pol_tutorial policy tutorial], and
+[link math_toolkit.policy.pol_ref policy reference].
[endsect][/sect:structure Getting About - Directory, Namespace & File structure]
Modified: sandbox/math_toolkit/libs/math/example/negative_binomial_example1.cpp
==============================================================================
--- sandbox/math_toolkit/libs/math/example/negative_binomial_example1.cpp (original)
+++ sandbox/math_toolkit/libs/math/example/negative_binomial_example1.cpp 2007-08-14 08:44:20 EDT (Tue, 14 Aug 2007)
@@ -15,7 +15,7 @@
First we need to #define macros to control the error and discrete handling policies.
For this simple example, we want to avoid throwing an exception (the default policy) and just return infinity.
We want to treat the distribution as if it was continuous, so we choose a policy of real,
-rather than the default policy integer_outside.
+rather than the default policy integer_round_outwards.
*/
#define BOOST_MATH_OVERFLOW_ERROR_POLICY ignore_error
#define BOOST_MATH_DISCRETE_QUANTILE_POLICY real
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