math/doc/math.qbk

[article Math Toolkit
    [quickbook 1.3]
    [copyright 2006 John Maddock, Paul A. Bristow, Hubert Holin and Xiaogang Zhang]
    [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.], [Zhang, Xiaogang]]
    [category math]
    [/last-revision $Date$]
]

[include HTML4_symbols.qbk]

[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;''']  [/small Latin letter open e]

[def __ceilR '''&#x2309;''']
[def __ceilL '''&#2308;''']
[def __floorR '''&#x230B;''']
[def __floorL '''&#x230A;''']
[def __infin '''&#8734;''']
[def __integral '''&#8747;''']
[def __aacute '''&#225;''']
[def __eacute '''&#233;''']
[def __quarter '''&#x00BC;''']
[def __nearequal '''&#x224A;''']
[def __quarter '''&#x00BC;''']
[def __space '''&#8203;''']

[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]

[/Misc]
[def __lanczos [link math_toolkit.backgrounders.lanczos Lanczos approximation]]
[def __zero_error [link zero_error effectively zero error]]
[def __relative_error [link math_toolkit.backgrounders.relative_error relative zero error]]

[/gammas]
[def __lgamma [link math_toolkit.special.sf_gamma.lgamma lgamma]]
[def __digamma [link math_toolkit.special.sf_gamma.digamma digamma]]
[def __tgamma_ratio [link math_toolkit.special.sf_gamma.gamma_ratios tgamma_ratio]]
[def __tgamma_delta_ratio [link math_toolkit.special.sf_gamma.gamma_ratios tgamma_delta_ratio]]
[def __tgamma [link math_toolkit.special.sf_gamma.tgamma tgamma]]
[def __tgamma1pm1 [link math_toolkit.special.sf_gamma.tgamma tgamma1pm1]]
[def __tgamma_lower [link math_toolkit.special.sf_gamma.igamma tgamma_lower]]
[def __gamma_p [link math_toolkit.special.sf_gamma.igamma gamma_p]]
[def __gamma_q [link math_toolkit.special.sf_gamma.igamma gamma_q]]
[def __gamma_q_inv [link math_toolkit.special.sf_gamma.igamma_inv gamma_q_inv]]
[def __gamma_p_inv [link math_toolkit.special.sf_gamma.igamma_inv gamma_p_inv]]
[def __gamma_q_inva [link math_toolkit.special.sf_gamma.igamma_inv gamma_q_inva]]
[def __gamma_p_inva [link math_toolkit.special.sf_gamma.igamma_inv gamma_p_inva]]
[def __gamma_p_derivative [link math_toolkit.special.sf_gamma.gamma_derivatives gamma_p_derivative]]

[/factorials]
[def __factorial [link math_toolkit.special.factorials.sf_factorial factorial]]
[def __unchecked_factorial [link math_toolkit.special.factorials.sf_factorial unchecked_factorial]]
[def __max_factorial [link math_toolkit.special.factorials.sf_factorial max_factorial]]
[def __double_factorial [link math_toolkit.special.factorials.sf_double_factorial double_factorial]]
[def __rising_factorial [link math_toolkit.special.factorials.sf_rising_factorial rising_factorial]]
[def __falling_factorial [link math_toolkit.special.factorials.sf_falling_factorial falling_factorial]]

[/error functions]
[def __erf [link math_toolkit.special.sf_erf.error_function erf]]
[def __erfc [link math_toolkit.special.sf_erf.error_function erfc]]
[def __erf_inv [link math_toolkit.special.sf_erf.error_inv erf_inv]]
[def __erfc_inv [link math_toolkit.special.sf_erf.error_inv erfc_inv]]

[/beta functions]
[def __beta  [link math_toolkit.special.sf_beta.beta_function beta]]
[def __beta3 [link math_toolkit.special.sf_beta.ibeta_function beta]]
[def __betac [link math_toolkit.special.sf_beta.ibeta_function betac]]
[def __ibeta [link math_toolkit.special.sf_beta.ibeta_function ibeta]]
[def __ibetac [link math_toolkit.special.sf_beta.ibeta_function ibetac]]
[def __ibeta_inv [link math_toolkit.special.sf_beta.ibeta_inv_function ibeta_inv]]
[def __ibetac_inv [link math_toolkit.special.sf_beta.ibeta_inv_function ibetac_inv]]
[def __ibeta_inva [link math_toolkit.special.sf_beta.ibeta_inv_function ibeta_inva]]
[def __ibetac_inva [link math_toolkit.special.sf_beta.ibeta_inv_function ibetac_inva]]
[def __ibeta_invb [link math_toolkit.special.sf_beta.ibeta_inv_function ibeta_invb]]
[def __ibetac_invb [link math_toolkit.special.sf_beta.ibeta_inv_function ibetac_invb]]
[def __ibeta_derivative [link math_toolkit.special.sf_beta.beta_derivative ibeta_derivative]]

[/elliptic integrals]
[def __ellint_rj  [link math_toolkit.special.elliptic_integrals.ellint_carlson ellint_rj]]
[def __ellint_rf  [link math_toolkit.special.elliptic_integrals.ellint_carlson ellint_rf]]
[def __ellint_rc  [link math_toolkit.special.elliptic_integrals.ellint_carlson ellint_rc]]
[def __ellint_rd  [link math_toolkit.special.elliptic_integrals.ellint_carlson ellint_rd]]
[def __ellint_1  [link math_toolkit.special.elliptic_integrals.ellint_1 ellint_1]]
[def __ellint_2  [link math_toolkit.special.elliptic_integrals.ellint_2 ellint_2]]
[def __ellint_3  [link math_toolkit.special.elliptic_integrals.ellint_3 ellint_3]]

[/sinus cardinals]
[def __sinc_pi  [link math_toolkit.special.sinc.sinc_pi sinc_pi]]
[def __sinhc_pi  [link math_toolkit.special.sinc.sinhc_pi sinhc_pi]]

[/Inverse hyperbolics]
[def __acosh  [link math_toolkit.special.inv_hyper.acosh acosh]]
[def __asinh  [link math_toolkit.special.inv_hyper.asinh asinh]]
[def __atanh  [link math_toolkit.special.inv_hyper.atanh atanh]]

[/classify]
[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]]

