math/doc/math.qbk

[library Math Toolkit
    [quickbook 1.3]
    [copyright 2006 John Maddock and Paul A. Bristow]
    [purpose Various Special Functions, Statistical Distributions, and Numerical Tools]
    [license
        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])
    ]
    [authors [Maddock, John], [Bristow, Paul A.]]
    [category math]
    [/last-revision $Date$]
]

[def __effects [*Effects: ]]
[def __formula [*Formula: ]]
[def __exm1 '''<code>e<superscript>x</superscript> - 1</code>''']
[def __ex '''<code>e<superscript>x</superscript></code>''']
[def __te '''2&#x025B;''']
[def __lanczos [link lanczos Lanczos approximation]]
[def __zero_error [link zero_error effectively zero error]]
[def __NTL_RR [@http://shoup.net/ntl/doc/RR.txt NTL::RR]]
[def __NTL_quad_float [@http://shoup.net/ntl/doc/quad_float.txt NTL::quad_float]]

[def __godfrey [link godfrey Godfrey]]
[def __pugh [link pugh Pugh]]

[def __caution This is not an official Boost library, it is a library under 
               construction, the code is fully functional and robust, but 
               interfaces, library structure, and function and distribution names
               may be changed without notice.]
               
[def __domain_error [link domain_error domain_error]]
[def __pole_error [link pole_error pole_error]]
[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 __logic_error [link logic_error logic_error]]
[def __checked_narrowing_cast [link checked_narrowing_cast checked_narrowing_cast]]

[/ The following macros expand to links to the various special functions
and use the function's name as the link text]

[def __tgamma [link math_toolkit.special.tgamma tgamma]]
[def __lgamma [link math_toolkit.special.lgamma tgamma]]
[def __digamma [link math_toolkit.special.lgamma digamma]]
[def __tgamma_ratio [link math_toolkit.special.gamma_ratios tgamma_ratio]]
[def __tgamma_delta_ratio [link math_toolkit.special.gamma_ratios tgamma_delta_ratio]]
[def __factorial [link math_toolkit.special.factorials factorial]]
[def __unchecked_factorial [link math_toolkit.special.factorials unchecked_factorial]]
[def __max_factorial [link math_toolkit.special.factorials max_factorial]]
[def __tgamma2 [link math_toolkit.special.igamma tgamma]]
[def __tgamma_lower [link math_toolkit.special.igamma tgamma_lower]]
[def __gamma_P [link math_toolkit.special.igamma gamma_P]]
[def __gamma_Q [link math_toolkit.special.igamma gamma_Q]]
[def __gamma_Q_inv [link math_toolkit.special.igamma_inv gamma_Q_inv]]
[def __gamma_P_inv [link math_toolkit.special.igamma_inv gamma_P_inv]]
[def __gamma_Q_inva [link math_toolkit.special.igamma_inv gamma_Q_inva]]
[def __gamma_P_inva [link math_toolkit.special.igamma_inv gamma_P_inva]]
[def __erf [link math_toolkit.special.error_function erf]]
[def __erfc [link math_toolkit.special.error_function erfc]]
[def __erf_inv [link math_toolkit.special.error_inv erf_inv]]
[def __erfc_inv [link math_toolkit.special.error_inv erfc_inv]]
[def __beta [link math_toolkit.special.beta_function beta]]
[def __beta3 [link math_toolkit.special.ibeta_function beta]]
[def __betac [link math_toolkit.special.ibeta_function betac]]
[def __ibeta [link math_toolkit.special.ibeta_function ibeta]]
[def __ibetac [link math_toolkit.special.ibeta_function ibetac]]
[def __ibeta_inv [link math_toolkit.special.ibeta_inv_function ibeta_inv]]
[def __ibetac_inv [link math_toolkit.special.ibeta_inv_function ibetac_inv]]
[def __ibeta_inva [link math_toolkit.special.ibeta_inv_function ibeta_inva]]
[def __ibetac_inva [link math_toolkit.special.ibeta_inv_function ibetac_inva]]
[def __ibeta_invb [link math_toolkit.special.ibeta_inv_function ibeta_invb]]
[def __ibetac_invb [link math_toolkit.special.ibeta_inv_function ibetac_invb]]
[def __gamma_P_derivative [link math_toolkit.special.beta_gamma_derivatives gamma_P_derivative]]
[def __ibeta_derivative [link math_toolkit.special.beta_gamma_derivatives ibeta_derivative]]
[def __fpclassify [link math_toolkit.special.fpclass fpclassify]]
[def __isfinite [link math_toolkit.special.fpclass isfinite]]
[def __isnan [link math_toolkit.special.fpclass isnan]]
[def __isinf [link math_toolkit.special.fpclass isinf]]
[def __isnormal [link math_toolkit.special.fpclass isnormal]]



[template super[x]'''<superscript>'''[x]'''</superscript>''']
[template sub[x]'''<subscript>'''[x]'''</subscript>''']

[section:intro Introduction]

This library is work in progress, it is intended to fulfil several needs:

# To provide a reasonably comprehensive set of
[@http://en.wikipedia.org/wiki/List_of_probability_distributions 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].\n
Both [@http://mathworld.wolfram.com/ContinuousDistribution.html continuous]
(like [@http://mathworld.wolfram.com/NormalDistribution.html normal]
& [@http://mathworld.wolfram.com/F-Distribution.html Fisher])
and [@http://mathworld.wolfram.com/DiscreteDistribution.html discrete]
(like [@http://mathworld.wolfram.com/BinomialDistribution.html binomial]
& [@http://mathworld.wolfram.com/PoissonDistribution.html Poisson]) distributions are provided.

# To provide a small number of high quality 
[@http://en.wikipedia.org/wiki/Special_functions special functions],
initially these will be concentrated on functions used in statistical applications.
The functions 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.  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`.
Use of these functions with interval arithmetic (Boost.Interval)
isn't quite supported yet, but it's something that needs to be investigated.

# To provide at least some 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.  Currently implemented
are helpers for the evaluation of infinite series, continued
fractions and rational approximations.  There are also
a fairly comprehensive set of root finding algorithms:
both with and without derivative support.  There are also classes 
for the manipulation of polynomials, for testing a special function
against tabulated test data, and for the rapid generation of test
data and/or data for output to an external graphing application.

# To provide the most common
[@http://en.wikipedia.org/wiki/List_of_probability_distributions probability distributions]
used for statistics as C++ templated objects, fully generic,
to support the use of arbitrary "real-number" types, so that they can be used not only with
built-in floating-point types but also User-Defined Types (UDT) conforming to the
real_concept archetype.
These distributions are implemented using the special functions above.
There are several examples of using the distributions for
some typical applications in statistics.

[endsect][/section:intro Introduction]

[section:dist Statistical Distributions and Functions]
[include dist_tutorial.qbk]
[include dist_reference.qbk]
[endsect][/section:dist Statistical Distributions and Functions]

[section:special Special Functions]
[include tgamma.qbk]
[include lgamma.qbk]
[include digamma.qbk]
[include gamma_ratios.qbk]
[include factorials.qbk]
[include igamma.qbk]
[include igamma_inv.qbk]
[include erf.qbk]
[include erf_inv.qbk]
[include beta.qbk]
[include ibeta.qbk]
[include ibeta_inv.qbk]
[include beta_gamma_derivatives.qbk]
[include fpclassify.qbk]
[include error_handling.qbk]
[endsect][/section:special Special Functions]

[section:toolkit Toolkit]
[include series.qbk]
[include fraction.qbk]
[include rational.qbk]
[include roots.qbk]
[include roots_without_derivatives.qbk]
[include minima.qbk]
[endsect][/section:toolkit Toolkit]

[section:internals Tools for Internal Testing and Development Use (Experimental)]
[include internals_overview.qbk]
[include polynomial.qbk]
[include minimax.qbk]
[include relative_error.qbk]
[include test_data.qbk]
[endsect]

[section:Using_UDT Use with User Defined Floating-Point Types]
[include concepts.qbk]
[endsect][/section:Using_UDT Use with User Defined Floating-Point Types]

[section:backgrounders Backgrounders]
[include error.qbk]
[include lanczos.qbk]
[endsect][/section:backgrounds Backgrounders]

[section:status Status and Roadmap]
[include roadmap.qbk]
[include issues.qbk]
[endsect][/section:status Status and Roadmap]

[/ math.qbk
  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).
]