mirror of
https://github.com/boostorg/math.git
synced 2026-02-01 20:42:19 +00:00
127 lines
5.1 KiB
Plaintext
127 lines
5.1 KiB
Plaintext
[section:implementation Additional Implementation Notes]
|
|
|
|
[h4 Mathematical Formula and Sources for Distributions]
|
|
|
|
[h4 Implemention philosophy]
|
|
|
|
"First be right, then be fast."
|
|
|
|
There will always be potential compromises
|
|
to be made between speed and accuracy.
|
|
It may be possible to find faster methods,
|
|
particularly for certain limited ranges of arguments,
|
|
but for most applications of math functions and distributions,
|
|
we judge that speed is rarely as important as accuracy.
|
|
|
|
So our priority is accuracy.
|
|
|
|
To permit evaluation of accuracy of the special functions,
|
|
production of extremely accurate tables of test values
|
|
has received considerable effort.
|
|
|
|
(It also required much CPU effort -
|
|
there was some danger of molten plastic dripping from the bottom of JM's laptop,
|
|
so instead, PAB's Dual-core desktop was kept 50% busy for *days*
|
|
calculating some tables of test values!)
|
|
|
|
For a specific RealType, say float or double,
|
|
it may be possible to find approximations for some functions
|
|
that are simpler and thus faster, but less accurate
|
|
(perhaps because there are no refining iterations,
|
|
for example, when calculating inverse functions).
|
|
|
|
If these prove accurate enough to be "fit for his purpose",
|
|
then a user may substitute his custom specialization.
|
|
|
|
For example, there are approximations dating back from times when computation was a *lot* more expensive:
|
|
|
|
H Goldberg and H Levine, Approximate formulas for percentage points and normalisation of t and chi squared, Ann. Math. Stat., 17(4), 216 - 225 (Dec 1946).
|
|
|
|
A H Carter, Approximations to percentage points of the z-distribution, Biometrika 34(2), 352 - 358 (Dec 1947).
|
|
|
|
These could still provide sufficient accuracy for some speed-critical applications.
|
|
|
|
[h4 Handling Unsuitable Arguments]
|
|
|
|
In
|
|
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1665.pdf Errors in Mathematical Special Functions, J. Marraffino & M. Paterno]
|
|
it is proposed that signalling a domain error is mandatory
|
|
when the argument would give an mathematically undefined result.
|
|
|
|
Guideline 1
|
|
|
|
[:A mathematical function is said to be defined at a point a = (a1, a2, . . .)
|
|
if the limits as x = (x1, x2, . . .) 'approaches a from all directions agree'.
|
|
The defined value may be any number, or +infinity, or -infinity.]
|
|
|
|
Put crudely, if the function goes to + infinity
|
|
and then emerges 'round-the-back' with - infinity,
|
|
it is NOT defined.
|
|
|
|
[:The library function which approximates a mathematical function shall signal a domain error
|
|
whenever evaluated with argument values for which the mathematical function is undefined.]
|
|
|
|
Guideline 2
|
|
|
|
The library function which approximates a mathematical function
|
|
shall signal a domain error whenever evaluated with argument values
|
|
for which the mathematical function obtains a non-real value.
|
|
|
|
This implementation is believed to follow these proposals.
|
|
|
|
See [link math_toolkit.special.error_handling error handling]
|
|
for a detailed explanation of the mechanism,
|
|
and [link math_toolkit.dist.stat_tut.weg.error_eq error handling] and an example
|
|
at [@../../example/error_handling_example.cpp error_handling_example.cpp]
|
|
|
|
[caution If you enable throw but 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.
|
|
However, for simplicity, the is not done for most examples.]
|
|
|
|
[h4 Notes on Implementation of Specific Functions]
|
|
|
|
|
|
[h4 Sources of Test Data]
|
|
|
|
We found a large number of sources of test data.
|
|
We have assumed that these are /"known good/"
|
|
if they agree with the results from our test
|
|
and only consulted other sources for their /'vote/'
|
|
in the case of serious disagreement.
|
|
The accuracy, and claimed accuracy (if any), vary very widely.
|
|
Only [@http://functions.wolfram.com/ Wolfram Mathematica functions]
|
|
provided a higher accuracy than
|
|
C++ double (64-bit floating-point) and was regarded as
|
|
the most-trusted (by far) source.
|
|
|
|
A useful index of sources is:
|
|
[@http://www.sal.hut.fi/Teaching/Resources/ProbStat/table.html
|
|
Web-oriented Teaching Resources in Probability and Statistics]
|
|
|
|
[@http://espse.ed.psu.edu/edpsych/faculty/rhale/hale/507Mat/statlets/free/pdist.htm Statlet]:
|
|
Calculate and plot probability distributions is a Javascript application
|
|
that provides the most complete range of distributions:
|
|
|
|
[:Bernoulli, Binomial, discrete uniform, geometric, hypergeometric,
|
|
negative binomial, poisson, beta, cauchy, chi-sequared, erlang,
|
|
exponential, extreme value, Fish, gamma, laplace, logistic,
|
|
lognormal, normal, parteo, student's t, triangular, uniform, and weibull.]
|
|
|
|
It calculates pdf, cdf, survivor, log survivor, hazard, tail areas,
|
|
& critical values for 5 tail values.
|
|
|
|
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.
|
|
|
|
[endsect][/section:implementation Implementation Notes]
|
|
|
|
[/
|
|
Copyright 2006 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).
|
|
]
|