[/powers etc]
[def __expm1 [link math_toolkit.special.powers.expm1 expm1]]
[def __log1p [link math_toolkit.special.powers.log1p log1p]]
[def __cbrt [link math_toolkit.special.powers.cbrt cbrt]]
[def __sqrt1pm1 [link math_toolkit.special.powers.sqrt1pm1 sqrt1pm1]]
[def __powm1 [link math_toolkit.special.powers.powm1 powm1]]
[def __hypot [link math_toolkit.special.powers.hypot hypot]]

[/ distribution non-members]
[def __cdf [link math.dist.cdf Cumulative Distribution Function]]
[def __pdf [link math.dist.pdf Probability Density Function]]
[def __ccdf [link math.dist.ccdf Complement of the Cumulative Distribution Function]]
[def __quantile [link math.dist.quantile Quantile]]
[def __quantile_c [link math.dist.quantile_c Quantile from the complement of the probability]]
[def __mean [link math.dist.mean mean]]
[def __median [link math.dist.median median]]
[def __mode [link math.dist.mode mode]]
[def __skewness [link math.dist.skewness skewness]]
[def __kurtosis [link math.dist.kurtosis kurtosis]]
[def __kurtosis_excess [link math.dist.kurtosis_excess kurtosis_excess]]
[def __variance [link math.dist.variance variance]]
[def __sd [link math.dist.sd standard deviation]]
[def __hazard [link math.dist.hazard Hazard Function]]
[def __chf [link math.dist.chf Cumulative Hazard Function]]
[def __range [link math.dist.range range]]
[def __support [link math.dist.support support]]

