|
|
Boost-Commit : |
From: john_at_[hidden]
Date: 2007-09-11 13:08:58
Author: johnmaddock
Date: 2007-09-11 13:08:57 EDT (Tue, 11 Sep 2007)
New Revision: 39192
URL: http://svn.boost.org/trac/boost/changeset/39192
Log:
Updated introductory material.
Added:
sandbox/math_toolkit/libs/math/doc/overview.qbk (contents, props changed)
sandbox/math_toolkit/libs/math/doc/thread_safety.qbk (contents, props changed)
Text files modified:
sandbox/math_toolkit/libs/math/doc/distributions/error_handling_example.qbk | 2
sandbox/math_toolkit/libs/math/doc/error_handling.qbk | 161 ++++++++++++++++++++++++++++++++-------
sandbox/math_toolkit/libs/math/doc/implementation.qbk | 4
sandbox/math_toolkit/libs/math/doc/math.qbk | 89 ---------------------
4 files changed, 138 insertions(+), 118 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-09-11 13:08:57 EDT (Tue, 11 Sep 2007)
@@ -1,6 +1,6 @@
[section:error_eg Error Handling Example]
-See [link math_toolkit.special.error_handling error handling documentation]
+See [link math_toolkit.main_overview.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.
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-09-11 13:08:57 EDT (Tue, 11 Sep 2007)
@@ -2,39 +2,141 @@
[def __format [@../../libs/format/index.html Boost.Format]]
-[h4 synopsis]
+[heading Quick Reference]
-Several __error_policy are provided to allow fine-grained control of the behaviour
-when arguments are passed for which values cannot be computed, for example,
-causing overflow, underflow, at a pole, or when accurate evaluation proves impossible.
-Defaults behaviour is provided that should be suitable for most applications.
-To provide ultimate control a user-defined error policy also can be implemented
-to provide specific __user_error_handling.
-
-The functions in this header are designed to be user-replaceable error
-handlers that define how errors are handled by the special functions
-in this library. See __user_error_handling.
+Handling of errors by this library is split into two orthogonal parts:
-There are also some pre-processor macro defines that can be used to
+* What kind of error has been raised?
+* What should be done when the error is raised?
+
+The kinds of errors that can be raised are:
+
+[variablelist
+[[Domain Error][Occurs when one or more arguments to a function
+ are out of range.]]
+[[Pole Error][Occurs when the particular arguments cause the function to be
+ evaluated at a pole with no well defined residual value. For example if
+ __tgamma is evaluated at exactly -2, the function approaches different limiting
+ values depending upon whether you approach from just above or just below
+ -2. Hence the function has no well defined value at this point and a
+ Pole Error will be raised.]]
+[[Overflow Error][Occurs when the result is either infinite, or too large
+ to represent in the numeric type being returned by the function.]]
+[[Underflow Error][Occurs when the result is not zero, but is too small
+ to be represented by any other value in the type being returned by
+ the function.]]
+[[Denormalisation Error][Occurs when the returned result would be a denormalised value.]]
+[[Evaluation Error][Occurs when an internal error occured that prevented the
+ result from being evaluated: this should never occur, but if it does, then
+ it's likely to be due to an iterative method not converging fast enough.]]
+]
+
+The action undertaken by each error condition is determined by the current
+__Policy in effect. This can be changed program-wide by setting some
+configuration macros, or at namespace scope, or at the call site (by
+specifying a specific policy in the function call).
+
+The available actions are:
+
+[variablelist
+[[throw_on_error][Throws the exception most appropriate to the error condition.]]
+[[errno_on_error][Sets ::errno to an appropriate value, and then returns the most
+appropriate result]]
+[[ignore_error][Ignores the error and simply the returns the most appropriate result.]]
+[[user_error][Calls a
+ [link math_toolkit.policy.pol_tutorial.user_defined_error_policies user-supplied error handler].]]
+]
+
+The following table shows all the permutations of errors and actions,
+with the default action for each error shown in bold:
+
+[table Possible Error Conditions, and their Defaults
+[[Error Type] [throw_on_error][errno_on_error][ignore_error][user_error]]
+[[Domain Error]
+ [[*Throws `std::domain_error`]]
+ [Sets `::errno` to `EDOM` and returns `std::numeric_limits<T>::quiet_NaN()`]
+ [Returns `std::numeric_limits<T>::quiet_NaN()`]
+ [Returns the result of `boost::math::policies::user_domain_error`:
+ [link math_toolkit.policy.pol_tutorial.user_defined_error_policies
+ this function must be defined by the user].]
+ ]
+[[Pole Error]
+ [[*Throws `std::domain_error`]]
+ [Sets `::errno` to `EDOM` and returns `std::numeric_limits<T>::quiet_NaN()`]
+ [Returns `std::numeric_limits<T>::quiet_NaN()`]
+ [Returns the result of `boost::math::policies::user_pole_error`:
+ [link math_toolkit.policy.pol_tutorial.user_defined_error_policies
+ this function must be defined by the user].]
+ ]
+[[Overflow Error]
+ [[*Throws `std::overflow_error`]]
+ [Sets `::errno` to `ERANGE` and returns `std::numeric_limits<T>::infinity()`]
+ [Returns `std::numeric_limits<T>::infinity()`]
+ [Returns the result of `boost::math::policies::user_overflow_error`:
+ [link math_toolkit.policy.pol_tutorial.user_defined_error_policies
+ this function must be defined by the user].]
+ ]
+[[Underflow Error]
+ [Throws `std::underflow_error`]
+ [Sets `::errno` to `ERANGE` and returns 0.]
+ [[*Returns 0]]
+ [Returns the result of `boost::math::policies::user_underflow_error`:
+ [link math_toolkit.policy.pol_tutorial.user_defined_error_policies
+ this function must be defined by the user].]
+ ]
+[[Denorm Error]
+ [Throws `std::underflow_error`]
+ [Sets `::errno` to `ERANGE` and returns the denormalised value.]
+ [[*Returns the denormalised value.]]
+ [Returns the result of `boost::math::policies::user_denorm_error`:
+ [link math_toolkit.policy.pol_tutorial.user_defined_error_policies
+ this function must be defined by the user].]
+ ]
+[[Evaluation Error]
+ [[*Throws `boost::math::evaluation_error`]]
+ [Sets `::errno` to `EDOM` and returns `std::numeric_limits<T>::infinity()`.]
+ [Returns `std::numeric_limits<T>::infinity()`.]
+ [Returns the result of `boost::math::policies::user_evaluation_error`:
+ [link math_toolkit.policy.pol_tutorial.user_defined_error_policies
+ this function must be defined by the user].]
+ ]
+]
+
+[heading Rationale]
+
+The flexibility of the current implementation should be reasonably obvious, the
+default behaviours were chosen based on feedback during the formal review of
+this library. It was felt that:
+
+* Genuine errors should be flagged with exceptions
+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.
+
+[heading Finding More Information]
+
+There are some pre-processor macro defines that can be used to
[link math_toolkit.policy.pol_ref.policy_defaults
-change the policy defaults].
+change the policy defaults]. See also the [link math_toolkit.policy
+policy section].
An example is at the Policy tutorial in
-[link math_toolkit.policy.pol_tutorial.changing_policy_defaults Changing the Policy Defaults].
+[link math_toolkit.policy.pol_tutorial.changing_policy_defaults
+Changing the Policy Defaults].
Full source code of this typical example of passing a 'bad' argument
(negative degrees of freedom) to Student's t distribution
-is at [@../../example/error_handling_example.cpp error_handling_example.cpp].
+is [link math_toolkit.dist.stat_tut.weg.error_eg in the error handling example].
The various kind of errors are described in more detail below.
-[#domain_error][h4 Domain Errors]
+[heading [#domain_error]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::policy::raise_domain_error<T>(FunctionName, Message, Val, __Policy);
+ boost::math::policies::raise_domain_error<T>(FunctionName, Message, Val, __Policy);
Where
`T` is the floating-point type passed to the function, `FunctionName` is the
@@ -76,13 +178,13 @@
`Val` to the full precision of T, where as "%.3g" would contain the value of
`Val` to 3 digits. See the __format documentation for more details.
-[#pole_error][h4 Evaluation at a pole]
+[heading [#pole_error]Evaluation at a pole]
When a special function is passed an argument that is at a pole
without a well defined residual value, then the function returns
the result of:
- boost::math::policy::pole_error<T>(FunctionName, Message, Val, __Policy);
+ boost::math::policies::raise_pole_error<T>(FunctionName, Message, Val, __Policy);
Where
`T` is the floating point type passed to the function, `FunctionName` is the
@@ -103,12 +205,12 @@
`val` to the full precision of T, where as "%.3g" would contain the value of
`val` to 3 digits. See the __format documentation for more details.
-[#overflow_error][h4 Numeric Overflow]
+[heading [#overflow_error]Numeric Overflow]
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::policy::overflow_error<T>(FunctionName, Message, __Policy);
+ boost::math::policies::raise_overflow_error<T>(FunctionName, Message, __Policy);
Where
`T` is the floating-point type passed to the function, `FunctionName` is the
@@ -122,12 +224,12 @@
In this situation if the type `T` doesn't support infinities,
the maximum value for the type is returned.
-[#underflow_error][h4 Numeric Underflow]
+[heading [#underflow_error]Numeric Underflow]
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::policy::underflow_error<T>(FunctionName, Message, __Policy);
+ boost::math::policies::raise_underflow_error<T>(FunctionName, Message, __Policy);
Where
`T` is the floating point type passed to the function, `FunctionName` is the
@@ -139,12 +241,12 @@
But with another policy, like `throw_on_error`,
throws an `std::underflow_error` C++ exception.
-[#denorm_error][h4 Denormalisation Errors]
+[heading [#denorm_error]Denormalisation Errors]
If the result of a special function is a denormalised value /z/ then the function
returns the result of:
- boost::math::policy::denorm_error<T>(z, FunctionName, Message, __Policy);
+ boost::math::policies::raise_denorm_error<T>(z, FunctionName, Message, __Policy);
Where
`T` is the floating point type passed to the function, `FunctionName` is the
@@ -156,12 +258,12 @@
But with another policy, like `throw_on_error`
throws an `std::underflow_error` C++ exception.
-[#evaluation_error][h4 Evaluation Errors]
+[hreading [#evaluation_error]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::policy::evaluation_error<T>(FunctionName, Message, Val, __Policy);
+ boost::math::policies::raise_evaluation_error<T>(FunctionName, Message, Val, __Policy);
Where
`T` is the floating point type passed to the function, `FunctionName` is the
@@ -170,7 +272,7 @@
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`.
+The default behaviour of this function is to throw a `boost::math::evaluation_error`.
Note that in order to support information rich error messages when throwing
exceptions, `Message` must contain
@@ -181,7 +283,7 @@
`val` to the full precision of T, where as "%.3g" would contain the value of
`val` to 3 digits. See the __format documentation for more details.
-[#checked_narrowing_cast][h4 Errors from typecasts]
+[heading [#checked_narrowing_cast]Errors from typecasts]
Many special functions evaluate their results at a higher precision
than their arguments in order to ensure full machine precision in
@@ -206,4 +308,3 @@
http://www.boost.org/LICENSE_1_0.txt).
]
-
Modified: sandbox/math_toolkit/libs/math/doc/implementation.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/implementation.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/implementation.qbk 2007-09-11 13:08:57 EDT (Tue, 11 Sep 2007)
@@ -125,12 +125,12 @@
['ISO/IEC 9899:1999 Programming languages - C]
and with the
[@www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf Draft Technical Report on C++ Library Extensions, 2005-06-24, section 5.2.1, paragraph 5].
-[link math_toolkit.special.error_handling See also domain_error].
+[link math_toolkit.main_overview.error_handling See also domain_error].
See __policy_ref for details of the error handling policies that should allow
a user to comply with any of these recommendations, as well as other behaviour.
-See [link math_toolkit.special.error_handling error handling]
+See [link math_toolkit.main_overview.error_handling error handling]
for a detailed explanation of the mechanism, and
[link math_toolkit.dist.stat_tut.weg.error_eg error_handling example]
and
Modified: sandbox/math_toolkit/libs/math/doc/math.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/math.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/math.qbk 2007-09-11 13:08:57 EDT (Tue, 11 Sep 2007)
@@ -256,90 +256,7 @@
[section:main_overview Overview]
-[section:intro About the Math Toolkit]
-
-This library is divided into three interconnected parts:
-
-[h4 Statistical Distributions]
-
-Provide a reasonably comprehensive set of
-[link math_toolkit.dist statistical distributions],
-upon which higher level statistical tests can be built.
-
-The initial focus is on the central
-[@http://en.wikipedia.org/wiki/Univariate univariate ]
-[@http://mathworld.wolfram.com/StatisticalDistribution.html distributions].
-Both [@http://mathworld.wolfram.com/ContinuousDistribution.html continuous]
-(like [link math_toolkit.dist.dist_ref.dists.normal_dist normal]
-& [link math_toolkit.dist.dist_ref.dists.f_dist Fisher])
-and [@http://mathworld.wolfram.com/DiscreteDistribution.html discrete]
-(like [link math_toolkit.dist.dist_ref.dists.binomial_dist binomial]
-& [link math_toolkit.dist.dist_ref.dists.poisson_dist Poisson])
-distributions are provided.
-
-A [link math_toolkit.dist.stat_tut comprehensive tutorial is provided],
-along with a series of
-[link math_toolkit.dist.stat_tut.weg worked examples] illustrating
-how the library is used to conduct statistical tests.
-
-[h4 Mathematical Special Functions]
-
-Provides a small number of high quality
-[link math_toolkit.special special functions],
-initially these were concentrated on functions used in statistical applications
-along with those in the [tr1].
-
-The function families currently implemented are the gamma, beta & erf functions
-along with the incomplete gamma and beta functions (four variants
-of each) and all the possible inverses of these, plus digamma,
-various factorial functions,
-Bessel functions, elliptic integrals, sinus cardinals (along with their
-hyperbolic variants), inverse hyperbolic functions, Legrendre/Laguerre/Hermite
-polynomials and various
-special power and logarithmic functions.
-
-All the implementations
-are fully generic and support the use of arbitrary "real-number" types,
-although they are optimised for use with types with known-about
-[@http://en.wikipedia.org/wiki/Significand significand (or mantissa)]
-sizes: typically `float`, `double` or `long double`.
-
-[h4 Implementation Toolkit]
-
-Provides [link math_toolkit.toolkit many of the tools] required to implement
-mathematical special functions: hopefully the presence of
-these will encourage other authors to contribute more special
-function implementations in the future. These tools are currently
-considered experimental: they are "exposed implementation details"
-whose interfaces and\/or implementations may change.
-
-There are helpers for the
-[link math_toolkit.toolkit.internals1.series_evaluation
-evaluation of infinite series],
-[link math_toolkit.toolkit.internals1.cf continued
-fractions] and [link math_toolkit.toolkit.internals1.rational
-rational approximations].
-
-There is a fairly comprehensive set of root finding and
-[link math_toolkit.toolkit.internals1.minima function minimisation
-algorithms]: the root finding algorithms are both
-[link math_toolkit.toolkit.internals1.roots with] and
-[link math_toolkit.toolkit.internals1.roots2 without] derivative support.
-
-A [link math_toolkit.toolkit.internals2.minimax
-Remez algorithm implementation] allows for the locating of minimax rational
-approximations.
-
-There are also (experimental) classes for the
-[link math_toolkit.toolkit.internals2.polynomials manipulation of polynomials], for
-[link math_toolkit.toolkit.internals2.error_test
-testing a special function against tabulated test data], and for
-the [link math_toolkit.toolkit.internals2.test_data
-rapid generation of test data] and/or data for output to an
-external graphing application.
-
-[endsect] [/section:intro Introduction]
-
+[include overview.qbk]
[include structure.qbk] [/getting about]
[include result_type_calc.qbk]
@@ -347,7 +264,9 @@
[section:pol_overview Configuration and Policies]
[policy_overview]
-[endsect][/section:pol_overview Configuration and Policies]
+[endsect]
+
+[include thread_safety.qbk]
[section:perf_over Performance]
[performance_overview]
Added: sandbox/math_toolkit/libs/math/doc/overview.qbk
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/libs/math/doc/overview.qbk 2007-09-11 13:08:57 EDT (Tue, 11 Sep 2007)
@@ -0,0 +1,83 @@
+[section:intro About the Math Toolkit]
+
+This library is divided into three interconnected parts:
+
+[h4 Statistical Distributions]
+
+Provide a reasonably comprehensive set of
+[link math_toolkit.dist statistical distributions],
+upon which higher level statistical tests can be built.
+
+The initial focus is on the central
+[@http://en.wikipedia.org/wiki/Univariate univariate ]
+[@http://mathworld.wolfram.com/StatisticalDistribution.html distributions].
+Both [@http://mathworld.wolfram.com/ContinuousDistribution.html continuous]
+(like [link math_toolkit.dist.dist_ref.dists.normal_dist normal]
+& [link math_toolkit.dist.dist_ref.dists.f_dist Fisher])
+and [@http://mathworld.wolfram.com/DiscreteDistribution.html discrete]
+(like [link math_toolkit.dist.dist_ref.dists.binomial_dist binomial]
+& [link math_toolkit.dist.dist_ref.dists.poisson_dist Poisson])
+distributions are provided.
+
+A [link math_toolkit.dist.stat_tut comprehensive tutorial is provided],
+along with a series of
+[link math_toolkit.dist.stat_tut.weg worked examples] illustrating
+how the library is used to conduct statistical tests.
+
+[h4 Mathematical Special Functions]
+
+Provides a small number of high quality
+[link math_toolkit.special special functions],
+initially these were concentrated on functions used in statistical applications
+along with those in the [tr1].
+
+The function families currently implemented are the gamma, beta & erf functions
+along with the incomplete gamma and beta functions (four variants
+of each) and all the possible inverses of these, plus digamma,
+various factorial functions,
+Bessel functions, elliptic integrals, sinus cardinals (along with their
+hyperbolic variants), inverse hyperbolic functions, Legrendre/Laguerre/Hermite
+polynomials and various
+special power and logarithmic functions.
+
+All the implementations
+are fully generic and support the use of arbitrary "real-number" types,
+although they are optimised for use with types with known-about
+[@http://en.wikipedia.org/wiki/Significand significand (or mantissa)]
+sizes: typically `float`, `double` or `long double`.
+
+[h4 Implementation Toolkit]
+
+Provides [link math_toolkit.toolkit many of the tools] required to implement
+mathematical special functions: hopefully the presence of
+these will encourage other authors to contribute more special
+function implementations in the future. These tools are currently
+considered experimental: they are "exposed implementation details"
+whose interfaces and\/or implementations may change.
+
+There are helpers for the
+[link math_toolkit.toolkit.internals1.series_evaluation
+evaluation of infinite series],
+[link math_toolkit.toolkit.internals1.cf continued
+fractions] and [link math_toolkit.toolkit.internals1.rational
+rational approximations].
+
+There is a fairly comprehensive set of root finding and
+[link math_toolkit.toolkit.internals1.minima function minimisation
+algorithms]: the root finding algorithms are both
+[link math_toolkit.toolkit.internals1.roots with] and
+[link math_toolkit.toolkit.internals1.roots2 without] derivative support.
+
+A [link math_toolkit.toolkit.internals2.minimax
+Remez algorithm implementation] allows for the locating of minimax rational
+approximations.
+
+There are also (experimental) classes for the
+[link math_toolkit.toolkit.internals2.polynomials manipulation of polynomials], for
+[link math_toolkit.toolkit.internals2.error_test
+testing a special function against tabulated test data], and for
+the [link math_toolkit.toolkit.internals2.test_data
+rapid generation of test data] and/or data for output to an
+external graphing application.
+
+[endsect] [/section:intro Introduction]
Added: sandbox/math_toolkit/libs/math/doc/thread_safety.qbk
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/libs/math/doc/thread_safety.qbk 2007-09-11 13:08:57 EDT (Tue, 11 Sep 2007)
@@ -0,0 +1,23 @@
+[section:threads Thread Safety]
+
+The library is fully thread safe and re-entrant provided the function
+and class templates in the library are instantiated with
+built-in floating point types: i.e. the types `float`, `double`
+and `long double`.
+
+However, the library [*is not thread safe] when
+used with user-defined (i.e. class type) numeric types.
+
+The reason for the latter limitation is the need to
+initialise symbolic constants using constructs such as:
+
+ static const T coefficient_array = { ... list of values ... };
+
+Which is always thread safe when T is a built-in floating point type,
+but not when T is a user defined type: as in this case there
+is a need for T's constructors to be run, leading to potential
+race conditions.
+
+This limitation may be addressed in a future release.
+
+[endsect] [/section:threads Thread Safety]
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