math/doc/math.qbk

[article Math Toolkit
    [quickbook 1.4]
    [copyright 2006-2007 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.], [Holin, Hubert], [Zhang, Xiaogang]]
    [category math]
    [/last-revision $Date$]
]

[include html4_symbols.qbk] [/ just for testing]
[/include latin1_symbols.qbk] [/ just for testing]

[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 now an official Boost library, but remains a library under 
               construction, the code is fully functional and robust, but 
               interfaces, library structure, and function and distribution names
               may still be changed without notice.]
               
[template tr1[] [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf Technical Report on C++ Library Extensions]]
[template jm_rationals[] [link math_toolkit.backgrounders.implementation.rational_approximations_used devised by JM]]
[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 __checked_narrowing_cast [link checked_narrowing_cast checked_narrowing_cast]]

[def __arg_pomotion_rules [link math_toolkit.special.result_type ['result type calculation rules]]]
[def __sf_result [link math_toolkit.special.result_type ['calculated-result-type]]]

[/ 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.ellint.ellint_carlson ellint_rj]]
[def __ellint_rf  [link math_toolkit.special.ellint.ellint_carlson ellint_rf]]
[def __ellint_rc  [link math_toolkit.special.ellint.ellint_carlson ellint_rc]]
[def __ellint_rd  [link math_toolkit.special.ellint.ellint_carlson ellint_rd]]
[def __ellint_1  [link math_toolkit.special.ellint.ellint_1 ellint_1]]
[def __ellint_2  [link math_toolkit.special.ellint.ellint_2 ellint_2]]
[def __ellint_3  [link math_toolkit.special.ellint.ellint_3 ellint_3]]

[/Bessel functions]
[def __cyl_bessel_j  [link math_toolkit.special.bessel.bessel cyl_bessel_j]]
[def __cyl_neumann  [link math_toolkit.special.bessel.bessel cyl_neumann]]
[def __cyl_bessel_i  [link math_toolkit.special.bessel.mbessel cyl_bessel_i]]
[def __cyl_bessel_k  [link math_toolkit.special.bessel.mbessel cyl_bessel_k]]
[def __sph_bessel  [link math_toolkit.special.bessel.sph_bessel sph_bessel]]
[def __sph_neumann  [link math_toolkit.special.bessel.sph_bessel sph_neumann]]

[/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 __cauchy_distrib [link math_toolkit.dist.dist_ref.dists.cauchy_dist Cauchy Distribution]]
[def __chi_squared_distrib [link math_toolkit.dist.dist_ref.dists.chi_squared_dist Chi Squared Distribution]]
[def __exp_distrib [link math_toolkit.dist.dist_ref.dists.exp_dist Exponential Distribution]]
[def __F_distrib [link math_toolkit.dist.dist_ref.dists.f_dist Fisher F Distribution]]
[def __gamma_distrib [link math_toolkit.dist.dist_ref.dists.gamma_dist Gamma Distribution]]
[def __lognormal_distrib [link math_toolkit.dist.dist_ref.dists.lognormal_dist Log-normal Distribution]]
[def __negative_binomial_distrib [link math_toolkit.dist.dist_ref.dists.negative_binomial_dist Negative Binomial Distribution]]
[def __normal_distrib [link math_toolkit.dist.dist_ref.dists.normal_dist Normal Distribution]]
[def __poisson_distrib [link math_toolkit.dist.dist_ref.dists.poisson_dist Poisson Distribution]]
[def __students_t_distrib [link math_toolkit.dist.dist_ref.dists.students_t_dist Students t Distribution]]
[def __weibull_distrib [link math_toolkit.dist.dist_ref.dists.weibull Weibull Distribution]]

[/links to policy]
[def __Policy [link math_toolkit.policy Policy]] [/ Used in distribution template specifications]
[def __policy_section [link math_toolkit.policy Policies]] [/ Used in text to refer too.]
[def __policy_class [link math_toolkit.policy.pol_ref.pol_ref_ref policies::policy<>]]
[def __math_undefined [link math_toolkit.policy.pol_ref.assert_undefined mathematically undefined function]]
[def __policy_ref [link math_toolkit.policy.pol_ref policy reference]]
[def __math_discrete [link math_toolkit.policy.pol_ref.discrete_quant_ref discrete functions]]
[def __error_policy [link math_toolkit.policy.pol_ref.error_handling_policies error handling policies]]
[def __changing_policy_defaults [link math_toolkit.policy.pol_ref.policy_defaults changing policies defaults]]
[def __user_error_handling [link math_toolkit.policy.pol_tutorial.user_defined_error_policies user error handling]]

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

[def __gsl [@http://www.gnu.org/software/gsl/ GSL-1.9]]
[def __glibc [@http://www.gnu.org/software/libc/ GNU C Lib]]
[def __hpc [@http://docs.hp.com/en/B9106-90010/index.html HP-UX C Library]]
[def __cephes [@http://www.netlib.org/cephes/ Cephes]]


[/ 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;''']

[template header_file[file] [@../../../../[file] [file]]]

[template optional_policy[] 
The final __Policy argument is optional and can be used to
control the behaviour of the function: how it handles errors, 
what level of precision to use etc.  Refer to the 
[link math_toolkit.policy policy documentation for more details].]

[template discrete_quantile_warning[NAME]
[caution
The [NAME] distribution is a discrete distribution: internally
functions like the `cdf` and `pdf` are treated "as if" they are continuous 
functions, but in reality the results returned from these functions
only have meaning if an integer value is provided for the random variate 
argument.

The quantile function will by default return an integer result that has been
/rounded outwards/.  That is to say lower quantiles (where the probability is
less than 0.5) are rounded downward, and upper quantiles (where the probability
is greater than 0.5) are rounded upwards.  This behaviour
ensures that if an X% quantile is requested, then /at least/ the requested
coverage will be present in the central region, and /no more than/
the requested coverage will be present in the tails.

This behaviour can be changed so that the quantile functions are rounded
differently, or even return a real-valued result using 
[link math_toolkit.policy.pol_overview Policies].  It is strongly
recommended that you read the tutorial 
[link math_toolkit.policy.pol_tutorial.understand_dis_quant
Understanding Quantiles of Discrete Distributions] before
using the quantile function on the [NAME] distribution.  The
[link math_toolkit.policy.pol_ref.discrete_quant_ref reference docs] 
describe how to change the rounding policy
for these distributions.
]
]

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

[include performance.qbk]

[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] [/section:sf_gamma Gamma Functions]

[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_beta Beta Functions]

[section:sf_erf Error Functions]
[include erf.qbk]
[include erf_inv.qbk]
[endsect] [/section:sf_erf Error Functions]

[section:sf_poly Polynomials]
[include legendre.qbk]
[include laguerre.qbk]
[include hermite.qbk]
[include spherical_harmonic.qbk]
[endsect] [/section:sf_poly Polynomials]

[section:bessel Bessel Functions]
[include bessel_introduction.qbk]
[include bessel_jy.qbk]
[include bessel_ik.qbk]
[include bessel_spherical.qbk]
[endsect] [/section:bessel Bessel Functions]

[section:ellint Elliptic Integrals]
[include ellint_introduction.qbk]
[include ellint_carlson.qbk]
[include ellint_legendre.qbk]
[endsect] [/section:ellint Elliptic Integrals]

[include powers.qbk]
[include sinc.qbk]
[include inv_hyper.qbk]
[include fpclassify.qbk]
[include error_handling.qbk]
[include result_type_calc.qbk]
[endsect] [/section:special Special Functions]

[section:toolkit Internal Details and Tools (Experimental)]

[include internals_overview.qbk]

[section:internals1 Reused Utilities]
[include series.qbk]
[include fraction.qbk]
[include rational.qbk]
[include roots.qbk]
[include roots_without_derivatives.qbk]
[include minima.qbk]
[endsect] [/section:internals1 Reused Utilities]

[section:internals2 Testing and Development]
[include polynomial.qbk]
[include minimax.qbk]
[include relative_error.qbk]
[include test_data.qbk]
[endsect] [/section:internals2 Testing and Development]

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

[include policy.qbk]

[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]
[/include test_Latin1_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).
]