|
|
Boost-Commit : |
From: john_at_[hidden]
Date: 2007-08-29 13:51:24
Author: johnmaddock
Date: 2007-08-29 13:51:24 EDT (Wed, 29 Aug 2007)
New Revision: 39057
URL: http://svn.boost.org/trac/boost/changeset/39057
Log:
Re-factored some overviews, and changed the layout of the introduction.
Added:
sandbox/math_toolkit/libs/math/doc/common_overviews.qbk (contents, props changed)
Text files modified:
sandbox/math_toolkit/libs/math/doc/credits.qbk | 5 ++
sandbox/math_toolkit/libs/math/doc/math.qbk | 16 +++++++
sandbox/math_toolkit/libs/math/doc/performance.qbk | 85 +++++++++++++++++++--------------------
sandbox/math_toolkit/libs/math/doc/policy.qbk | 71 ++++++++++++++++-----------------
sandbox/math_toolkit/libs/math/doc/structure.qbk | 49 +++-------------------
5 files changed, 103 insertions(+), 123 deletions(-)
Added: sandbox/math_toolkit/libs/math/doc/common_overviews.qbk
==============================================================================
--- (empty file)
+++ sandbox/math_toolkit/libs/math/doc/common_overviews.qbk 2007-08-29 13:51:24 EDT (Wed, 29 Aug 2007)
@@ -0,0 +1,85 @@
+
+
+[template policy_overview[]
+
+Policies are a powerful fine-grain mechanism that allow you to customise the
+behaviour of this library according to your needs. There is more information
+available in the [link math_toolkit.policy.pol_tutorial policy tutorial]
+and the [link math_toolkit.policy.pol_ref policy reference].
+
+Generally speaking unless you find that the
+[link math_toolkit.policy.pol_tutorial.policy_tut_defaults
+ default policy behaviour]
+when encountering 'bad' argument values does not meet your needs,
+you should not need to worry about policies.
+
+Policies are a compile-time mechanism that allow you to change
+error-handling or calculation precision either
+program wide, or at the call site.
+
+Although the policy mechanism itself is rather complicated,
+in practice it is easy to use, and very flexible.
+
+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.
+* How many iterations a special function is permitted to perform in
+ a series evaluation or root finding algorithm before it gives up and raises an
+ __evaluation_error.
+
+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].
+
+]
+
+[template performance_overview[]
+
+By and large the performance of this library should be acceptable
+for most needs. However, you should note that the library's primary
+emphasis is on accuracy and numerical stability, and /not/ speed.
+
+In terms of the algorithms used, this library aims to use the same "best
+of breed" algorithms as many other libraries: the principle difference
+is that this library is implemented in C++ - taking advantage of all
+the abstraction mechanisms that C++ offers - where as most traditional
+numeric libraries are implemented in C or FORTRAN. Traditionally
+languages such as C or FORTAN are perceived as easier to optimise
+than more complex languages like C++, so in a sense this library
+provides a good test of current compiler technology, and the
+"abstraction penalty" - if any - of C++ compared to other languages.
+
+The two most important things you can do to ensure the best performance
+from this library are:
+
+# Turn on your compilers optimisations: the difference between "release"
+and "debug" builds can easily be a [link math_toolkit.perf.getting_best factor of 20].
+# Pick your compiler carefully: [link math_toolkit.perf.comp_compilers
+performance differences of up to
+8 fold] have been found between some windows compilers for example.
+
+The [link math_toolkit.perf performance section] contains more
+information on the performance
+of this library, what you can do to fine tune it, and how this library
+compares to some other open source alternatives.
+
+]
+
+[/ math.qbk
+ Copyright 2007 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: sandbox/math_toolkit/libs/math/doc/credits.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/credits.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/credits.qbk 2007-08-29 13:51:24 EDT (Wed, 29 Aug 2007)
@@ -20,6 +20,11 @@
Xiaogang Zhang worked on the Bessel functions and elliptic integrals for his
Google Summer of Code project 2006.
+We are also indebted to Matthias Schabel for managing the formal Boost-review
+of this library, and to all the reviewers - including Guillaume Melquiond,
+Arnaldur Gylfason, John Phillips, Stephan Tolksdorf and Jeff Garland
+- for their many helpful comments.
+
[endsect][/section:roadmap Roadmap]
[/
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-08-29 13:51:24 EDT (Wed, 29 Aug 2007)
@@ -14,6 +14,7 @@
[include html4_symbols.qbk] [/ just for testing]
[/include latin1_symbols.qbk] [/ just for testing]
+[include common_overviews.qbk][/ overviews that appear in more than one place!]
[def __effects [*Effects: ]]
[def __formula [*Formula: ]]
@@ -52,6 +53,7 @@
[def __overflow_error [link overflow_error overflow_error]]
[def __underflow_error [link underflow_error underflow_error]]
[def __denorm_error [link denorm_error denorm_error]]
+[def __evaluation_error [link evaluation_error evaluation_error]]
[def __checked_narrowing_cast [link checked_narrowing_cast checked_narrowing_cast]]
[def __arg_pomotion_rules [link math_toolkit.special.result_type ['result type calculation rules]]]
@@ -252,6 +254,8 @@
]
]
+[section:main_overview Overview]
+
[section:intro About the Math Toolkit]
This library is divided into three interconnected parts:
@@ -322,7 +326,15 @@
[include structure.qbk] [/getting about]
-[include performance.qbk]
+[section:pol_overview Configuration and Policies]
+[policy_overview]
+[endsect][/section:pol_overview Configuration and Policies]
+
+[section:perf_over Performance]
+[performance_overview]
+[endsect]
+
+[endsect][/section:main_overview Overview]
[section:dist Statistical Distributions and Functions]
[include dist_tutorial.qbk]
@@ -412,6 +424,8 @@
[include policy.qbk]
+[include performance.qbk]
+
[section:backgrounders Backgrounders]
[include implementation.qbk]
[include error.qbk] [/relative error NOT handling]
Modified: sandbox/math_toolkit/libs/math/doc/performance.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/performance.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/performance.qbk 2007-08-29 13:51:24 EDT (Wed, 29 Aug 2007)
@@ -1,31 +1,14 @@
-
-[section:perf Performance]
-
[template perf[name value] [value]]
[template para[text] '''<para>'''[text]'''</para>''']
-By and large the performance of this library should be acceptable
-for most needs. However, you should note that the library's primary
-emphasis is on accuracy and numerical stability, and /not/ speed.
-
-In terms of the algorithms used, this library aims to use the same "best
-of breed" algorithms as many other libraries: the principle difference
-is that this library is implemented in C++ - taking advantage of all
-the abstraction mechanisms that C++ offers - where as most traditional
-numeric libraries are implemented in C or FORTRAN. Traditionally
-languages such as C or FORTAN are perceived as easier to optimise
-than more complex languages like C++, so in a sense this library
-provides a good test of current compiler technology, and the
-"abstraction penalty" - if any - of C++ compared to other languages.
+[section:perf Performance]
-[heading Getting the Best Performance from this Library]
+[section:perf_over Performance Overview]
+[performance_overview]
+[endsect]
-By far the most important thing you can do when using this library
-is turn on your compiler's optimisation options. As the following
-table shows the penalty for using the library in debug mode can be
-quite large.
+[section:interp Interpretting these Results]
-[caution
In all of the following tables, the best performing
result in each row, is assigned a relative value of "1" and shown
in bold, so a score of "2" means ['"twice as slow as the best
@@ -36,16 +19,25 @@
with an Intel 2.8GHz Pentium 4 processor with 2Gb of RAM and running
either Windows XP or Mandriva Linux.
-As usual
+[caution As usual
with performance results these should be taken with a large pinch
of salt: relative performance is known to shift quite a bit depending
upon the architecture of the particular test system used. Further
more, our performance results were obtained using our own test data:
these test values are designed to provide good coverage of our code and test
all the appropriate corner cases. They do not necessarily represent
-"typical" usage: whatever that may be.
+"typical" usage: whatever that may be!
]
+[endsect]
+
+[section:getting_best Getting the Best Performance from this Library]
+
+By far the most important thing you can do when using this library
+is turn on your compiler's optimisation options. As the following
+table shows the penalty for using the library in debug mode can be
+quite large.
+
[table Performance Comparison of Release and Debug Settings
[[Function]
[Microsoft Visual C++ 8.0
@@ -60,14 +52,16 @@
[[__erf][[perf msvc-debug-erf..[para 16.65][para (1.028e-006s)]]][[perf msvc-erf..[para *1.00*][para (6.173e-008s)]]]]
[[__erf_inv][[perf msvc-debug-erf_inv..[para 19.28][para (1.215e-006s)]]][[perf msvc-erf_inv..[para *1.00*][para (6.302e-008s)]]]]
[[__ibeta and __ibetac][[perf msvc-debug-ibeta..[para 8.32][para (1.540e-005s)]]][[perf msvc-ibeta..[para *1.00*][para (1.852e-006s)]]]]
-[[__ibeta_inv and ibetac_inv][[perf msvc-debug-ibeta_inv..[para 10.25][para (7.492e-005s)]]][[perf msvc-ibeta_inv..[para *1.00*][para (7.311e-006s)]]]]
+[[__ibeta_inv and __ibetac_inv][[perf msvc-debug-ibeta_inv..[para 10.25][para (7.492e-005s)]]][[perf msvc-ibeta_inv..[para *1.00*][para (7.311e-006s)]]]]
[[__ibeta_inva, __ibetac_inva, __ibeta_invb and __ibetac_invb][[perf msvc-debug-ibeta_invab..[para 8.57][para (2.441e-004s)]]][[perf msvc-ibeta_invab..[para *1.00*][para (2.847e-005s)]]]]
-[[__gamma_p and gamma_q][[perf msvc-debug-igamma..[para 10.98][para (1.044e-005s)]]][[perf msvc-igamma..[para *1.00*][para (9.504e-007s)]]]]
-[[__gamma_p_inv and gamma_q_inv][[perf msvc-debug-igamma_inv..[para 10.25][para (3.721e-005s)]]][[perf msvc-igamma_inv..[para *1.00*][para (3.631e-006s)]]]]
-[[__gamma_p_inva and gamma_q_inva][[perf msvc-debug-igamma_inva..[para 11.26][para (1.124e-004s)]]][[perf msvc-igamma_inva..[para *1.00*][para (9.982e-006s)]]]]
+[[__gamma_p and __gamma_q][[perf msvc-debug-igamma..[para 10.98][para (1.044e-005s)]]][[perf msvc-igamma..[para *1.00*][para (9.504e-007s)]]]]
+[[__gamma_p_inv and __gamma_q_inv][[perf msvc-debug-igamma_inv..[para 10.25][para (3.721e-005s)]]][[perf msvc-igamma_inv..[para *1.00*][para (3.631e-006s)]]]]
+[[__gamma_p_inva and __gamma_q_inva][[perf msvc-debug-igamma_inva..[para 11.26][para (1.124e-004s)]]][[perf msvc-igamma_inva..[para *1.00*][para (9.982e-006s)]]]]
]
-[heading Comparing Compilers]
+[endsect]
+
+[section:comp_compilers Comparing Compilers]
After a good choice of build settings the next most important thing
you can do, is choose your compiler
@@ -93,14 +87,16 @@
[[__erf][[perf intel-erf..[para *1.00*][para (4.118e-008s)]]][[perf msvc-erf..[para 1.50][para (6.173e-008s)]]][[perf gcc-erf..[para 3.24][para (1.336e-007s)]]]]
[[__erf_inv][[perf intel-erf_inv..[para *1.00*][para (4.439e-008s)]]][[perf msvc-erf_inv..[para 1.42][para (6.302e-008s)]]][[perf gcc-erf_inv..[para 7.88][para (3.500e-007s)]]]]
[[__ibeta and __ibetac][[perf intel-ibeta..[para *1.00*][para (1.631e-006s)]]][[perf msvc-ibeta..[para 1.14][para (1.852e-006s)]]][[perf gcc-ibeta..[para 3.05][para (4.975e-006s)]]]]
-[[__ibeta_inv and ibetac_inv][[perf intel-ibeta_inv..[para *1.00*][para (6.133e-006s)]]][[perf msvc-ibeta_inv..[para 1.19][para (7.311e-006s)]]][[perf gcc-ibeta_inv..[para 2.60][para (1.597e-005s)]]]]
+[[__ibeta_inv and __ibetac_inv][[perf intel-ibeta_inv..[para *1.00*][para (6.133e-006s)]]][[perf msvc-ibeta_inv..[para 1.19][para (7.311e-006s)]]][[perf gcc-ibeta_inv..[para 2.60][para (1.597e-005s)]]]]
[[__ibeta_inva, __ibetac_inva, __ibeta_invb and __ibetac_invb][[perf intel-ibeta_invab..[para *1.00*][para (2.453e-005s)]]][[perf msvc-ibeta_invab..[para 1.16][para (2.847e-005s)]]][[perf gcc-ibeta_invab..[para 2.83][para (6.947e-005s)]]]]
-[[__gamma_p and gamma_q][[perf intel-igamma..[para *1.00*][para (6.735e-007s)]]][[perf msvc-igamma..[para 1.41][para (9.504e-007s)]]][[perf gcc-igamma..[para 2.78][para (1.872e-006s)]]]]
-[[__gamma_p_inv and gamma_q_inv][[perf intel-igamma_inv..[para *1.00*][para (2.637e-006s)]]][[perf msvc-igamma_inv..[para 1.38][para (3.631e-006s)]]][[perf gcc-igamma_inv..[para 3.31][para (8.736e-006s)]]]]
-[[__gamma_p_inva and gamma_q_inva][[perf intel-igamma_inva..[para *1.00*][para (7.716e-006s)]]][[perf msvc-igamma_inva..[para 1.29][para (9.982e-006s)]]][[perf gcc-igamma_inva..[para 2.56][para (1.974e-005s)]]]]
+[[__gamma_p and __gamma_q][[perf intel-igamma..[para *1.00*][para (6.735e-007s)]]][[perf msvc-igamma..[para 1.41][para (9.504e-007s)]]][[perf gcc-igamma..[para 2.78][para (1.872e-006s)]]]]
+[[__gamma_p_inv and __gamma_q_inv][[perf intel-igamma_inv..[para *1.00*][para (2.637e-006s)]]][[perf msvc-igamma_inv..[para 1.38][para (3.631e-006s)]]][[perf gcc-igamma_inv..[para 3.31][para (8.736e-006s)]]]]
+[[__gamma_p_inva and __gamma_q_inva][[perf intel-igamma_inva..[para *1.00*][para (7.716e-006s)]]][[perf msvc-igamma_inva..[para 1.29][para (9.982e-006s)]]][[perf gcc-igamma_inva..[para 2.56][para (1.974e-005s)]]]]
]
-[heading Performance Tuning Macros]
+[endsect]
+
+[section:tuning Performance Tuning Macros]
There are a small number of performance tuning options
that are determined by configuration macros. These should be set
@@ -231,14 +227,15 @@
[[__erf][[perf gcc-4_2-ld-erf..[para 1.48][para (1.387e-007s)]]][[perf gcc-4_2-erf..[para *1.00*][para (9.377e-008s)]]]]
[[__erf_inv][[perf gcc-4_2-ld-erf_inv..[para 1.11][para (4.009e-007s)]]][[perf gcc-4_2-erf_inv..[para *1.00*][para (3.598e-007s)]]]]
[[__ibeta and __ibetac][[perf gcc-4_2-ld-ibeta..[para 1.29][para (5.354e-006s)]]][[perf gcc-4_2-ibeta..[para *1.00*][para (4.137e-006s)]]]]
-[[__ibeta_inv and ibetac_inv][[perf gcc-4_2-ld-ibeta_inv..[para 1.44][para (2.220e-005s)]]][[perf gcc-4_2-ibeta_inv..[para *1.00*][para (1.538e-005s)]]]]
+[[__ibeta_inv and __ibetac_inv][[perf gcc-4_2-ld-ibeta_inv..[para 1.44][para (2.220e-005s)]]][[perf gcc-4_2-ibeta_inv..[para *1.00*][para (1.538e-005s)]]]]
[[__ibeta_inva, __ibetac_inva, __ibeta_invb and __ibetac_invb][[perf gcc-4_2-ld-ibeta_invab..[para 1.25][para (7.009e-005s)]]][[perf gcc-4_2-ibeta_invab..[para *1.00*][para (5.607e-005s)]]]]
-[[__gamma_p and gamma_q][[perf gcc-4_2-ld-igamma..[para 1.26][para (3.116e-006s)]]][[perf gcc-4_2-igamma..[para *1.00*][para (2.464e-006s)]]]]
-[[__gamma_p_inv and gamma_q_inv][[perf gcc-4_2-ld-igamma_inv..[para 1.27][para (1.178e-005s)]]][[perf gcc-4_2-igamma_inv..[para *1.00*][para (9.291e-006s)]]]]
-[[__gamma_p_inva and gamma_q_inva][[perf gcc-4_2-ld-igamma_inva..[para 1.20][para (2.765e-005s)]]][[perf gcc-4_2-igamma_inva..[para *1.00*][para (2.311e-005s)]]]]
+[[__gamma_p and __gamma_q][[perf gcc-4_2-ld-igamma..[para 1.26][para (3.116e-006s)]]][[perf gcc-4_2-igamma..[para *1.00*][para (2.464e-006s)]]]]
+[[__gamma_p_inv and __gamma_q_inv][[perf gcc-4_2-ld-igamma_inv..[para 1.27][para (1.178e-005s)]]][[perf gcc-4_2-igamma_inv..[para *1.00*][para (9.291e-006s)]]]]
+[[__gamma_p_inva and __gamma_q_inva][[perf gcc-4_2-ld-igamma_inva..[para 1.20][para (2.765e-005s)]]][[perf gcc-4_2-igamma_inva..[para *1.00*][para (2.311e-005s)]]]]
]
-[heading Comparisons to Other Open Source Libraries]
+[endsect]
+[section:comparisons Comparisons to Other Open Source Libraries]
We've run our performance tests both for our own code, and against other
open source implementations of the same functions. The results are
@@ -279,7 +276,7 @@
[table A Comparison to the R Statistical Library on Windows XP
[[Statistical Function][Boost][R]]
[[__beta_distrib CDF][[perf msvc-dist-beta-cdf..[para 1.20][para (1.916e-006s)]]][[perf msvc-dist-beta-R-cdf..[para *1.00*][para (1.597e-006s)]]]]
-[[__beta_distrib Quantile][[perf msvc-dist-beta-quantile..[para *1.00*][para (6.570e-006s)]]][[perf msvc-dist-beta-R-quantile..[para 74.66[footnote There are a small number of our test cases where the R library fails to converge on a result: these tend to dominate the performance result.]][para (4.905e-004s)]][para (4.905e-004s)]]]]
+[[__beta_distrib Quantile][[perf msvc-dist-beta-quantile..[para *1.00*][para (6.570e-006s)]]][[perf msvc-dist-beta-R-quantile..[para 74.66[footnote There are a small number of our test cases where the R library fails to converge on a result: these tend to dominate the performance result.]][para (4.905e-004s)]]]]
[[__binomial_distrib CDF][[perf msvc-dist-binomial-cdf..[para *1.00*][para (5.276e-007s)]]][[perf msvc-dist-binom-R-cdf..[para 2.45][para (1.293e-006s)]]]]
[[__binomial_distrib Quantile][[perf msvc-dist-binomial-quantile..[para *1.00*][para (4.013e-006s)]]][[perf msvc-dist-binom-R-quantile..[para 1.32][para (5.280e-006s)]]]]
[[__cauchy_distrib CDF][[perf msvc-dist-cauchy-cdf..[para *1.00*][para (1.231e-007s)]]][[perf msvc-dist-cauchy-R-cdf..[para 1.28][para (1.576e-007s)]]]]
@@ -295,7 +292,7 @@
[[__lognormal_distrib CDF][[perf msvc-dist-lognormal-cdf..[para *1.00*][para (2.078e-007s)]]][[perf msvc-dist-lnorm-R-cdf..[para 1.41][para (2.930e-007s)]]]]
[[__lognormal_distrib Quantile][[perf msvc-dist-lognormal-quantile..[para *1.00*][para (6.692e-007s)]]][[perf msvc-dist-lnorm-R-quantile..[para 1.63][para (1.090e-006s)]]]]
[[__negative_binomial_distrib CDF][[perf msvc-dist-negative_binomial-cdf..[para *1.00*][para (9.005e-007s)]]][[perf msvc-dist-nbinom-R-cdf..[para 2.42][para (2.178e-006s)]]]]
-[[__negative_binomial_distrib Quantile][[perf msvc-dist-negative_binomial-quantile..[para *1.00*][para (9.601e-006s)]]][[perf msvc-dist-nbinom-R-quantile..[para 53.59[footnote The R library appears to use a linear-search strategy, that can perform very badly in a small number of pathological cases, but may or may not be more efficient in "typical" cases]][para (5.145e-004s)]][para (5.145e-004s)]]]]
+[[__negative_binomial_distrib Quantile][[perf msvc-dist-negative_binomial-quantile..[para *1.00*][para (9.601e-006s)]]][[perf msvc-dist-nbinom-R-quantile..[para 53.59[footnote The R library appears to use a linear-search strategy, that can perform very badly in a small number of pathological cases, but may or may not be more efficient in "typical" cases]][para (5.145e-004s)]]]]
[[__normal_distrib CDF][[perf msvc-dist-normal-cdf..[para *1.00*][para (5.926e-008s)]]][[perf msvc-dist-norm-R-cdf..[para 3.01][para (1.785e-007s)]]]]
[[__normal_distrib Quantile][[perf msvc-dist-normal-quantile..[para *1.00*][para (1.248e-007s)]]][[perf msvc-dist-norm-R-quantile..[para 1.05][para (1.311e-007s)]]]]
[[__poisson_distrib CDF][[perf msvc-dist-poisson-cdf..[para *1.00*][para (8.999e-007s)]]][[perf msvc-dist-pois-R-cdf..[para 2.42][para (2.175e-006s)]]]]
@@ -314,7 +311,7 @@
[table A Comparison to the R Statistical Library on Linux
[[Statistical Function][Boost][R]]
[[__beta_distrib CDF][[perf gcc-4_2-dist-beta-cdf..[para 1.71][para (3.508e-006s)]]][[perf gcc-4_2-dist-beta-R-cdf..[para *1.00*][para (2.050e-006s)]]]]
-[[__beta_distrib Quantile][[perf gcc-4_2-dist-beta-quantile..[para *1.00*][para (1.294e-005s)]]][[perf gcc-4_2-dist-beta-R-quantile..[para 44.06[footnote There are a small number of our test cases where the R library fails to converge on a result: these tend to dominate the performance result.]][para (5.701e-004s)]][para (5.701e-004s)]]]]
+[[__beta_distrib Quantile][[perf gcc-4_2-dist-beta-quantile..[para *1.00*][para (1.294e-005s)]]][[perf gcc-4_2-dist-beta-R-quantile..[para 44.06[footnote There are a small number of our test cases where the R library fails to converge on a result: these tend to dominate the performance result.]][para (5.701e-004s)]]]]
[[__binomial_distrib CDF][[perf gcc-4_2-dist-binomial-cdf..[para 1.22][para (1.342e-006s)]]][[perf gcc-4_2-dist-binom-R-cdf..[para *1.00*][para (1.104e-006s)]]]]
[[__binomial_distrib Quantile][[perf gcc-4_2-dist-binomial-quantile..[para 1.36][para (7.083e-006s)]]][[perf gcc-4_2-dist-binom-R-quantile..[para *1.00*][para (5.194e-006s)]]]]
[[__cauchy_distrib CDF][[perf gcc-4_2-dist-cauchy-cdf..[para *1.00*][para (1.372e-007s)]]][[perf gcc-4_2-dist-cauchy-R-cdf..[para 1.47][para (2.017e-007s)]]]]
@@ -330,7 +327,7 @@
[[__lognormal_distrib CDF][[perf gcc-4_2-dist-lognormal-cdf..[para *1.00*][para (1.782e-007s)]]][[perf gcc-4_2-dist-lnorm-R-cdf..[para 2.00][para (3.564e-007s)]]]]
[[__lognormal_distrib Quantile][[perf gcc-4_2-dist-lognormal-quantile..[para *1.00*][para (7.093e-007s)]]][[perf gcc-4_2-dist-lnorm-R-quantile..[para 1.07][para (7.607e-007s)]]]]
[[__negative_binomial_distrib CDF][[perf gcc-4_2-dist-negative_binomial-cdf..[para 1.03][para (2.209e-006s)]]][[perf gcc-4_2-dist-nbinom-R-cdf..[para *1.00*][para (2.141e-006s)]]]]
-[[__negative_binomial_distrib Quantile][[perf gcc-4_2-dist-negative_binomial-quantile..[para *1.00*][para (1.826e-005s)]]][[perf gcc-4_2-dist-nbinom-R-quantile..[para 30.07[footnote The R library appears to use a linear-search strategy, that can perform very badly in a small number of pathological cases, but may or may not be more efficient in "typical" cases]][para (5.490e-004s)]][para (5.490e-004s)]]]]
+[[__negative_binomial_distrib Quantile][[perf gcc-4_2-dist-negative_binomial-quantile..[para *1.00*][para (1.826e-005s)]]][[perf gcc-4_2-dist-nbinom-R-quantile..[para 30.07[footnote The R library appears to use a linear-search strategy, that can perform very badly in a small number of pathological cases, but may or may not be more efficient in "typical" cases]][para (5.490e-004s)]]]]
[[__normal_distrib CDF][[perf gcc-4_2-dist-normal-cdf..[para *1.00*][para (8.542e-008s)]]][[perf gcc-4_2-dist-norm-R-cdf..[para 2.09][para (1.782e-007s)]]]]
[[__normal_distrib Quantile][[perf gcc-4_2-dist-normal-quantile..[para *1.00*][para (1.362e-007s)]]][[perf gcc-4_2-dist-norm-R-quantile..[para 1.26][para (1.722e-007s)]]]]
[[__poisson_distrib CDF][[perf gcc-4_2-dist-poisson-cdf..[para 1.10][para (1.953e-006s)]]][[perf gcc-4_2-dist-pois-R-cdf..[para *1.00*][para (1.775e-006s)]]]]
@@ -342,7 +339,7 @@
]
[endsect]
-
+[endsect]
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-29 13:51:24 EDT (Wed, 29 Aug 2007)
@@ -1,43 +1,7 @@
[section:policy Policies]
[section:pol_overview Policy Overview]
-
-Policies are a powerful fine-grain mechanism that allow you to customise the
-behaviour of this library according to your needs. There is more information
-available in the [link math_toolkit.policy.pol_tutorial policy tutorial]
-and the [link math_toolkit.policy.pol_ref policy reference].
-
-Unless you find that the [link math_toolkit.policy.pol_tutorial.policy_tut_defaults
- default policy behaviour]
-when encountering 'bad' argument values does not meet your needs,
-you should not need to worry about policies.
-
-Policies are a compile-time mechanism that allow you to change
-error-handling or calculation precision either
-program wide, or at the call site.
-
-Although the policy mechanism itself is rather complicated,
-in practice it is easy to use, and very flexible.
-
-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].
-
+[policy_overview]
[endsect][/section:pol_overview Policy Overview]
[include policy_tutorial.qbk]
@@ -471,6 +435,27 @@
[endsect][/section:precision_pol Precision Policies]
+[section:iteration_pol Iteration Limits Policies]
+
+There are two policies that effect the iterative algorithms
+used to implement the special functions in this library:
+
+ template <unsigned long limit = BOOST_MATH_MAX_SERIES_ITERATION_POLICY>
+ class max_series_iterations;
+
+ template <unsigned long limit = BOOST_MATH_MAX_ROOT_ITERATION_POLICY>
+ class max_root_iterations;
+
+The class `max_series_iterations` determines the maximum number of
+iterations permitted in a series evaluation, before the special
+function gives up and returns the result of __evaluation_error.
+
+The class `max_root_iterations` determines the maximum number
+of iterations permitted in a root-finding algorithm before the special
+function gives up and returns the result of __evaluation_error.
+
+[endsect][/section:iteration_pol Iteration Limits Policies]
+
[section:policy_defaults Using macros to Change the Policy Defaults]
You can use the various macros below to change any (or all) of the policies.
@@ -573,6 +558,18 @@
for some generic code, that needs to work with all distributions and determine
at runtime whether or not a particular property is well defined.
+[h5 BOOST_MATH_MAX_SERIES_ITERATION_POLICY]
+
+Determines how many series iterations a special function is permitted
+to perform before it gives up and returns an __evaluation_error:
+Defaults to 1000000.
+
+[h5 BOOST_MATH_MAX_ROOT_ITERATION_POLICY]
+
+Determines how many root-finding iterations a special function is permitted
+to perform before it gives up and returns an __evaluation_error:
+Defaults to 200.
+
[h5 Example]
Suppose we want overflow errors to set `::errno` and return an infinity,
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-29 13:51:24 EDT (Wed, 29 Aug 2007)
@@ -1,6 +1,4 @@
-[section:structure Getting About - Directory, Files, Namespaces & Configuration Macros]
-
-[h4 Navigation]
+[section:navigation Navigation]
Used in combination with the configured browser key (usually Alt), the
following keys act as handy shortcuts for common navigation tasks.
@@ -16,7 +14,9 @@
[^[*u]] - Up
]
-[h4 Directory File Structure for Boost Math Functions, Math Constants, & Statistics Distributions]
+[endsect]
+
+[section:directories Directory File Structure for Boost Math Functions, Math Constants, & Statistics Distributions]
[h4 boost\/math]
@@ -75,9 +75,10 @@
[@http://shoup.net/ntl/ NTL] released package to provide a few additional
(and vital) extra features.]]
]
+
+[endsect]
-
-[h4 Namespaces for Boost Math Functions, Math Constants and Statistics Distributions]
+[section:namespaces Namespaces for Boost Math Functions, Math Constants and Statistics Distributions]
All math functions and distributions are in `namespace boost::math`
@@ -94,42 +95,8 @@
Functions not intended for use by applications are in `boost::math::detail`.
Functions that may have more general use, like `digits` (significand), `max_value`, `min_value` and `epsilon` are in `boost::math::tools`.
-
-[h4 Using Functions and Distributions]
-
-See [link math_toolkit.dist.stat_tut Statistical Distributions Tutorial] and
-[link math_toolkit.dist.dist_ref Statistical Distributions Reference]
-and [link math_toolkit.special Special Functions]
-
-[h4 Configuration Policy Macros - Controlling Handling Arguments, Undefined Functions, Throwing of Exceptions, Accuracy, ]
-
-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]
+[endsect]
[/ structure.qbk
Copyright 2006 John Maddock and Paul A. Bristow.
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