[/ distribution def names end in distrib to avoid clashes]
[def __beta_distrib [link math_toolkit.dist.dist_ref.dists.beta_dist Beta Distribution]]
[def __binomial_distrib [link math_toolkit.dist.dist_ref.dists.binomial_dist Binomial Distribution]]
[def __negative_binomial_distrib [link math_toolkit.dist.dist_ref.dists.negative_binomial_dist Negative Binomial Distribution]]
[def __chi_squared_distrib [link math_toolkit.dist.dist_ref.dists.chi_squared_dist Chi Squared Distribution]]
[def __normal_distrib [link math_toolkit.dist.dist_ref.dists.normal_dist Normal Distribution]]
[def __F_distrib [link math_toolkit.dist.dist_ref.dists.f_dist Fisher F Distribution]]
[def __students_t_distrib [link math_toolkit.dist.dist_ref.dists.students_t_dist Students t Distribution]]

[def __usual_accessors __cdf, __pdf, __quantile, __hazard, 
   __chf, __mean, __median, __mode, __variance, __sd, __skewness, 
   __kurtosis, __kurtosis_excess, __range and __support]


[/ Some composite templates]
[template super[x]'''<superscript>'''[x]'''</superscript>''']
[template sub[x]'''<subscript>'''[x]'''</subscript>''']
[template floor[x]'''&#x230A;'''[x]'''&#x230B;''']
[template floorlr[x][lfloor][x][rfloor]]
[template ceil[x] '''&#x2308;'''[x]'''&#x2309;''']

[section:intro About the Math Toolkit]

This library is divided into three interconnected parts:

[h4 Statistical Distributions]

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.

A tutorial is provided, along with a series of worked examples illustrating
how the library is used to conduct statistical tests.

[h4 Mathematical Special Functions]

Provides a small number of high quality 
[@http://en.wikipedia.org/wiki/Special_functions special functions],
initially these are be concentrated on functions used in statistical applications.

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 and various 
special power and logarithmic functions.  Future additions will focus on
those new math functions added in the C++ Technical Report on Standard Library
Extensions.

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 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.  

There are helpers for the evaluation of infinite series, continued
fractions and rational approximations.  

There is a fairly comprehensive set of root finding and function minimisation 
algorithms: both with and without derivative support.

A Remez algorithm implementation allows for the locating of minimax rational
approximations.

There are also (experimental) 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.

[endsect][/section:intro Introduction]

[include structure.qbk] [/getting about]

[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]

[section:sf_gamma Gamma Functions]

[include tgamma.qbk]
[include lgamma.qbk]
[include digamma.qbk]
[include gamma_ratios.qbk]
[include igamma.qbk]
[include igamma_inv.qbk]
[include gamma_derivatives.qbk]

[endsect]

[include factorials.qbk]

[section:sf_beta Beta Functions]

[include beta.qbk]
[include ibeta.qbk]
[include ibeta_inv.qbk]
[include beta_derivative.qbk]

[endsect]

[section:sf_erf Error Functions]

[include erf.qbk]
[include erf_inv.qbk]

[endsect]

[section:sf_poly Polynomials]

[include legendre.qbk]
[include laguerre.qbk]
[include hermite.qbk]
[include spherical_harmonic.qbk]

[endsect]

[section Elliptic Integrals]

[include ellint_introduction.qbk]
[include ellint_carlson.qbk]
[include ellint_legendre.qbk]

[endsect]

[include powers.qbk]
[include sinc.qbk]
[include inv_hyper.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]

[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: internal tools]
[endsect][/section:toolkit Toolkit]

[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 implementation.qbk]
[include error.qbk][/relative error NOT handling]
[include lanczos.qbk]
[include remez.qbk]
[include references.qbk]
[endsect][/section:backgrounds Backgrounders]

[section:status Status and Roadmap]
[include roadmap.qbk]
[include compilers.qbk]
[include issues.qbk]
[include credits.qbk]
[/include test_HTML4_symbols.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).
]