Boost logo

Boost-Commit :

From: john_at_[hidden]
Date: 2007-10-09 07:30:36


Author: johnmaddock
Date: 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
New Revision: 39835
URL: http://svn.boost.org/trac/boost/changeset/39835

Log:
Added HTML docs, changed some section names to shorten the file names produced.
Added:
   trunk/libs/math/doc/sf_and_dist/html/
   trunk/libs/math/doc/sf_and_dist/html/index.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders/implementation.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders/lanczos.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders/refs.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders/relative_error.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders/remez.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dist_algorithms.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/bernoulli_dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/beta_dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/binomial_dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/cauchy_dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/chi_squared_dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/exp_dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/extreme_dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/f_dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/gamma_dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/lognormal_dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/negative_binomial_dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/normal_dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/pareto.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/poisson_dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/rayleigh.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/students_t_dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/triangular_dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/uniform_dist.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/weibull.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/nmp.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/future.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/dist_params.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/overview.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/variates.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/binom_eg/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/binom_eg.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/binom_eg/binom_conf.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/binom_eg/binom_size_eg.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/binom_eg/binomial_coinflip_example.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/binom_eg/binomial_quiz_example.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/cs_eg/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/cs_eg.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/cs_eg/chi_sq_intervals.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/cs_eg/chi_sq_size.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/cs_eg/chi_sq_test.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/dist_construct_eg.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/error_eg.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/f_eg.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/find_eg/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/find_eg.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/find_eg/find_location_eg.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/find_eg/find_mean_and_sd_eg.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/find_eg/find_scale_eg.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/nag_library.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/neg_binom_eg/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/neg_binom_eg.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/neg_binom_eg/neg_binom_conf.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/neg_binom_eg/neg_binom_size_eg.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/neg_binom_eg/negative_binomial_example1.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/neg_binom_eg/negative_binomial_example2.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/normal_example/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/normal_example.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/normal_example/normal_misc.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg/paired_st.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg/tut_mean_intervals.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg/tut_mean_size.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg/tut_mean_test.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg/two_sample_students_t.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/contact.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/directories.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/error_handling.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/history1.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/intro.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/namespaces.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/navigation.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/perf_over.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/pol_overview.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/result_type.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/threads.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/comp_compilers.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/comparisons.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/getting_best.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/interp.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/perf_over.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/perf_test_app.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/tuning.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_overview.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/assert_undefined.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/discrete_quant_ref.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/error_handling_policies.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/internal_promotion.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/iteration_pol.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/namespace_pol.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/pol_ref_ref.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/policy_defaults.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/precision_pol.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/ad_hoc_dist_policies.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/ad_hoc_sf_policies.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/changing_policy_defaults.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/namespace_policies.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/policy_tut_defaults.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/policy_usage.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/understand_dis_quant.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/user_def_err_pol.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/what_is_a_policy.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/bessel/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/bessel.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/bessel/bessel.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/bessel/bessel_over.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/bessel/mbessel.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/bessel/sph_bessel.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint/ellint_1.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint/ellint_2.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint/ellint_3.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint/ellint_carlson.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint/ellint_intro.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials/sf_binomial.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials/sf_double_factorial.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials/sf_factorial.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials/sf_falling_factorial.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials/sf_rising_factorial.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/fpclass.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/inv_hyper/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/inv_hyper.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/inv_hyper/acosh.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/inv_hyper/asinh.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/inv_hyper/atanh.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/inv_hyper/inv_hyper_over.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/cbrt.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/expm1.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/hypot.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/log1p.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/powm1.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/sqrt1pm1.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_beta/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_beta.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_beta/beta_derivative.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_beta/beta_function.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_beta/ibeta_function.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_beta/ibeta_inv_function.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_erf/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_erf.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_erf/error_function.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_erf/error_inv.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/digamma.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/gamma_derivatives.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/gamma_ratios.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/igamma.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/igamma_inv.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/lgamma.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/tgamma.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_poly/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_poly.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_poly/hermite.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_poly/laguerre.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_poly/legendre.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_poly/sph_harm.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sinc/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sinc.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sinc/sinc_overview.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sinc/sinc_pi.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sinc/sinhc_pi.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/status/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/status.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/status/compilers.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/status/credits.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/status/history1.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/status/issues.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/cf.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/minima.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/rational.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/roots.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/roots2.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/series_evaluation.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2/error_test.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2/minimax.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2/polynomials.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2/test_data.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals_overview.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/using_udt/
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/using_udt.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/using_udt/archetypes.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/using_udt/concepts.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/using_udt/dist_concept.html (contents, props changed)
   trunk/libs/math/doc/sf_and_dist/html/math_toolkit/using_udt/use_ntl.html (contents, props changed)
Text files modified:
   trunk/libs/math/doc/sf_and_dist/distributions/distribution_construction.qbk | 4 ++--
   trunk/libs/math/doc/sf_and_dist/error_handling.qbk | 14 +++++++-------
   trunk/libs/math/doc/sf_and_dist/math.qbk | 2 +-
   trunk/libs/math/doc/sf_and_dist/policy.qbk | 2 +-
   trunk/libs/math/doc/sf_and_dist/policy_tutorial.qbk | 4 ++--
   trunk/libs/math/doc/sf_and_dist/roadmap.qbk | 5 +++++
   6 files changed, 18 insertions(+), 13 deletions(-)

Modified: trunk/libs/math/doc/sf_and_dist/distributions/distribution_construction.qbk
==============================================================================
--- trunk/libs/math/doc/sf_and_dist/distributions/distribution_construction.qbk (original)
+++ trunk/libs/math/doc/sf_and_dist/distributions/distribution_construction.qbk 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -1,4 +1,4 @@
-[section:distribution_construction_eg Distribution Construction Example]
+[section:dist_construct_eg Distribution Construction Example]
 
 See [@../../../example/distribution_construction.cpp distribution_construction.cpp] for full source code.
 
@@ -6,4 +6,4 @@
 [distribution_construction1]
 [distribution_construction2]
 
-[endsect] [/section:distribution_construction_eg Distribution Construction Example]
+[endsect] [/section:dist_construct_eg Distribution Construction Example]

Modified: trunk/libs/math/doc/sf_and_dist/error_handling.qbk
==============================================================================
--- trunk/libs/math/doc/sf_and_dist/error_handling.qbk (original)
+++ trunk/libs/math/doc/sf_and_dist/error_handling.qbk 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -44,7 +44,7 @@
 appropriate result]]
 [[ignore_error][Ignores the error and simply the returns the most appropriate result.]]
 [[user_error][Calls a
- [link math_toolkit.policy.pol_tutorial.user_defined_error_policies user-supplied error handler].]]
+ [link math_toolkit.policy.pol_tutorial.user_def_err_pol user-supplied error handler].]]
 ]
 
 The following tables show all the permutations of errors and actions,
@@ -56,7 +56,7 @@
 [[errno_on_error][Sets `::errno` to `EDOM` and returns `std::numeric_limits<T>::quiet_NaN()`]]
 [[ignore_error][Returns `std::numeric_limits<T>::quiet_NaN()`]]
 [[user_error][Returns the result of `boost::math::policies::user_domain_error`:
- [link math_toolkit.policy.pol_tutorial.user_defined_error_policies
+ [link math_toolkit.policy.pol_tutorial.user_def_err_pol
             this function must be defined by the user].]]
 ]
     
@@ -66,7 +66,7 @@
 [[errno_on_error][Sets `::errno` to `EDOM` and returns `std::numeric_limits<T>::quiet_NaN()`]]
 [[ignore_error][Returns `std::numeric_limits<T>::quiet_NaN()`]]
 [[user_error][Returns the result of `boost::math::policies::user_pole_error`:
- [link math_toolkit.policy.pol_tutorial.user_defined_error_policies
+ [link math_toolkit.policy.pol_tutorial.user_def_err_pol
             this function must be defined by the user].]]
 ]
 
@@ -76,7 +76,7 @@
 [[errno_on_error][Sets `::errno` to `ERANGE` and returns `std::numeric_limits<T>::infinity()`]]
 [[ignore_error][Returns `std::numeric_limits<T>::infinity()`]]
 [[user_error][Returns the result of `boost::math::policies::user_overflow_error`:
- [link math_toolkit.policy.pol_tutorial.user_defined_error_policies
+ [link math_toolkit.policy.pol_tutorial.user_def_err_pol
             this function must be defined by the user].]]
 ]
 
@@ -86,7 +86,7 @@
 [[errno_on_error][Sets `::errno` to `ERANGE` and returns 0.]]
 [[ignore_error][[*Returns 0]]]
 [[user_error][Returns the result of `boost::math::policies::user_underflow_error`:
- [link math_toolkit.policy.pol_tutorial.user_defined_error_policies
+ [link math_toolkit.policy.pol_tutorial.user_def_err_pol
             this function must be defined by the user].]]
 ]
 
@@ -96,7 +96,7 @@
 [[errno_on_error][Sets `::errno` to `ERANGE` and returns the denormalised value.]]
 [[ignore_error][[*Returns the denormalised value.]]]
 [[user_error][Returns the result of `boost::math::policies::user_denorm_error`:
- [link math_toolkit.policy.pol_tutorial.user_defined_error_policies
+ [link math_toolkit.policy.pol_tutorial.user_def_err_pol
             this function must be defined by the user].]]
 ]
 
@@ -106,7 +106,7 @@
 [[errno_on_error][Sets `::errno` to `EDOM` and returns `std::numeric_limits<T>::infinity()`.]]
 [[ignore_error][Returns `std::numeric_limits<T>::infinity()`.]]
 [[user_error][Returns the result of `boost::math::policies::user_evaluation_error`:
- [link math_toolkit.policy.pol_tutorial.user_defined_error_policies
+ [link math_toolkit.policy.pol_tutorial.user_def_err_pol
             this function must be defined by the user].]]
 ]
 

Added: trunk/libs/math/doc/sf_and_dist/html/index.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/index.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,394 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Math Toolkit</title>
+<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="index.html" title="Math Toolkit">
+<link rel="next" href="math_toolkit/main_overview.html" title="Overview">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav"><a accesskey="n" href="math_toolkit/main_overview.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a></div>
+<div class="article" lang="en">
+<div class="titlepage">
+<div>
+<div><h2 class="title">
+<a name="math_toolkit"></a>Math Toolkit</h2></div>
+<div><div class="authorgroup">
+<div class="author"><h3 class="author">
+<span class="firstname">John</span> <span class="surname">Maddock</span>
+</h3></div>
+<div class="author"><h3 class="author">
+<span class="firstname">Paul A.</span> <span class="surname">Bristow</span>
+</h3></div>
+<div class="author"><h3 class="author">
+<span class="firstname">Hubert</span> <span class="surname">Holin</span>
+</h3></div>
+<div class="author"><h3 class="author">
+<span class="firstname">Xiaogang</span> <span class="surname">Zhang</span>
+</h3></div>
+</div></div>
+<div><p class="copyright">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</p></div>
+<div><div class="legalnotice">
+<a name="id489799"></a><p>
+ 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)
+ </p>
+</div></div>
+</div>
+<hr>
+</div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt><span class="section"> Overview</span></dt>
+<dd><dl>
+<dt><span class="section"> About the Math Toolkit</span></dt>
+<dt><span class="section"> Navigation</span></dt>
+<dt><span class="section"><a href="math_toolkit/main_overview/directories.html"> Directory and
+ File Structure</a></span></dt>
+<dt><span class="section"> Namespaces</span></dt>
+<dt><span class="section"><a href="math_toolkit/main_overview/result_type.html"> Calculation
+ of the Type of the Result</a></span></dt>
+<dt><span class="section"> Error Handling</span></dt>
+<dt><span class="section"><a href="math_toolkit/main_overview/pol_overview.html"> Configuration
+ and Policies</a></span></dt>
+<dt><span class="section"> Thread Safety</span></dt>
+<dt><span class="section"> Performance</span></dt>
+<dt><span class="section"><a href="math_toolkit/main_overview/history1.html"> History and What's
+ New</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/main_overview/contact.html"> Contact Info and
+ Support</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Statistical Distributions and Functions</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="math_toolkit/dist/stat_tut.html"> Statistical Distributions
+ Tutorial</a></span></dt>
+<dd><dl>
+<dt><span class="section"> Overview</span></dt>
+<dt><span class="section"> Worked Examples</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="math_toolkit/dist/stat_tut/weg/dist_construct_eg.html">
+ Distribution Construction Example</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/stat_tut/weg/st_eg.html"> Student's
+ t Distribution Examples</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/stat_tut/weg/cs_eg.html"> Chi Squared
+ Distribution Examples</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/stat_tut/weg/f_eg.html"> F Distribution
+ Examples</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/stat_tut/weg/binom_eg.html"> Binomial
+ Distribution Examples</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/stat_tut/weg/neg_binom_eg.html"> Negative
+ Binomial Distribution Examples</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/stat_tut/weg/normal_example.html"> Normal
+ Distribution Examples</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/stat_tut/weg/error_eg.html"> Error Handling
+ Example</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/stat_tut/weg/find_eg.html"> Find Location
+ and Scale Examples</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/stat_tut/weg/nag_library.html"> Comparison
+ with C, R, FORTRAN-style Free Functions</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="math_toolkit/dist/stat_tut/variates.html"> Random Variates
+ and Distribution Parameters</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/stat_tut/dist_params.html"> Discrete Probability
+ Distributions</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref.html"> Statistical Distributions
+ Reference</a></span></dt>
+<dd><dl>
+<dt><span class="section"> Non-Member Properties</span></dt>
+<dt><span class="section"> Distributions</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/bernoulli_dist.html">
+ Bernoulli Distribution</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/beta_dist.html"> Beta
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/binomial_dist.html">
+ Binomial Distribution</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/cauchy_dist.html"> Cauchy-Lorentz
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/chi_squared_dist.html">
+ Chi Squared Distribution</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/exp_dist.html"> Exponential
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/extreme_dist.html"> Extreme
+ Value Distribution</a></span></dt>
+<dt><span class="section"> F Distribution</span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/gamma_dist.html"> Gamma
+ (and Erlang) Distribution</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/lognormal_dist.html">
+ Log Normal Distribution</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/negative_binomial_dist.html">
+ Negative Binomial Distribution</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/normal_dist.html"> Normal
+ (Gaussian) Distribution</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/pareto.html"> Pareto
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/poisson_dist.html"> Poisson
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/rayleigh.html"> Rayleigh
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/students_t_dist.html">
+ Students t Distribution</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/triangular_dist.html">
+ Triangular Distribution</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/weibull.html"> Weibull
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dists/uniform_dist.html"> Uniform
+ Distribution</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="math_toolkit/dist/dist_ref/dist_algorithms.html"> Distribution
+ Algorithms</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Extras/Future Directions</span></dt>
+</dl></dd>
+<dt><span class="section"> Special Functions</span></dt>
+<dd><dl>
+<dt><span class="section"> Gamma Functions</span></dt>
+<dd><dl>
+<dt><span class="section"> Gamma</span></dt>
+<dt><span class="section"> Log Gamma</span></dt>
+<dt><span class="section"> Digamma</span></dt>
+<dt><span class="section"><a href="math_toolkit/special/sf_gamma/gamma_ratios.html"> Ratios
+ of Gamma Functions</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/sf_gamma/igamma.html"> Incomplete Gamma
+ Functions</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/sf_gamma/igamma_inv.html"> Incomplete
+ Gamma Function Inverses</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/sf_gamma/gamma_derivatives.html"> Derivative
+ of the Incomplete Gamma Function</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="math_toolkit/special/factorials.html"> Factorials and Binomial
+ Coefficients</a></span></dt>
+<dd><dl>
+<dt><span class="section"> Factorial</span></dt>
+<dt><span class="section"><a href="math_toolkit/special/factorials/sf_double_factorial.html">
+ Double Factorial</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/factorials/sf_rising_factorial.html">
+ Rising Factorial</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/factorials/sf_falling_factorial.html">
+ Falling Factorial</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/factorials/sf_binomial.html"> Binomial
+ Coefficients</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Beta Functions</span></dt>
+<dd><dl>
+<dt><span class="section"> Beta</span></dt>
+<dt><span class="section"><a href="math_toolkit/special/sf_beta/ibeta_function.html"> Incomplete
+ Beta Functions</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/sf_beta/ibeta_inv_function.html"> The
+ Incomplete Beta Function Inverses</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/sf_beta/beta_derivative.html"> Derivative
+ of the Incomplete Beta Function</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Error Functions</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="math_toolkit/special/sf_erf/error_function.html"> Error
+ Functions</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/sf_erf/error_inv.html"> Error Function
+ Inverses</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Polynomials</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="math_toolkit/special/sf_poly/legendre.html"> Legendre (and
+ Associated) Polynomials</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/sf_poly/laguerre.html"> Laguerre (and
+ Associated) Polynomials</a></span></dt>
+<dt><span class="section"> Hermite Polynomials</span></dt>
+<dt><span class="section"> Spherical Harmonics</span></dt>
+</dl></dd>
+<dt><span class="section"> Bessel Functions</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="math_toolkit/special/bessel/bessel_over.html"> Bessel Function
+ Overview</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/bessel/bessel.html"> Bessel Functions
+ of the First and Second Kinds</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/bessel/mbessel.html"> Modified Bessel
+ Functions of the First and Second Kinds</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/bessel/sph_bessel.html"> Spherical
+ Bessel Functions of the First and Second Kinds</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Elliptic Integrals</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="math_toolkit/special/ellint/ellint_intro.html"> Elliptic
+ Integral Overview</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/ellint/ellint_carlson.html"> Elliptic
+ Integrals - Carlson Form</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/ellint/ellint_1.html"> Elliptic Integrals
+ of the First Kind - Legendre Form</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/ellint/ellint_2.html"> Elliptic Integrals
+ of the Second Kind - Legendre Form</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/special/ellint/ellint_3.html"> Elliptic Integrals
+ of the Third Kind - Legendre Form</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="math_toolkit/special/powers.html"> Logs, Powers, Roots and
+ Exponentials</a></span></dt>
+<dd><dl>
+<dt><span class="section"> log1p</span></dt>
+<dt><span class="section"> expm1</span></dt>
+<dt><span class="section"> cbrt</span></dt>
+<dt><span class="section"> sqrt1pm1</span></dt>
+<dt><span class="section"> powm1</span></dt>
+<dt><span class="section"> hypot</span></dt>
+</dl></dd>
+<dt><span class="section"><a href="math_toolkit/special/sinc.html"> Sinus Cardinal and Hyperbolic
+ Sinus Cardinal Functions</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="math_toolkit/special/sinc/sinc_overview.html"> Sinus Cardinal
+ and Hyperbolic Sinus Cardinal Functions Overview</a></span></dt>
+<dt><span class="section">sinc_pi</span></dt>
+<dt><span class="section">sinhc_pi</span></dt>
+</dl></dd>
+<dt><span class="section"> Inverse Hyperbolic Functions</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="math_toolkit/special/inv_hyper/inv_hyper_over.html"> Inverse
+ Hyperbolic Functions Overview</a></span></dt>
+<dt><span class="section"> acosh</span></dt>
+<dt><span class="section"> asinh</span></dt>
+<dt><span class="section"> atanh</span></dt>
+</dl></dd>
+<dt><span class="section"><a href="math_toolkit/special/fpclass.html"> Floating Point Classification:
+ Infinities and NaN's</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Internal Details and Tools (Experimental)</span></dt>
+<dd><dl>
+<dt><span class="section"> Overview</span></dt>
+<dt><span class="section"> Reused Utilities</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="math_toolkit/toolkit/internals1/series_evaluation.html">
+ Series Evaluation</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/toolkit/internals1/cf.html"> Continued Fraction
+ Evaluation</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/toolkit/internals1/rational.html"> Polynomial
+ and Rational Function Evaluation</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/toolkit/internals1/roots.html"> Root Finding
+ With Derivatives</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/toolkit/internals1/roots2.html"> Root Finding
+ Without Derivatives</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/toolkit/internals1/minima.html"> Locating Function
+ Minima</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Testing and Development</span></dt>
+<dd><dl>
+<dt><span class="section"> Polynomials</span></dt>
+<dt><span class="section"><a href="math_toolkit/toolkit/internals2/minimax.html"> Minimax Approximations
+ and the Remez Algorithm</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/toolkit/internals2/error_test.html"> Relative
+ Error and Testing</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/toolkit/internals2/test_data.html"> Graphing,
+ Profiling, and Generating Test Data for Special Functions</a></span></dt>
+</dl></dd>
+</dl></dd>
+<dt><span class="section"><a href="math_toolkit/using_udt.html"> Use with User Defined Floating-Point
+ Types</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="math_toolkit/using_udt/use_ntl.html"> Using With NTL - a High-Precision
+ Floating-Point Library</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/using_udt/concepts.html"> Conceptual Requirements
+ for Real Number Types</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/using_udt/dist_concept.html"> Conceptual Requirements
+ for Distribution Types</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/using_udt/archetypes.html"> Conceptual Archetypes
+ and Testing</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Policies</span></dt>
+<dd><dl>
+<dt><span class="section"> Policy Overview</span></dt>
+<dt><span class="section"> Policy Tutorial</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="math_toolkit/policy/pol_tutorial/what_is_a_policy.html">
+ So Just What is a Policy Anyway?</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/policy/pol_tutorial/policy_tut_defaults.html">
+ Policies Have Sensible Defaults</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/policy/pol_tutorial/policy_usage.html"> So
+ How are Policies Used Anyway?</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/policy/pol_tutorial/changing_policy_defaults.html">
+ Changing the Policy Defaults</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/policy/pol_tutorial/ad_hoc_dist_policies.html">
+ Setting Policies for Distributions on an Ad Hoc Basis</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/policy/pol_tutorial/ad_hoc_sf_policies.html">
+ Changing the Policy on an Ad Hoc Basis for the Special Functions</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/policy/pol_tutorial/namespace_policies.html">
+ Setting Policies at Namespace or Translation Unit Scope</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/policy/pol_tutorial/user_def_err_pol.html">
+ Calling User Defined Error Handlers</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/policy/pol_tutorial/understand_dis_quant.html">
+ Understanding Quantiles of Discrete Distributions</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Policy Reference</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="math_toolkit/policy/pol_ref/error_handling_policies.html">
+ Error Handling Policies</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/policy/pol_ref/internal_promotion.html"> Internal
+ Promotion Policies</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/policy/pol_ref/assert_undefined.html"> Mathematically
+ Undefined Function Policies</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/policy/pol_ref/discrete_quant_ref.html"> Discrete
+ Quantile Policies</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/policy/pol_ref/precision_pol.html"> Precision
+ Policies</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/policy/pol_ref/iteration_pol.html"> Iteration
+ Limits Policies</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/policy/pol_ref/policy_defaults.html"> Using
+ macros to Change the Policy Defaults</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/policy/pol_ref/namespace_pol.html"> Setting
+ Polices at Namespace Scope</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/policy/pol_ref/pol_ref_ref.html"> Policy Class
+ Reference</a></span></dt>
+</dl></dd>
+</dl></dd>
+<dt><span class="section"> Performance</span></dt>
+<dd><dl>
+<dt><span class="section"> Performance Overview</span></dt>
+<dt><span class="section"> Interpretting these Results</span></dt>
+<dt><span class="section"><a href="math_toolkit/perf/getting_best.html"> Getting the Best Performance
+ from this Library</a></span></dt>
+<dt><span class="section"> Comparing Compilers</span></dt>
+<dt><span class="section"> Performance Tuning Macros</span></dt>
+<dt><span class="section"><a href="math_toolkit/perf/comparisons.html"> Comparisons to Other
+ Open Source Libraries</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/perf/perf_test_app.html"> The Performance Test
+ Application</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Backgrounders</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="math_toolkit/backgrounders/implementation.html"> Additional
+ Implementation Notes</a></span></dt>
+<dt><span class="section"><a href="math_toolkit/backgrounders/relative_error.html"> Relative
+ Error</a></span></dt>
+<dt><span class="section"> The Lanczos Approximation</span></dt>
+<dt><span class="section"> The Remez Method</span></dt>
+<dt><span class="section"> References</span></dt>
+</dl></dd>
+<dt><span class="section"> Library Status</span></dt>
+<dd><dl>
+<dt><span class="section"> History and What's New</span></dt>
+<dt><span class="section"> Compilers</span></dt>
+<dt><span class="section"> Known Issues, and Todo List</span></dt>
+<dt><span class="section"> Credits and Acknowledgements</span></dt>
+</dl></dd>
+</dl>
+</div>
+<p>
+ ISBN 0-9504833-2-X 978-0-9504833-2-0, Classification 519.2-dc22
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"><p><small>Last revised: October 09, 2007 at 11:19:03 GMT</small></p></td>
+<td align="right"><small></small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav"><a accesskey="n" href="math_toolkit/main_overview.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a></div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,49 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Backgrounders</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../index.html" title="Math Toolkit">
+<link rel="up" href="../index.html" title="Math Toolkit">
+<link rel="prev" href="perf/perf_test_app.html" title="The Performance Test Application">
+<link rel="next" href="backgrounders/implementation.html" title="Additional Implementation Notes">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="perf/perf_test_app.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="backgrounders/implementation.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="math_toolkit.backgrounders"></a> Backgrounders
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="backgrounders/implementation.html"> Additional
+ Implementation Notes</a></span></dt>
+<dt><span class="section"><a href="backgrounders/relative_error.html"> Relative
+ Error</a></span></dt>
+<dt><span class="section"> The Lanczos Approximation</span></dt>
+<dt><span class="section"> The Remez Method</span></dt>
+<dt><span class="section"> References</span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="perf/perf_test_app.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="backgrounders/implementation.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders/implementation.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders/implementation.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,952 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Additional Implementation Notes</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../backgrounders.html" title="Backgrounders">
+<link rel="prev" href="../backgrounders.html" title="Backgrounders">
+<link rel="next" href="relative_error.html" title="Relative Error">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../backgrounders.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="relative_error.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.backgrounders.implementation"></a><a href="implementation.html" title="Additional Implementation Notes"> Additional
+ Implementation Notes</a>
+</h3></div></div></div>
+<p>
+ The majority of the implementation notes are included with the documentation
+ of each function or distribution. The notes here are of a more general nature,
+ and reflect more the general implementation philosophy used.
+ </p>
+<a name="math_toolkit.backgrounders.implementation.implemention_philosophy"></a><h5>
+<a name="id782879"></a>
+ <a href="implementation.html#math_toolkit.backgrounders.implementation.implemention_philosophy">Implemention
+ philosophy</a>
+ </h5>
+<p>
+ "First be right, then be fast."
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ So our priority is accuracy.
+ </p>
+<p>
+ To permit evaluation of accuracy of the special functions, production of
+ extremely accurate tables of test values has received considerable effort.
+ </p>
+<p>
+ (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 <span class="bold"><strong>days</strong></span> calculating some
+ tables of test values!)
+ </p>
+<p>
+ 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).
+ </p>
+<p>
+ If these prove accurate enough to be "fit for his purpose", then
+ a user may substitute his custom specialization.
+ </p>
+<p>
+ For example, there are approximations dating back from times when computation
+ was a <span class="bold"><strong>lot</strong></span> more expensive:
+ </p>
+<p>
+ 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).
+ </p>
+<p>
+ A H Carter, Approximations to percentage points of the z-distribution, Biometrika
+ 34(2), 352 - 358 (Dec 1947).
+ </p>
+<p>
+ These could still provide sufficient accuracy for some speed-critical applications.
+ </p>
+<a name="math_toolkit.backgrounders.implementation.accuracy_and_representation_of_test_values"></a><h5>
+<a name="id782990"></a>
+ <a href="implementation.html#math_toolkit.backgrounders.implementation.accuracy_and_representation_of_test_values">Accuracy
+ and Representation of Test Values</a>
+ </h5>
+<p>
+ In order to be accurate enough for as many as possible real types, constant
+ values are given to 50 decimal digits if available (though many sources proved
+ only accurate near to 64-bit double precision). Values are specified as long
+ double types by appending L, unless they are exactly representable, for example
+ integers, or binary fractions like 0.125. This avoids the risk of loss of
+ accuracy converting from double, the default type. Values are used after
+ static_cast&lt;RealType&gt;(1.2345L) to provide the appropriate RealType
+ for spot tests.
+ </p>
+<p>
+ Functions that return constants values, like kurtosis for example, are written
+ as
+ </p>
+<p>
+ <code class="computeroutput"><span class="keyword">static_cast</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;(-</span><span class="number">3</span><span class="special">)</span> <span class="special">/</span>
+ <span class="number">5</span><span class="special">;</span></code>
+ </p>
+<p>
+ to provide the most accurate value that the compiler can compute for the
+ real type. (The denominator is an integer and so will be promoted exactly).
+ </p>
+<p>
+ So tests for one third, <span class="bold"><strong>not</strong></span> exactly representable
+ with radix two floating-point, (should) use, for example:
+ </p>
+<p>
+ <code class="computeroutput"><span class="keyword">static_cast</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;(</span><span class="number">1</span><span class="special">)</span> <span class="special">/</span>
+ <span class="number">3</span><span class="special">;</span></code>
+ </p>
+<p>
+ If a function is very sensitive to changes in input, specifying an inexact
+ value as input (such as 0.1) can throw the result off by a noticeable amount:
+ 0.1f is "wrong" by ~1e-7 for example (because 0.1 has no exact
+ binary representation). That is why exact binary values - halves, quarters,
+ and eighths etc - are used in test code along with the occasional fraction
+ <code class="computeroutput"><span class="identifier">a</span><span class="special">/</span><span class="identifier">b</span></code> with <code class="computeroutput"><span class="identifier">b</span></code>
+ a power of two (in order to ensure that the result is an exactly representable
+ binary value).
+ </p>
+<a name="math_toolkit.backgrounders.implementation.tolerance_of_tests"></a><h5>
+<a name="id783222"></a>
+ <a href="implementation.html#math_toolkit.backgrounders.implementation.tolerance_of_tests">Tolerance
+ of Tests</a>
+ </h5>
+<p>
+ The tolerances need to be set to the maximum of:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Some epsilon value.
+ </li>
+<li>
+ The accuracy of the data (often only near 64-bit double).
+ </li>
+</ul></div>
+<p>
+ Otherwise when long double has more digits than the test data, then no amount
+ of tweaking an epsilon based tolerance will work.
+ </p>
+<p>
+ A common problem is when tolerances that are suitable for implementations
+ like Microsoft VS.NET where double and long double are the same size: tests
+ fail on other systems where long double is more accurate than double. Check
+ first that the suffix L is present, and then that the tolerance is big enough.
+ </p>
+<a name="math_toolkit.backgrounders.implementation.handling_unsuitable_arguments"></a><h5>
+<a name="id783282"></a>
+ <a href="implementation.html#math_toolkit.backgrounders.implementation.handling_unsuitable_arguments">Handling
+ Unsuitable Arguments</a>
+ </h5>
+<p>
+ In <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1665.pdf" target="_top">Errors
+ in Mathematical Special Functions</a>, J. Marraffino &amp; M. Paterno
+ it is proposed that signalling a domain error is mandatory when the argument
+ would give an mathematically undefined result.
+ </p>
+<div class="itemizedlist"><ul type="disc"><li>
+ Guideline 1
+ </li></ul></div>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<p>
+ Put crudely, if the function goes to + infinity and then emerges 'round-the-back'
+ with - infinity, it is NOT defined.
+ </p>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<div class="itemizedlist"><ul type="disc"><li>
+ Guideline 2
+ </li></ul></div>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<p>
+ This implementation is believed to follow these proposals and to assist compatibility
+ with <span class="emphasis"><em>ISO/IEC 9899:1999 Programming languages - C</em></span> and
+ with the <a href="../../www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf" target="_top">Draft
+ Technical Report on C++ Library Extensions, 2005-06-24, section 5.2.1, paragraph
+ 5</a>. <a href="../main_overview/error_handling.html" title="Error Handling">See
+ also domain_error</a>.
+ </p>
+<p>
+ See policy reference for
+ details of the error handling policies that should allow a user to comply
+ with any of these recommendations, as well as other behaviour.
+ </p>
+<p>
+ See error handling
+ for a detailed explanation of the mechanism, and <a href="../dist/stat_tut/weg/error_eg.html" title="Error Handling Example">error_handling
+ example</a> and error_handling_example.cpp
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ If you enable throw but do NOT have try &amp; catch block, then the program
+ will terminate with an uncaught exception and probably abort. Therefore
+ to get the benefit of helpful error messages, enabling <span class="bold"><strong>all</strong></span>
+ exceptions <span class="bold"><strong>and</strong></span> using try&amp;catch is
+ recommended for all applications. However, for simplicity, this is not
+ done for most examples.
+ </p></td></tr>
+</table></div>
+<a name="math_toolkit.backgrounders.implementation.handling_of_functions_that_are_not_mathematically_defined"></a><h5>
+<a name="id783506"></a>
+ <a href="implementation.html#math_toolkit.backgrounders.implementation.handling_of_functions_that_are_not_mathematically_defined">Handling
+ of Functions that are Not Mathematically defined</a>
+ </h5>
+<p>
+ Functions that are not mathematically defined, like the Cauchy mean, fail
+ to compile by default. <a href="../policy/pol_ref/assert_undefined.html" title="Mathematically Undefined Function Policies">A
+ policy</a> allows control of this.
+ </p>
+<p>
+ If the policy is to permit undefined functions, then calling them throws
+ a domain error, by default. But the error policy can be set to not throw,
+ and to return NaN instead. For example,
+ </p>
+<p>
+ <code class="computeroutput"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span>
+ <span class="identifier">ignore_error</span></code>
+ </p>
+<p>
+ appears before the first Boost include, then if the un-implemented function
+ is called, mean(cauchy&lt;&gt;()) will return std::numeric_limits&lt;T&gt;::quiet_NaN().
+ </p>
+<div class="warning"><table border="0" summary="Warning">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../../doc/html/images/warning.png"></td>
+<th align="left">Warning</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ If <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">has_quiet_NaN</span></code> is false (for example T
+ is a User-defined type), then an exception will always be thrown when a
+ domain error occurs. Catching exceptions is therefore strongly recommended.
+ </p></td></tr>
+</table></div>
+<a name="math_toolkit.backgrounders.implementation.median_of_distributions"></a><h5>
+<a name="id783647"></a>
+ <a href="implementation.html#math_toolkit.backgrounders.implementation.median_of_distributions">Median
+ of distributions</a>
+ </h5>
+<p>
+ There are many distributions for which we have been unable to find an analytic
+ formula, and this has deterred us from implementing <a href="http://en.wikipedia.org/wiki/Median" target="_top">median
+ functions</a>, the mid-point in a list of values.
+ </p>
+<p>
+ However a useful median approximation for distribution <code class="computeroutput"><span class="identifier">dist</span></code>
+ may be available from
+ </p>
+<p>
+ <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="number">0.5</span><span class="special">)</span></code>.
+ </p>
+<p>
+ <a href="http://www.amstat.org/publications/jse/v13n2/vonhippel.html" target="_top">Mean,
+ Median, and Skew, Paul T von Hippel</a>
+ </p>
+<p>
+ <a href="http://documents.wolfram.co.jp/teachersedition/MathematicaBook/24.5.html" target="_top">Descriptive
+ Statistics,</a>
+ </p>
+<p>
+ <a href="http://documents.wolfram.co.jp/v5/Add-onsLinks/StandardPackages/Statistics/DescriptiveStatistics.html" target="_top">and
+ </a>
+ </p>
+<p>
+ <a href="http://documents.wolfram.com/v5/TheMathematicaBook/AdvancedMathematicsInMathematica/NumericalOperationsOnData/3.8.1.html" target="_top">Mathematica
+ Basic Statistics.</a> give more detail, in particular for discrete distributions.
+ </p>
+<a name="math_toolkit.backgrounders.implementation.handling_of_floating_point_infinity"></a><h5>
+<a name="id783792"></a>
+ <a href="implementation.html#math_toolkit.backgrounders.implementation.handling_of_floating_point_infinity">Handling
+ of Floating-Point Infinity</a>
+ </h5>
+<p>
+ Some functions and distributions are well defined with + or - infinity as
+ argument(s), but after some experiments with handling infinite arguments
+ as special cases, we concluded that it was generally more useful to forbid
+ this, and instead to return the result of domain_error.
+ </p>
+<p>
+ Handling infinity as special cases is additionally complicated because, unlike
+ built-in types on most - but not all - platforms, not all User-Defined Types
+ are specialized to provide <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">()</span></code> and would return zero rather than any representation
+ of infinity.
+ </p>
+<p>
+ The rationale is that non-finiteness may happen because of error or overflow
+ in the users code, and it will be more helpful for this to be diagnosed promptly
+ rather than just continuing. The code also became much more complicated,
+ more error-prone, much more work to test, and much less readable.
+ </p>
+<p>
+ However in a few cases, for example normal, where we felt it obvious, we
+ have permitted argument(s) to be infinity, provided infinity is implemented
+ for the realType on that implementation.
+ </p>
+<p>
+ Overflow, underflow, denorm can be handled using <a href="../policy/pol_ref/error_handling_policies.html" title="Error Handling Policies">error
+ handling policies</a>.
+ </p>
+<p>
+ We have also tried to catch boundary cases where the mathematical specification
+ would result in divide by zero or overflow and signalling these similarly.
+ What happens at (and near), poles can be controlled through <a href="../policy/pol_ref/error_handling_policies.html" title="Error Handling Policies">error
+ handling policies</a>.
+ </p>
+<a name="math_toolkit.backgrounders.implementation.scale__shape_and_location"></a><h5>
+<a name="id783940"></a>
+ <a href="implementation.html#math_toolkit.backgrounders.implementation.scale__shape_and_location">Scale,
+ Shape and Location</a>
+ </h5>
+<p>
+ We considered adding location and scale to the list of functions, for example:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">&gt;</span>
+<span class="keyword">inline</span> <span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">triangular_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="identifier">RealType</span> <span class="identifier">lower</span> <span class="special">=</span> <span class="identifier">dist</span><span class="special">.</span><span class="identifier">lower</span><span class="special">();</span>
+ <span class="identifier">RealType</span> <span class="identifier">mode</span> <span class="special">=</span> <span class="identifier">dist</span><span class="special">.</span><span class="identifier">mode</span><span class="special">();</span>
+ <span class="identifier">RealType</span> <span class="identifier">upper</span> <span class="special">=</span> <span class="identifier">dist</span><span class="special">.</span><span class="identifier">upper</span><span class="special">();</span>
+ <span class="identifier">RealType</span> <span class="identifier">result</span><span class="special">;</span> <span class="comment">// of checks.
+</span> <span class="keyword">if</span><span class="special">(</span><span class="keyword">false</span> <span class="special">==</span> <span class="identifier">detail</span><span class="special">::</span><span class="identifier">check_triangular</span><span class="special">(</span><span class="identifier">BOOST_CURRENT_FUNCTION</span><span class="special">,</span> <span class="identifier">lower</span><span class="special">,</span> <span class="identifier">mode</span><span class="special">,</span> <span class="identifier">upper</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">result</span><span class="special">))</span>
+ <span class="special">{</span>
+ <span class="keyword">return</span> <span class="identifier">result</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="keyword">return</span> <span class="special">(</span><span class="identifier">upper</span> <span class="special">-</span> <span class="identifier">lower</span><span class="special">);</span>
+<span class="special">}</span>
+</pre>
+<p>
+ but found that these concepts are not defined (or their definition too contentious)
+ for too many distributions to be generally applicable. Because they are non-member
+ functions, they can be added if required.
+ </p>
+<a name="math_toolkit.backgrounders.implementation.notes_on_implementation_of_specific_functions__amp__distributions"></a><h5>
+<a name="id784406"></a>
+ <a href="implementation.html#math_toolkit.backgrounders.implementation.notes_on_implementation_of_specific_functions__amp__distributions">Notes
+ on Implementation of Specific Functions &amp; Distributions</a>
+ </h5>
+<div class="itemizedlist"><ul type="disc"><li>
+ Default parameters for the Triangular Distribution. We are uncertain about
+ the best default parameters. Some sources suggest that the Standard Triangular
+ Distribution has lower = 0, mode = half and upper = 1. However as a approximation
+ for the normal distribution, the most common usage, lower = -1, mode =
+ 0 and upper = 1 would be more suitable.
+ </li></ul></div>
+<a name="math_toolkit.backgrounders.implementation.rational_approximations_used"></a><h5>
+<a name="id784447"></a>
+ <a href="implementation.html#math_toolkit.backgrounders.implementation.rational_approximations_used">Rational
+ Approximations Used</a>
+ </h5>
+<p>
+ Some of the special functions in this library are implemented via rational
+ approximations. These are either taken from the literature, or devised by
+ John Maddock using <a href="../toolkit/internals2/minimax.html" title="Minimax Approximations and the Remez Algorithm">our
+ Remez code</a>.
+ </p>
+<p>
+ Rational rather than Polynomial approximations are used to ensure accuracy:
+ polynomial approximations are often wonderful up to a certain level of accuracy,
+ but then quite often fail to provide much greater accuracy no matter how
+ many more terms are added.
+ </p>
+<p>
+ Our own approximations were devised either for added accuracy (to support
+ 128-bit long doubles for example), or because literature methods were unavailable
+ or under non-BSL compatible license. Our Remez code is known to produce good
+ agreement with literature results in fairly simple "toy" cases.
+ All approximations were checked for convergence and to ensure that they were
+ not ill-conditioned (the coefficients can give a theoretically good solution,
+ but the resulting rational function may be un-computable at fixed precision).
+ </p>
+<p>
+ Recomputing using different Remez implementations may well produce differing
+ coefficients: the problem is well known to be ill conditioned in general,
+ and our Remez implementation often found a broad and ill-defined minima for
+ many of these approximations (of course for simple "toy" examples
+ like approximating <code class="computeroutput"><span class="identifier">exp</span></code> the
+ minima is well defined, and the coeffiecents should agree no matter whose
+ Remez implementation is used). This should not in general effect the validity
+ of the approximations: there's good literature supporting the idea that coefficients
+ can be "in error" without necessarily adversely effecting the result.
+ Note that "in error" has a special meaning in this context, see
+ <a href="http://front.math.ucdavis.edu/0101.5042" target="_top">"Approximate construction
+ of rational approximations and the effect of error autocorrection.",
+ Grigori Litvinov, eprint arXiv:math/0101042</a>. Therefore the coefficients
+ still need to be accurately calculated, even if they can be in error compared
+ to the "true" minimax solution.
+ </p>
+<a name="math_toolkit.backgrounders.implementation.representation_of_mathematical_constants"></a><h5>
+<a name="id784563"></a>
+ <a href="implementation.html#math_toolkit.backgrounders.implementation.representation_of_mathematical_constants">Representation
+ of Mathematical Constants</a>
+ </h5>
+<p>
+ A macro BOOST_DEFINE_MATH_CONSTANT in constants.hpp is used to provide high
+ accuracy constants to mathematical functions and distributions, since it
+ is important to provide values uniformly for both built-in float, double
+ and long double types, and for User Defined types like NTL::quad_float and
+ NTL::RR.
+ </p>
+<p>
+ To permit calculations in this Math ToolKit and its tests, (and elsewhere)
+ at about 100 decimal digits with NTL::RR type, it is obviously necessary
+ to define constants to this accuracy.
+ </p>
+<p>
+ However, some compilers do not accept decimal digits strings as long as this.
+ So the constant is split into two parts, with the 1st containing at least
+ long double precision, and the 2nd zero if not needed or known. The 3rd part
+ permits an exponent to be provided if necessary (use zero if none) - the
+ other two parameters may only contain decimal digits (and sign and decimal
+ point), and may NOT include an exponent like 1.234E99 (nor a trailing F or
+ L). The second digit string is only used if T is a User-Defined Type, when
+ the constant is converted to a long string literal and lexical_casted to
+ type T. (This is necessary because you can't use a numeric constant since
+ even a long double might not have enough digits).
+ </p>
+<p>
+ For example, pi is defined:
+ </p>
+<pre class="programlisting">
+<span class="identifier">BOOST_DEFINE_MATH_CONSTANT</span><span class="special">(</span><span class="identifier">pi</span><span class="special">,</span>
+ <span class="number">3.141592653589793238462643383279502884197169399375105820974944</span><span class="special">,</span>
+ <span class="number">5923078164062862089986280348253421170679821480865132823066470938446095505</span><span class="special">,</span>
+ <span class="number">0</span><span class="special">)</span>
+</pre>
+<p>
+ And used thus:
+ </p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">constants</span><span class="special">;</span>
+
+<span class="keyword">double</span> <span class="identifier">diameter</span> <span class="special">=</span> <span class="number">1.</span><span class="special">;</span>
+<span class="keyword">double</span> <span class="identifier">radius</span> <span class="special">=</span> <span class="identifier">diameter</span> <span class="special">*</span> <span class="identifier">pi</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;();</span>
+
+<span class="keyword">or</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">constants</span><span class="special">::</span><span class="identifier">pi</span><span class="special">&lt;</span><span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span><span class="special">&gt;()</span>
+</pre>
+<p>
+ Note that it is necessary (if inconvenient) to specify the type explicitly.
+ </p>
+<p>
+ So you cannot write
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">constants</span><span class="special">::</span><span class="identifier">pi</span><span class="special">&lt;&gt;();</span> <span class="comment">// could not deduce template argument for 'T'
+</span></pre>
+<p>
+ Neither can you write:
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">constants</span><span class="special">::</span><span class="identifier">pi</span><span class="special">;</span> <span class="comment">// Context does not allow for disambiguation of overloaded function
+</span><span class="keyword">double</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">constants</span><span class="special">::</span><span class="identifier">pi</span><span class="special">();</span> <span class="comment">// Context does not allow for disambiguation of overloaded function
+</span></pre>
+<a name="math_toolkit.backgrounders.implementation.thread_safety"></a><h5>
+<a name="id785109"></a>
+ <a href="implementation.html#math_toolkit.backgrounders.implementation.thread_safety">Thread
+ safety</a>
+ </h5>
+<p>
+ Reporting of error by setting errno should be thread safe already (otherwise
+ none of the std lib math functions would be thread safe?). If you turn on
+ reporting of errors via exceptions, errno gets left unused anyway.
+ </p>
+<p>
+ Other than that, the code is intended to be thread safe <span class="bold"><strong>for
+ built in real-number types</strong></span> : so float, double and long double
+ are all thread safe.
+ </p>
+<p>
+ For non-built-in types - NTL::RR for example - initialisation of the various
+ constants used in the implementation is potentially <span class="bold"><strong>not</strong></span>
+ thread safe. This most undesiable, but it would be a signficant challenge
+ to fix it. Some compilers may offer the option of having static-constants
+ initialised in a thread safe manner (Commeau, and maybe others?), if that's
+ the case then the problem is solved. This is a topic of hot debate for the
+ next C++ std revision, so hopefully all compilers will be required to do
+ the right thing here at some point.
+ </p>
+<a name="math_toolkit.backgrounders.implementation.sources_of_test_data"></a><h5>
+<a name="id785174"></a>
+ <a href="implementation.html#math_toolkit.backgrounders.implementation.sources_of_test_data">Sources
+ of Test Data</a>
+ </h5>
+<p>
+ We found a large number of sources of test data. We have assumed that these
+ are <span class="emphasis"><em>"known good"</em></span> if they agree with the results
+ from our test and only consulted other sources for their <span class="emphasis"><em>'vote'</em></span>
+ in the case of serious disagreement. The accuracy, actual and claimed, vary
+ very widely. Only <a href="http://functions.wolfram.com/" target="_top">Wolfram Mathematica
+ functions</a> provided a higher accuracy than C++ double (64-bit floating-point)
+ and was regarded as the most-trusted source by far.
+ </p>
+<p>
+ A useful index of sources is: <a href="http://www.sal.hut.fi/Teaching/Resources/ProbStat/table.html" target="_top">Web-oriented
+ Teaching Resources in Probability and Statistics</a>
+ </p>
+<p>
+ Statlet:
+ Is a Javascript application that calculates and plots probability distributions,
+ and provides the most complete range of distributions:
+ </p>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ Bernoulli, Binomial, discrete uniform, geometric, hypergeometric, negative
+ binomial, Poisson, beta, Cauchy-Lorentz, chi-sequared, Erlang, exponential,
+ extreme value, Fisher, gamma, Laplace, logistic, lognormal, normal, Parteo,
+ Student's t, triangular, uniform, and Weibull.
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<p>
+ It calculates pdf, cdf, survivor, log survivor, hazard, tail areas, &amp;
+ critical values for 5 tail values.
+ </p>
+<p>
+ 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.
+ </p>
+<a name="math_toolkit.backgrounders.implementation.creating_and_managing_the_equations"></a><h5>
+<a name="id785284"></a>
+ <a href="implementation.html#math_toolkit.backgrounders.implementation.creating_and_managing_the_equations">Creating
+ and Managing the Equations</a>
+ </h5>
+<p>
+ The primary source for the equations is now MathML:
+ see the *.mml files in libs/math/doc/equations/.
+ </p>
+<p>
+ These are most easily edited by a GUI editor such as Mathcast,
+ please note that the equation editor supplied with Open Office currently
+ mangles these files and should not currently be used.
+ </p>
+<p>
+ Convertion to SVG was achieved using SVGMath
+ and a command line such as:
+ </p>
+<pre class="programlisting">$for file in *.mml; do
+&gt;/cygdrive/c/Python25/python.exe 'C:\download\open\SVGMath-0.3.1\math2svg.py' \
+&gt;&gt;$file &gt; $(basename $file .mml).svg
+&gt;done
+</pre>
+<p>
+ Note that SVGMath requires that the mml files are <span class="bold"><strong>not</strong></span>
+ wrapped in an XHTML XML wrapper - this is added by Mathcast by default -
+ one workaround is to copy an existing mml file and then edit it with Mathcast:
+ the existing format should then be preserved. This is a bug in the XML parser
+ used by SVGMath which the author is aware of.
+ </p>
+<p>
+ If neccessary the XHTML wrapper can be removed with:
+ </p>
+<pre class="programlisting">cat filename | tr -d "\r\n" | sed -e 's/.*\(&lt;math[^&gt;]*&gt;.*&lt;/math&gt;\).*/\1/' &gt; newfile</pre>
+<p>
+ Setting up fonts for SVGMath is currently rather tricky, on a windows system
+ JM's font setup looks like this:
+ </p>
+<pre class="programlisting">&lt;!-- MathML-to-SVG configuration file --&gt;
+&lt;config verbose<code class="literal">"true"&gt;
+ &lt;!-- Fallback font family --&gt;
+ &lt;fallback family</code>"Lucida Sans Unicode"/&gt;
+
+ &lt;!-- Default values for MathML properties. --&gt;
+ &lt;!-- Most of these are defined in the MathML Rec - change with care --&gt;
+ &lt;defaults displaystyle<code class="literal">"false"
+ mathsize</code>"12pt"
+ scriptminsize<code class="literal">"8pt"
+ scriptsizemultiplier</code>"0.71"
+ veryverythinmathspace<code class="literal">"0.0555556em"
+ verythinmathspace</code>"0.111111em"
+ thinmathspace<code class="literal">"0.166667em"
+ mediummathspace</code>"0.222222em"
+ thickmathspace<code class="literal">"0.277778em"
+ verythickmathspace</code>"0.333333em"
+ veryverythickmathspace<code class="literal">"0.388889em"
+ rowspacing</code>"1.0ex"
+ columnspacing<code class="literal">"0.8em"
+ framespacing</code>"0.4em 0.5ex"/&gt;
+
+ &lt;!-- Additional styling for individual operators --&gt;
+ &lt;!-- Make differentials italic --&gt;
+ &lt;operator-style operator<code class="literal">"&amp;#x2145;" fontstyle</code>"italic"/&gt;
+ &lt;operator-style operator<code class="literal">"&amp;#x2146;" fontstyle</code>"italic"/&gt;
+
+ &lt;!-- Font families --&gt;
+ &lt;family name<code class="literal">"Times New Roman"&gt;
+ &lt;font ttf</code>"C:\WINDOWS\Fonts\times.ttf"/&gt;
+ &lt;font weight<code class="literal">"bold" ttf</code>"C:\WINDOWS\Fonts\timesbd.ttf"/&gt;
+ &lt;font style<code class="literal">"italic" ttf</code>"C:\WINDOWS\Fonts\timesi.ttf"/&gt;
+ &lt;font weight<code class="literal">"bold" style</code>"italic" ttf<code class="literal">"C:\WINDOWS\Fonts\timesbi.ttf"\/&gt;
+ &lt;\/family&gt;
+
+ &lt;family name</code>"Arial"&gt;
+ &lt;font ttf<code class="literal">"C:\WINDOWS\Fonts\arial.ttf"\/&gt;
+ &lt;font weight</code>"bold" ttf<code class="literal">"C:\WINDOWS\Fonts\arialbd.ttf"\/&gt;
+ &lt;font style</code>"italic" ttf<code class="literal">"C:\WINDOWS\Fonts\ariali.ttf"\/&gt;
+ &lt;font weight</code>"bold" style<code class="literal">"italic" ttf</code>"C:\WINDOWS\Fonts\arialbi.ttf"/&gt;
+ &lt;/family&gt;
+
+ &lt;family name<code class="literal">"Courier New"&gt;
+ &lt;font ttf</code>"C:\WINDOWS\Fonts\cour.ttf"/&gt;
+ &lt;font weight<code class="literal">"bold" ttf</code>"C:\WINDOWS\Fonts\courbd.ttf"/&gt;
+ &lt;font style<code class="literal">"italic" ttf</code>"C:\WINDOWS\Fonts\couri.ttf"/&gt;
+ &lt;font weight<code class="literal">"bold" style</code>"italic" ttf<code class="literal">"C:\WINDOWS\Fonts\courbi.ttf"\/&gt;
+ &lt;\/family&gt;
+
+ &lt;family name</code>"Euclid Fraktur"&gt;
+ &lt;font ttf<code class="literal">"C:\WINDOWS\Fonts\eufrak.ttf"\/&gt;
+ &lt;font weight</code>"bold" ttf<code class="literal">"C:\WINDOWS\Fonts\eufrakb.ttf"\/&gt;
+ &lt;\/family&gt;
+
+ &lt;family name</code>"Monotype Corsiva"&gt;
+ &lt;font ttf<code class="literal">"C:\WINDOWS\Fonts\mtcorsva.ttf"\/&gt;
+ &lt;\/family&gt;
+
+ &lt;family name</code>"Lucida Sans Unicode"&gt;
+ &lt;font ttf<code class="literal">"C:\WINDOWS\Fonts\lsansuni.ttf"\/&gt;
+ &lt;\/family&gt;
+
+ &lt;!-- Math variant definitions --&gt;
+ &lt;!-- Serif --&gt;
+ &lt;mathvariant name</code>"normal"
+ family<code class="literal">"Times New Roman, Lucida Sans Unicode"\/&gt;
+ &lt;mathvariant name</code>"bold"
+ family<code class="literal">"Times New Roman, Lucida Sans Unicode" weight</code>"bold"/&gt;
+ &lt;mathvariant name<code class="literal">"italic"
+ family</code>"Times New Roman, Lucida Sans Unicode" style<code class="literal">"italic"\/&gt;
+ &lt;mathvariant name</code>"bold-italic"
+ family<code class="literal">"Times New Roman, Lucida Sans Unicode" weight</code>"bold" style<code class="literal">"italic"\/&gt;
+
+ &lt;!-- Sans-Serif --&gt;
+ &lt;mathvariant name</code>"sans-serif"
+ family<code class="literal">"Arial, Lucida Sans Unicode"\/&gt;
+ &lt;mathvariant name</code>"bold-sans-serif"
+ family<code class="literal">"Arial, Lucida Sans Unicode" weight</code>"bold"/&gt;
+ &lt;mathvariant name<code class="literal">"sans-serif-italic"
+ family</code>"Arial, Lucida Sans Unicode" style<code class="literal">"italic"\/&gt;
+ &lt;mathvariant name</code>"sans-serif-bold-italic"
+ family<code class="literal">"Arial, Lucida Sans Unicode" weight</code>"bold" style<code class="literal">"italic"\/&gt;
+
+ &lt;!-- Fraktur --&gt;
+ &lt;mathvariant name</code>"fraktur"
+ family<code class="literal">"Euclid Fraktur, Lucida Sans Unicode"\/&gt;
+ &lt;mathvariant name</code>"bold-fraktur"
+ family<code class="literal">"Euclid Fraktur, Lucida Sans Unicode" weight</code>"bold"/&gt;
+
+ &lt;!-- Script --&gt;
+ &lt;mathvariant name<code class="literal">"script"
+ family</code>"Monotype Corsiva, Lucida Sans Unicode"/&gt;
+ &lt;mathvariant name<code class="literal">"bold-script"
+ family</code>"Monotype Corsiva, Lucida Sans Unicode" weight<code class="literal">"bold"\/&gt;
+
+ &lt;!-- Monospace --&gt;
+ &lt;mathvariant name</code>"monospace" family<code class="literal">"Courier New, Lucida Sans Unicode"\/&gt;
+
+ &lt;!-- Double-struck --&gt;
+ &lt;mathvariant name</code>"double-struck" family="Lucida Sans Unicode"/&gt;
+&lt;/config&gt;
+</pre>
+<p>
+ Note that unlike the sample config file supplied with SVGMath this does not
+ make use of the Mathematica 7 font as this lacks sufficient Unicode information
+ for it to be used with either SVGMath or XEP "as is".
+ </p>
+<p>
+ Also note that the SVG files in the repository are almost certainly Windows-specific
+ since they reference various Windows Fonts.
+ </p>
+<p>
+ PNG files can be created from the SVG's using Batik
+ and a command such as:
+ </p>
+<pre class="programlisting">java -jar 'C:\download\open\batik-1.7\batik-rasterizer.jar' -dpi 120 *.svg</pre>
+<p>
+ The PDF is generated using:
+ </p>
+<pre class="programlisting">$bjam -a pdf xsl:param<code class="literal">admon.graphics.extension</code>".svg" \
+&gt;xsl:param=use.role.for.mediaobject=1 xsl:param=preferred.mediaobject.role=print</pre>
+<p>
+ Note that XEP will have to be configured to <span class="bold"><strong>use and
+ embed</strong></span> whatever fonts are used by the SVG equations. JM's XEP config
+ file looks like:
+ </p>
+<pre class="programlisting">&lt;?xml version<code class="literal">"1.0" encoding</code>"UTF-8"?&gt;
+&lt;config&gt;
+
+ &lt;!-- <code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code>= --&gt;
+ &lt;!-- Formatter options --&gt;
+ &lt;!-- <code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code>= --&gt;
+ &lt;options&gt;
+ &lt;option name<code class="literal">"LICENSE" value</code>"license.xml"/&gt;
+ &lt;option name<code class="literal">"TMPDIR" value</code>"none"/&gt;
+ &lt;option name<code class="literal">"BROKENIMAGE" value</code>"images/404.gif"/&gt;
+ &lt;option name<code class="literal">"LOGO" value</code>"images/logo-renderx.svg"/&gt;
+
+ &lt;!-- Backend options --&gt;
+ &lt;generator-options format<code class="literal">"PDF"&gt;
+ &lt;!-- &lt;option name</code>"COMPRESS" value<code class="literal">"false"\/&gt; --&gt;
+ &lt;!-- &lt;option name</code>"PDF_VERSION" value<code class="literal">"1.3"\/&gt; --&gt;
+ &lt;\/generator-options&gt;
+
+ &lt;generator-options format</code>"PostScript"&gt;
+ &lt;!-- &lt;option name<code class="literal">"LANGUAGE_LEVEL" value</code>"2"/&gt; --&gt;
+ &lt;!-- &lt;option name<code class="literal">"CLONE_EPS" value</code>"true"/&gt; --&gt;
+ &lt;/generator-options&gt;
+
+ &lt;generator-options format<code class="literal">"AFP"&gt;
+ &lt;option name</code>"AFPCodepageTxt" value<code class="literal">"Cp500"\/&gt;
+ &lt;option name</code>"AFPCodepage" value<code class="literal">"T1V10500"\/&gt;
+ &lt;option name</code>"AFPLogLevel" value<code class="literal">"0"\/&gt;
+ &lt;option name</code>"USE_PTOCA_LEVEL" value<code class="literal">"3"\/&gt;
+ &lt;option name</code>"USE_BCOCA_LEVEL" value<code class="literal">"1"\/&gt;
+ &lt;option name</code>"USE_GOCA_LEVEL" value<code class="literal">"1"\/&gt;
+ &lt;option name</code>"RESOLUTION" value<code class="literal">"1440"\/&gt;
+ &lt;!-- &lt;option name</code>"AFPGrayImage" value<code class="literal">"yes"\/&gt; --&gt;
+ &lt;option name</code>"USE_SHADING_PATTERNS" value<code class="literal">"yes"\/&gt;
+ &lt;option name</code>"USE_REPLICATE_AND_TRIM" value<code class="literal">"yes"\/&gt;
+ &lt;option name</code>"SHADING_PATTERN_RESOLUTION" value<code class="literal">"0.25"\/&gt;
+ &lt;option name</code>"TRY_USING_TIFF_COMPRESSION" value<code class="literal">"yes"\/&gt;
+ &lt;option name</code>"AFPFont,Helvetica" value<code class="literal">"C0H200.0, C0H300.0, C0H400.0, C0H500.0, C0H201.0, C0H301.0, C0H401.0, C0H501.0, 278"\/&gt;
+ &lt;option name</code>"AFPFont,Times" value<code class="literal">"C0N200.0, C0N300.0, C0N400.0, C0N500.0, C0N201.0, C0N301.0, C0N401.0, C0N501.0, 250"\/&gt;
+ &lt;option name</code>"AFPFont,Courier" value<code class="literal">"C04200.0, C04300.0, C04400.0, C04500.0, C04201.0, C04301.0, C04401.0, C04501.0, 600"\/&gt;
+ &lt;option name</code>"AFPFont,Arial" value<code class="literal">"C0H200.0, C0H300.0, C0H400.0, C0H500.0, C0H201.0, C0H301.0, C0H401.0, C0H501.0, 278"\/&gt;
+ &lt;option name</code>"AFPFont,Times New Roman" value<code class="literal">"C0N200.0, C0N300.0, C0N400.0, C0N500.0, C0N201.0, C0N301.0, C0N401.0, C0N501.0, 250"\/&gt;
+ &lt;option name</code>"AFPFont,Verdana" value<code class="literal">"C0VE0.0, C0VEI.0, C0VEB.0, C0VEZ.0, C0H201.0, C0H301.0, C0H401.0, C0H501.0,278"\/&gt;
+ &lt;option name</code>"AFPFont,Interstate" value<code class="literal">"C0IS0.0, C0ISB.0, C0IS0.0, C0ISB.0, C0H201.0, C0H301.0, C0H401.0, C0H501.0, 278"\/&gt;
+ &lt;\/generator-options&gt;
+ &lt;\/options&gt;
+
+ &lt;!-- =</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">= --&gt;
+ &lt;!-- Fonts --&gt;
+ &lt;!-- =</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">= --&gt;
+
+ &lt;fonts xml:base</code>"fonts/" default-family<code class="literal">"Helvetica"&gt;
+
+ &lt;!-- Base Adobe fonts. --&gt;
+ &lt;font-group label</code>"Base 14" embed<code class="literal">"false"&gt;
+ &lt;font-family name</code>"Courier"&gt;
+ &lt;font&gt;&lt;font-data afm<code class="literal">"Courier.afm"\/&gt;&lt;\/font&gt;
+ &lt;font style</code>"oblique"&gt;&lt;font-data afm<code class="literal">"Courier-Oblique.afm"\/&gt;&lt;\/font&gt;
+ &lt;font weight</code>"bold"&gt;&lt;font-data afm<code class="literal">"Courier-Bold.afm"\/&gt;&lt;\/font&gt;
+ &lt;font weight</code>"bold" style<code class="literal">"oblique"&gt;&lt;font-data afm</code>"Courier-BoldOblique.afm"/&gt;&lt;/font&gt;
+ &lt;/font-family&gt;
+
+ &lt;font-family name<code class="literal">"Helvetica"&gt;
+ &lt;font&gt;&lt;font-data afm</code>"Helvetica.afm"/&gt;&lt;/font&gt;
+ &lt;font style<code class="literal">"oblique"&gt;&lt;font-data afm</code>"Helvetica-Oblique.afm"/&gt;&lt;/font&gt;
+ &lt;font weight<code class="literal">"bold"&gt;&lt;font-data afm</code>"Helvetica-Bold.afm"/&gt;&lt;/font&gt;
+ &lt;font weight<code class="literal">"bold" style</code>"oblique"&gt;&lt;font-data afm<code class="literal">"Helvetica-BoldOblique.afm"\/&gt;&lt;\/font&gt;
+ &lt;\/font-family&gt;
+
+ &lt;font-family name</code>"Times" ligatures<code class="literal">"&#64257; &#64258;"&gt;
+ &lt;font&gt;&lt;font-data afm</code>"Times-Roman.afm"/&gt;&lt;/font&gt;
+ &lt;font style<code class="literal">"italic"&gt;&lt;font-data afm</code>"Times-Italic.afm"/&gt;&lt;/font&gt;
+ &lt;font weight<code class="literal">"bold"&gt;&lt;font-data afm</code>"Times-Bold.afm"/&gt;&lt;/font&gt;
+ &lt;font weight<code class="literal">"bold" style</code>"italic"&gt;&lt;font-data afm<code class="literal">"Times-BoldItalic.afm"\/&gt;&lt;\/font&gt;
+ &lt;\/font-family&gt;
+
+ &lt;font-family name</code>"Symbol"&gt;
+ &lt;font&gt;&lt;font-data afm<code class="literal">"Symbol.afm"\/&gt;&lt;\/font&gt;
+ &lt;\/font-family&gt;
+
+ &lt;font-family name</code>"ZapfDingbats"&gt;
+ &lt;font&gt;&lt;font-data afm<code class="literal">"ZapfDingbats.afm"\/&gt;&lt;\/font&gt;
+ &lt;\/font-family&gt;
+ &lt;\/font-group&gt;
+
+ &lt;!-- Other Type1 fonts --&gt;
+ &lt;font-group label</code>"Assorted Type 1" embed<code class="literal">"true"&gt;
+ &lt;font-family name</code>"OmegaSerifIPA"&gt;
+ &lt;font&gt;&lt;font-data afm<code class="literal">"IPA.afm" pfa</code>"IPA.pfa" glyph-list<code class="literal">"IPA.glyphs"\/&gt;&lt;\/font&gt;
+ &lt;\/font-family&gt;
+ &lt;font-alias name</code>"OmegaIPA" value<code class="literal">"OmegaSerifIPA"\/&gt;
+ &lt;font-alias name</code>"Phonetic" value<code class="literal">"OmegaSerifIPA"\/&gt;
+ &lt;\/font-group&gt;
+
+ &lt;!-- Sample configuration for Windows TrueType fonts. --&gt;
+
+ &lt;font-group xml:base</code>"file:/C:/Windows/Fonts/" label<code class="literal">"Windows TrueType" embed</code>"true" subset<code class="literal">"true"&gt;
+ &lt;font-family name</code>"Arial"&gt;
+ &lt;font&gt;&lt;font-data ttf<code class="literal">"arial.ttf"\/&gt;&lt;\/font&gt;
+ &lt;font style</code>"oblique"&gt;&lt;font-data ttf<code class="literal">"ariali.ttf"\/&gt;&lt;\/font&gt;
+ &lt;font weight</code>"bold"&gt;&lt;font-data ttf<code class="literal">"arialbd.ttf"\/&gt;&lt;\/font&gt;
+ &lt;font weight</code>"bold" style<code class="literal">"oblique"&gt;&lt;font-data ttf</code>"arialbi.ttf"/&gt;&lt;/font&gt;
+ &lt;/font-family&gt;
+
+ &lt;font-family name<code class="literal">"Times New Roman" ligatures</code>"&amp;#xFB01; &amp;#xFB02;"&gt;
+ &lt;font&gt;&lt;font-data ttf<code class="literal">"times.ttf"\/&gt;&lt;\/font&gt;
+ &lt;font style</code>"italic"&gt;&lt;font-data ttf<code class="literal">"timesi.ttf"\/&gt;&lt;\/font&gt;
+ &lt;font weight</code>"bold"&gt;&lt;font-data ttf<code class="literal">"timesbd.ttf"\/&gt;&lt;\/font&gt;
+ &lt;font weight</code>"bold" style<code class="literal">"italic"&gt;&lt;font-data ttf</code>"timesbi.ttf"/&gt;&lt;/font&gt;
+ &lt;/font-family&gt;
+
+ &lt;font-family name<code class="literal">"Courier New"&gt;
+ &lt;font&gt;&lt;font-data ttf</code>"cour.ttf"/&gt;&lt;/font&gt;
+ &lt;font style<code class="literal">"oblique"&gt;&lt;font-data ttf</code>"couri.ttf"/&gt;&lt;/font&gt;
+ &lt;font weight<code class="literal">"bold"&gt;&lt;font-data ttf</code>"courbd.ttf"/&gt;&lt;/font&gt;
+ &lt;font weight<code class="literal">"bold" style</code>"oblique"&gt;&lt;font-data ttf<code class="literal">"courbi.ttf"\/&gt;&lt;\/font&gt;
+ &lt;\/font-family&gt;
+
+ &lt;font-family name</code>"Tahoma" embed<code class="literal">"true"&gt;
+ &lt;font&gt;&lt;font-data ttf</code>"tahoma.ttf"/&gt;&lt;/font&gt;
+ &lt;font weight<code class="literal">"bold"&gt;&lt;font-data ttf</code>"tahomabd.ttf"/&gt;&lt;/font&gt;
+ &lt;/font-family&gt;
+
+ &lt;font-family name<code class="literal">"Verdana" embed</code>"true"&gt;
+ &lt;font&gt;&lt;font-data ttf<code class="literal">"verdana.ttf"\/&gt;&lt;\/font&gt;
+ &lt;font style</code>"oblique"&gt;&lt;font-data ttf<code class="literal">"verdanai.ttf"\/&gt;&lt;\/font&gt;
+ &lt;font weight</code>"bold"&gt;&lt;font-data ttf<code class="literal">"verdanab.ttf"\/&gt;&lt;\/font&gt;
+ &lt;font weight</code>"bold" style<code class="literal">"oblique"&gt;&lt;font-data ttf</code>"verdanaz.ttf"/&gt;&lt;/font&gt;
+ &lt;/font-family&gt;
+
+ &lt;font-family name<code class="literal">"Palatino" embed</code>"true" ligatures<code class="literal">"&amp;#xFB00; &amp;#xFB01; &amp;#xFB02; &amp;#xFB03; &amp;#xFB04;"&gt;
+ &lt;font&gt;&lt;font-data ttf</code>"pala.ttf"/&gt;&lt;/font&gt;
+ &lt;font style<code class="literal">"italic"&gt;&lt;font-data ttf</code>"palai.ttf"/&gt;&lt;/font&gt;
+ &lt;font weight<code class="literal">"bold"&gt;&lt;font-data ttf</code>"palab.ttf"/&gt;&lt;/font&gt;
+ &lt;font weight<code class="literal">"bold" style</code>"italic"&gt;&lt;font-data ttf<code class="literal">"palabi.ttf"\/&gt;&lt;\/font&gt;
+ &lt;\/font-family&gt;
+
+ &lt;font-family name</code>"Lucida Sans Unicode"&gt;
+ &lt;font&gt;&lt;font-data ttf<code class="literal">"lsansuni.ttf"\/&gt;&lt;\/font&gt;
+ &lt;\/font-family&gt;
+
+ &lt;\/font-group&gt;
+
+ &lt;!-- Required aliases --&gt;
+ &lt;font-alias name</code>"monospace" value<code class="literal">"Courier"\/&gt;
+ &lt;font-alias name</code>"sans-serif" value<code class="literal">"Helvetica"\/&gt;
+ &lt;font-alias name</code>"serif" value<code class="literal">"Times"\/&gt;
+ &lt;font-alias name</code>"cursive" value<code class="literal">"Times"\/&gt;
+ &lt;font-alias name</code>"fantasy" value<code class="literal">"Times"\/&gt;
+ &lt;\/fonts&gt;
+
+ &lt;!-- =</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">= --&gt;
+ &lt;!-- Language-specific data: hyphenation, line breaking, etc --&gt;
+ &lt;!-- =</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">=</code><code class="literal">= --&gt;
+ &lt;languages default-language</code>"en-US" xml:base<code class="literal">"hyphen\/"&gt;
+
+ &lt;language name</code>"English (US)" codes<code class="literal">"none en-US eng-US"&gt;
+ &lt;hyphenation pattern</code>"hyphen.tex"/&gt;
+ &lt;/language&gt;
+
+ &lt;language name<code class="literal">"English (UK)" codes</code>"en-GB eng-GB en eng"&gt;
+ &lt;hyphenation pattern<code class="literal">"ukhyphen.tex"\/&gt;
+ &lt;\/language&gt;
+
+ &lt;language name</code>"Russian" codes<code class="literal">"ru rus"&gt;
+ &lt;hyphenation pattern</code>"ruhyphal.tex" encoding<code class="literal">"koi8-r"\/&gt;
+ &lt;\/language&gt;
+
+ &lt;language name</code>"French" codes<code class="literal">"fr fra fre"&gt;
+ &lt;hyphenation pattern</code>"frhyph_rx.tex"/&gt;
+ &lt;/language&gt;
+
+ &lt;language name<code class="literal">"German" codes</code>"de deu ger"&gt;
+ &lt;hyphenation pattern<code class="literal">"dehyph_rx.tex"\/&gt;
+ &lt;\/language&gt;
+
+ &lt;language name</code>"Spanish" codes<code class="literal">"es esl spa"&gt;
+ &lt;hyphenation pattern</code>"eshyph_rx.tex"/&gt;
+ &lt;/language&gt;
+
+ &lt;language name<code class="literal">"Polish" codes</code>"pl pol"&gt;
+ &lt;hyphenation pattern="plhyph_rx.tex"/&gt;
+ &lt;/language&gt;
+
+ &lt;/languages&gt;
+
+&lt;/config&gt;
+</pre>
+<p>
+ XZ authored his equations using the venerable Latex, JM converted these to
+ MathML using mxlatex.
+ This process is currently unreliable and required some manual intervention:
+ consequently Latex source is not considered a viable route for the automatic
+ production of SVG versions of equations.
+ </p>
+<p>
+ Equations are embedded in the quickbook source using the <span class="emphasis"><em>equation</em></span>
+ template defined in math.qbk. This outputs Docbook XML that looks like:
+ </p>
+<pre class="programlisting">&lt;inlinemediaobject&gt;
+&lt;imageobject role<code class="literal">"html"&gt;
+&lt;imagedata fileref</code>"../equations/myfile.png"&gt;&lt;/imagedata&gt;
+&lt;/imageobject&gt;
+&lt;imageobject role<code class="literal">"print"&gt;
+&lt;imagedata fileref</code>"../equations/myfile.svg"&gt;&lt;/imagedata&gt;
+&lt;/imageobject&gt;
+&lt;/inlinemediaobject&gt;
+</pre>
+<p>
+ MathML is not currently present in the Docbook output, or in the generated
+ HTML: this needs further investigation.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../backgrounders.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="relative_error.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders/lanczos.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders/lanczos.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,574 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>The Lanczos Approximation</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../backgrounders.html" title="Backgrounders">
+<link rel="prev" href="relative_error.html" title="Relative Error">
+<link rel="next" href="remez.html" title="The Remez Method">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="relative_error.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="remez.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.backgrounders.lanczos"></a> The Lanczos Approximation
+</h3></div></div></div>
+<a name="math_toolkit.backgrounders.lanczos.motivation"></a><h5>
+<a name="id787625"></a>
+ Motivation
+ </h5>
+<p>
+ <span class="emphasis"><em>Why base gamma and gamma-like functions on the Lanczos approximation?</em></span>
+ </p>
+<p>
+ First of all I should make clear that for the gamma function over real numbers
+ (as opposed to complex ones) the Lanczos approximation (See <a href="http://en.wikipedia.org/wiki/Lanczos_approximation" target="_top">Wikipedia
+ or </a> Mathworld)
+ appears to offer no clear advantage over more traditional methods such as
+ <a href="http://en.wikipedia.org/wiki/Stirling_approximation" target="_top">Stirling's
+ approximation</a>. Pugh carried out an extensive
+ comparison of the various methods available and discovered that they were
+ all very similar in terms of complexity and relative error. However, the
+ Lanczos approximation does have a couple of properties that make it worthy
+ of further consideration:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ The approximation has an easy to compute truncation error that holds for
+ all <span class="emphasis"><em>z &gt; 0</em></span>. In practice that means we can use the
+ same approximation for all <span class="emphasis"><em>z &gt; 0</em></span>, and be certain
+ that no matter how large or small <span class="emphasis"><em>z</em></span> is, the truncation
+ error will <span class="emphasis"><em>at worst</em></span> be bounded by some finite value.
+ </li>
+<li>
+ The approximation has a form that is particularly amenable to analytic
+ manipulation, in particular ratios of gamma or gamma-like functions are
+ particularly easy to compute without resorting to logarithms.
+ </li>
+</ul></div>
+<p>
+ It is the combination of these two properties that make the approximation
+ attractive: Stirling's approximation is highly accurate for large z, and
+ has some of the same analytic properties as the Lanczos approximation, but
+ can't easily be used across the whole range of z.
+ </p>
+<p>
+ As the simplest example, consider the ratio of two gamma functions: one could
+ compute the result via lgamma:
+ </p>
+<pre class="programlisting">
+<span class="identifier">exp</span><span class="special">(</span><span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">a</span><span class="special">)</span> <span class="special">-</span> <span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">b</span><span class="special">));</span>
+</pre>
+<p>
+ However, even if lgamma is uniformly accurate to 0.5ulp, the worst case relative
+ error in the above can easily be shown to be:
+ </p>
+<pre class="programlisting">
+<span class="identifier">Erel</span> <span class="special">&gt;</span> <span class="identifier">a</span> <span class="special">*</span> <span class="identifier">log</span><span class="special">(</span><span class="identifier">a</span><span class="special">)/</span><span class="number">2</span> <span class="special">+</span> <span class="identifier">b</span> <span class="special">*</span> <span class="identifier">log</span><span class="special">(</span><span class="identifier">b</span><span class="special">)/</span><span class="number">2</span>
+</pre>
+<p>
+ For small <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span> that's not a
+ problem, but to put the relationship another way: <span class="emphasis"><em>each time a and
+ b increase in magnitude by a factor of 10, at least one decimal digit of
+ precision will be lost.</em></span>
+ </p>
+<p>
+ In contrast, by analytically combining like power terms in a ratio of Lanczos
+ approximation's, these errors can be virtually eliminated for small <span class="emphasis"><em>a</em></span>
+ and <span class="emphasis"><em>b</em></span>, and kept under control for very large (or very
+ small for that matter) <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span>.
+ Of course, computing large powers is itself a notoriously hard problem, but
+ even so, analytic combinations of Lanczos approximations can make the difference
+ between obtaining a valid result, or simply garbage. Refer to the implementation
+ notes for the beta
+ function for an example of this method in practice. The incomplete gamma_p gamma and
+ beta functions
+ use similar analytic combinations of power terms, to combine gamma and beta
+ functions divided by large powers into single (simpler) expressions.
+ </p>
+<a name="math_toolkit.backgrounders.lanczos.the_approximation"></a><h5>
+<a name="id788005"></a>
+ <a href="lanczos.html#math_toolkit.backgrounders.lanczos.the_approximation">The
+ Approximation</a>
+ </h5>
+<p>
+ The Lanczos Approximation to the Gamma Function is given by:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../equations/lanczos0.png"></span>
+ </p>
+<p>
+ Where S<sub>g</sub>(z) is an infinite sum, that is convergent for all z &gt; 0, and
+ <span class="emphasis"><em>g</em></span> is an arbitrary parameter that controls the "shape"
+ of the terms in the sum which is given by:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../equations/lanczos0a.png"></span>
+ </p>
+<p>
+ With individual coefficients defined in closed form by:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../equations/lanczos0b.png"></span>
+ </p>
+<p>
+ However, evaluation of the sum in that form can lead to numerical instability
+ in the computation of the ratios of rising and falling factorials (effectively
+ we're multiplying by a series of numbers very close to 1, so roundoff errors
+ can accumulate quite rapidly).
+ </p>
+<p>
+ The Lanczos approximation is therefore often written in partial fraction
+ form with the leading constants absorbed by the coefficients in the sum:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../equations/lanczos1.png"></span>
+ </p>
+<p>
+ where:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../equations/lanczos2.png"></span>
+ </p>
+<p>
+ Again parameter <span class="emphasis"><em>g</em></span> is an arbitrarily chosen constant,
+ and <span class="emphasis"><em>N</em></span> is an arbitrarily chosen number of terms to evaluate
+ in the "Lanczos sum" part.
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ Some authors choose to define the sum from k=1 to N, and hence end up with
+ N+1 coefficients. This happens to confuse both the following discussion
+ and the code (since C++ deals with half open array ranges, rather than
+ the closed range of the sum). This convention is consistent with Godfrey, but not Pugh,
+ so take care when referring to the literature in this field.
+ </p></td></tr>
+</table></div>
+<a name="math_toolkit.backgrounders.lanczos.computing_the_coefficients"></a><h5>
+<a name="id788268"></a>
+ <a href="lanczos.html#math_toolkit.backgrounders.lanczos.computing_the_coefficients">Computing
+ the Coefficients</a>
+ </h5>
+<p>
+ The coefficients C0..CN-1 need to be computed from <span class="emphasis"><em>N</em></span>
+ and <span class="emphasis"><em>g</em></span> at high precision, and then stored as part of
+ the program. Calculation of the coefficients is performed via the method
+ of Godfrey; let the constants be contained
+ in a column vector P, then:
+ </p>
+<p>
+ P = B D C F
+ </p>
+<p>
+ where B is an NxN matrix:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../equations/lanczos4.png"></span>
+ </p>
+<p>
+ D is an NxN matrix:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../equations/lanczos3.png"></span>
+ </p>
+<p>
+ C is an NxN matrix:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../equations/lanczos5.png"></span>
+ </p>
+<p>
+ and F is an N element column vector:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../equations/lanczos6.png"></span>
+ </p>
+<p>
+ Note than the matrices B, D and C contain all integer terms and depend only
+ on <span class="emphasis"><em>N</em></span>, this product should be computed first, and then
+ multiplied by <span class="emphasis"><em>F</em></span> as the last step.
+ </p>
+<a name="math_toolkit.backgrounders.lanczos.choosing_the_right_parameters"></a><h5>
+<a name="id788474"></a>
+ <a href="lanczos.html#math_toolkit.backgrounders.lanczos.choosing_the_right_parameters">Choosing
+ the Right Parameters</a>
+ </h5>
+<p>
+ The trick is to choose <span class="emphasis"><em>N</em></span> and <span class="emphasis"><em>g</em></span>
+ to give the desired level of accuracy: choosing a small value for <span class="emphasis"><em>g</em></span>
+ leads to a strictly convergent series, but one which converges only slowly.
+ Choosing a larger value of <span class="emphasis"><em>g</em></span> causes the terms in the
+ series to be large and/or divergent for about the first <span class="emphasis"><em>g-1</em></span>
+ terms, and to then suddenly converge with a "crunch".
+ </p>
+<p>
+ Pugh has determined the optimal value of <span class="emphasis"><em>g</em></span>
+ for <span class="emphasis"><em>N</em></span> in the range <span class="emphasis"><em>1 &lt;= N &lt;= 60</em></span>:
+ unfortunately in practice choosing these values leads to cancellation errors
+ in the Lanczos sum as the largest term in the (alternating) series is approximately
+ 1000 times larger than the result. These optimal values appear not to be
+ useful in practice unless the evaluation can be done with a number of guard
+ digits <span class="emphasis"><em>and</em></span> the coefficients are stored at higher precision
+ than that desired in the result. These values are best reserved for say,
+ computing to float precision with double precision arithmetic.
+ </p>
+<div class="table">
+<a name="id788557"></a><p class="title"><b>Table 43. Optimal choices for N and g when computing with
+ guard digits (source: Pugh)</b></p>
+<div class="table-contents"><table class="table" summary="Optimal choices for N and g when computing with
+ guard digits (source: Pugh)">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ N
+ </p>
+ </th>
+<th>
+ <p>
+ g
+ </p>
+ </th>
+<th>
+ <p>
+ Max Error
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 24
+ </p>
+ </td>
+<td>
+ <p>
+ 6
+ </p>
+ </td>
+<td>
+ <p>
+ 5.581
+ </p>
+ </td>
+<td>
+ <p>
+ 9.51e-12
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ 13
+ </p>
+ </td>
+<td>
+ <p>
+ 13.144565
+ </p>
+ </td>
+<td>
+ <p>
+ 9.2213e-23
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><p>
+ The alternative described by Godfrey is to
+ perform an exhaustive search of the <span class="emphasis"><em>N</em></span> and <span class="emphasis"><em>g</em></span>
+ parameter space to determine the optimal combination for a given <span class="emphasis"><em>p</em></span>
+ digit floating-point type. Repeating this work found a good approximation
+ for double precision arithmetic (close to the one Godfrey
+ found), but failed to find really good approximations for 80 or 128-bit long
+ doubles. Further it was observed that the approximations obtained tended
+ to optimised for the small values of z (1 &lt; z &lt; 200) used to test the
+ implementation against the factorials. Computing ratios of gamma functions
+ with large arguments were observed to suffer from error resulting from the
+ truncation of the Lancozos series.
+ </p>
+<p>
+ Pugh identified all the locations where the theoretical
+ error of the approximation were at a minimum, but unfortunately has published
+ only the largest of these minima. However, he makes the observation that
+ the minima coincide closely with the location where the first neglected term
+ (a<sub>N</sub>) in the Lanczos series S<sub>g</sub>(z) changes sign. These locations are quite
+ easy to locate, albeit with considerable computer time. These "sweet
+ spots" need only be computed once, tabulated, and then searched when
+ required for an approximation that delivers the required precision for some
+ fixed precision type.
+ </p>
+<p>
+ Unfortunately, following this path failed to find a really good approximation
+ for 128-bit long doubles, and those found for 64 and 80-bit reals required
+ an excessive number of terms. There are two competing issues here: high precision
+ requires a large value of <span class="emphasis"><em>g</em></span>, but avoiding cancellation
+ errors in the evaluation requires a small <span class="emphasis"><em>g</em></span>.
+ </p>
+<p>
+ At this point note that the Lanczos sum can be converted into rational form
+ (a ratio of two polynomials, obtained from the partial-fraction form using
+ polynomial arithmetic), and doing so changes the coefficients so that <span class="emphasis"><em>they
+ are all positive</em></span>. That means that the sum in rational form can
+ be evaluated without cancellation error, albeit with double the number of
+ coefficients for a given N. Repeating the search of the "sweet spots",
+ this time evaluating the Lanczos sum in rational form, and testing only those
+ "sweet spots" whose theoretical error is less than the machine
+ epsilon for the type being tested, yielded good approximations for all the
+ types tested. The optimal values found were quite close to the best cases
+ reported by Pugh (just slightly larger <span class="emphasis"><em>N</em></span>
+ and slightly smaller <span class="emphasis"><em>g</em></span> for a given precision than Pugh reports), and even though converting to rational
+ form doubles the number of stored coefficients, it should be noted that half
+ of them are integers (and therefore require less storage space) and the approximations
+ require a smaller <span class="emphasis"><em>N</em></span> than would otherwise be required,
+ so fewer floating point operations may be required overall.
+ </p>
+<p>
+ The following table shows the optimal values for <span class="emphasis"><em>N</em></span> and
+ <span class="emphasis"><em>g</em></span> when computing at fixed precision. These should be
+ taken as work in progress: there are no values for 106-bit significand machines
+ (Darwin long doubles &amp; NTL quad_float), and further optimisation of the
+ values of <span class="emphasis"><em>g</em></span> may be possible. Errors given in the table
+ are estimates of the error due to truncation of the Lanczos infinite series
+ to <span class="emphasis"><em>N</em></span> terms. They are calculated from the sum of the
+ first five neglected terms - and are known to be rather pessimistic estimates
+ - although it is noticeable that the best combinations of <span class="emphasis"><em>N</em></span>
+ and <span class="emphasis"><em>g</em></span> occurred when the estimated truncation error almost
+ exactly matches the machine epsilon for the type in question.
+ </p>
+<div class="table">
+<a name="id788884"></a><p class="title"><b>Table 44. Optimum value for N and g when computing at fixed
+ precision</b></p>
+<div class="table-contents"><table class="table" summary="Optimum value for N and g when computing at fixed
+ precision">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform/Compiler Used
+ </p>
+ </th>
+<th>
+ <p>
+ N
+ </p>
+ </th>
+<th>
+ <p>
+ g
+ </p>
+ </th>
+<th>
+ <p>
+ Max Truncation Error
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 24
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, VC++ 7.1
+ </p>
+ </td>
+<td>
+ <p>
+ 6
+ </p>
+ </td>
+<td>
+ <p>
+ 1.428456135094165802001953125
+ </p>
+ </td>
+<td>
+ <p>
+ 9.41e-007
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, VC++ 7.1
+ </p>
+ </td>
+<td>
+ <p>
+ 13
+ </p>
+ </td>
+<td>
+ <p>
+ 6.024680040776729583740234375
+ </p>
+ </td>
+<td>
+ <p>
+ 3.23e-016
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Suse Linux 9 IA64, gcc-3.3.3
+ </p>
+ </td>
+<td>
+ <p>
+ 17
+ </p>
+ </td>
+<td>
+ <p>
+ 12.2252227365970611572265625
+ </p>
+ </td>
+<td>
+ <p>
+ 2.34e-024
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 116
+ </p>
+ </td>
+<td>
+ <p>
+ HP Tru64 Unix 5.1B / Alpha, Compaq C++ V7.1-006
+ </p>
+ </td>
+<td>
+ <p>
+ 24
+ </p>
+ </td>
+<td>
+ <p>
+ 20.3209821879863739013671875
+ </p>
+ </td>
+<td>
+ <p>
+ 4.75e-035
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><p>
+ Finally note that the Lanczos approximation can be written as follows by
+ removing a factor of exp(g) from the denominator, and then dividing all the
+ coefficients by exp(g):
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../equations/lanczos7.png"></span>
+ </p>
+<p>
+ This form is more convenient for calculating lgamma, but for the gamma function
+ the division by <span class="emphasis"><em>e</em></span> turns a possibly exact quality into
+ an inexact value: this reduces accuracy in the common case that the input
+ is exact, and so isn't used for the gamma function.
+ </p>
+<a name="math_toolkit.backgrounders.lanczos.references"></a><h5>
+<a name="id789162"></a>
+ References
+ </h5>
+<a name="godfrey"></a><a name="pugh"></a><div class="orderedlist"><ol type="1">
+<li>
+ Paul Godfrey, <a href="http://my.fit.edu/~gabdo/gamma.txt" target="_top">"A note
+ on the computation of the convergent Lanczos complex Gamma approximation"</a>.
+ </li>
+<li>
+ Glendon Ralph Pugh, <a href="http://bh0.physics.ubc.ca/People/matt/Doc/ThesesOthers/Phd/pugh.pdf" target="_top">"An
+ Analysis of the Lanczos Gamma Approximation"</a>, PhD Thesis November
+ 2004.
+ </li>
+<li>
+ Viktor T. Toth, <a href="http://www.rskey.org/gamma.htm" target="_top">"Calculators
+ and the Gamma Function"</a>.
+ </li>
+<li>
+ Mathworld, <a href="http://mathworld.wolfram.com/LanczosApproximation.html" target="_top">The
+ Lanczos Approximation</a>.
+ </li>
+</ol></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="relative_error.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="remez.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders/refs.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders/refs.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,166 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>References</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../backgrounders.html" title="Backgrounders">
+<link rel="prev" href="remez.html" title="The Remez Method">
+<link rel="next" href="../status.html" title="Library Status">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="remez.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../status.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.backgrounders.refs"></a> References
+</h3></div></div></div>
+<a name="math_toolkit.backgrounders.refs.general_references"></a><h5>
+<a name="id790525"></a>
+ <a href="refs.html#math_toolkit.backgrounders.refs.general_references">General
+ references</a>
+ </h5>
+<p>
+ (Specific detailed sources for individual functions and distributions are
+ given at the end of each individual section).
+ </p>
+<p>
+ <a href="http://dlmf.nist.gov/about/" target="_top">DLMF (NIST Digital Library of Mathematical
+ Functions)</a> is intended to be a replacement for the legendary Abramowitz
+ and Stegun's Handbook of Mathematical Functions, now scheduled to be completed
+ in 2007.
+ </p>
+<p>
+ M. Abramowitz and I. A. Stegun (Eds.) (1964) Handbook of Mathematical Functions
+ with Formulas, Graphs, and Mathematical Tables, National Bureau of Standards
+ Applied Mathematics Series, U.S. Government Printing Office, Washington,
+ D.C..
+ </p>
+<p>
+ The Wolfram Functions Site
+ The Wolfram Functions Site - Providing the mathematical and scientific community
+ with the world's largest (and most authorititive) collection of formulas
+ and graphics about mathematical functions.
+ </p>
+<p>
+ <a href="http://www.itl.nist.gov/div898/handbook/index.htm" target="_top">NIST/SEMATECH
+ e-Handbook of Statistical Methods</a>
+ </p>
+<p>
+ <a href="http://documents.wolfram.com/mathematica/Add-onsLinks/StandardPackages/Statistics/DiscreteDistributions.html" target="_top">Mathematica
+ Documentation: DiscreteDistributions</a> The Wolfram Research Documentation
+ Center is a collection of online reference materials about Mathematica, CalculationCenter,
+ and other Wolfram Research products.
+ </p>
+<p>
+ <a href="http://documents.wolfram.com/mathematica/Add-onsLinks/StandardPackages/Statistics/ContinuousDistributions.html" target="_top">Mathematica
+ Documentation: ContinuousDistributions</a> The Wolfram Research Documentation
+ Center is a collection of online reference materials about Mathematica, CalculationCenter,
+ and other Wolfram Research products.
+ </p>
+<p>
+ Statistical Distributions (Wiley Series in Probability &amp; Statistics)
+ (Paperback) by N.A.J. Hastings, Brian Peacock, Merran Evans, ISBN: 0471371246,
+ Wiley 2000.
+ </p>
+<p>
+ <a href="http://bh0.physics.ubc.ca/People/matt/Doc/ThesesOthers/Phd/pugh.pdf" target="_top">pugh.pdf
+ (application/pdf Object)</a> Pugh Msc Thesis on the Lanczzos approximation
+ to the gamma function.
+ </p>
+<p>
+ <a href="../../www.open-std.org/jtc1/sc22/wg21/docs/papers/2003" target="_top">N1514, 03-0097,
+ A Proposal to Add Mathematical Special Functions to the C++ Standard Library
+ (version 2), Walter E. Brown</a>
+ </p>
+<a name="math_toolkit.backgrounders.refs.calculators__that_we_found__and_used_to_cross_check___as_far_as_their_widely_varying_accuracy_allowed__"></a><h5>
+<a name="id790679"></a>
+ <a href="refs.html#math_toolkit.backgrounders.refs.calculators__that_we_found__and_used_to_cross_check___as_far_as_their_widely_varying_accuracy_allowed__">Calculators*
+ that we found (and used to cross-check - as far as their widely-varying accuracy
+ allowed).</a>
+ </h5>
+<p>
+ http://www.adsciengineering.combpdcalc
+ Binomial Probability Distribution Calculator.
+ </p>
+<a name="math_toolkit.backgrounders.refs.other_libraries"></a><h5>
+<a name="id790724"></a>
+ Other Libraries
+ </h5>
+<p>
+ Cephes library by Shephen
+ Moshier and his book:
+ </p>
+<p>
+ Methods and programs for mathematical functions, Stephen L B Moshier, Ellis
+ Horwood (1989) ISBN 0745802893 0470216093 provided inspiration.
+ </p>
+<p>
+ 100-decimal digit calculator
+ provided some spot values.
+ </p>
+<p>
+ <a href="http://www.csit.fsu.edu/~burkardt/cpp_src/dcdflib/dcdflib.html" target="_top">C++
+ version</a>.
+ </p>
+<p>
+ <a href="../../lib.stat.cmu.edu/general/cdflib" target="_top">CDFLIB Library of Fortran Routines
+ for Cumulative Distribution functions.</a>
+ </p>
+<p>
+ <a href="http://www.csit.fsu.edu/~burkardt/f_src/dcdflib/dcdflib.html" target="_top">DCDFLIB
+ C++ version</a> DCDFLIB is a library of C++ routines, using double precision
+ arithmetic, for evaluating cumulative probability density functions.
+ </p>
+<p>
+ http://www.softintegration.com/docs/packagechnagstat
+ </p>
+<p>
+ NAG libraries.
+ </p>
+<p>
+ MathCAD
+ </p>
+<p>
+ <a href="http://www.vni.com/products/imsl/jmsl/v30/api/com/imsl/stat/Cdf.html" target="_top">JMSL
+ Numerical Library</a> (Java).
+ </p>
+<p>
+ John F Hart, Computer Approximations, (1978) ISBN 0 088275 642-7.
+ </p>
+<p>
+ William J Cody, Software Manual for the Elementary Functions, Prentice-Hall
+ (1980) ISBN 0138220646.
+ </p>
+<p>
+ Nico Temme, Special Functions, An Introduction to the Classical Functions
+ of Mathematical Physics, Wiley, ISBN: 0471-11313-1 (1996) who also gave valueable
+ advice.
+ </p>
+<p>
+ <a href="http://www.cas.lancs.ac.uk/glossary_v1.1/prob.html#probdistn" target="_top">Statistics
+ Glossary</a>, Valerie Easton and John H. McColl.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="remez.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../status.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders/relative_error.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders/relative_error.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,120 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Relative Error</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../backgrounders.html" title="Backgrounders">
+<link rel="prev" href="implementation.html" title="Additional Implementation Notes">
+<link rel="next" href="lanczos.html" title="The Lanczos Approximation">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="implementation.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="lanczos.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.backgrounders.relative_error"></a><a href="relative_error.html" title="Relative Error"> Relative
+ Error</a>
+</h3></div></div></div>
+<p>
+ Given an actual value <span class="emphasis"><em>a</em></span> and a found value <span class="emphasis"><em>v</em></span>
+ the relative error can be calculated from:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../equations/error2.png"></span>
+ </p>
+<p>
+ However the test programs in the library use the symmetrical form:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../equations/error1.png"></span>
+ </p>
+<p>
+ which measures <span class="emphasis"><em>relative difference</em></span> and happens to be
+ less error prone in use since we don't have to worry which value is the "true"
+ result, and which is the experimental one. It guarantees to return a value
+ at least as large as the relative error.
+ </p>
+<p>
+ Special care needs to be taken when one value is zero: we could either take
+ the absolute error in this case (but that's cheating as the absolute error
+ is likely to be very small), or we could assign a value of either 1 or infinity
+ to the relative error in this special case. In the test cases for the special
+ functions in this library, everything below a threshold is regarded as "effectively
+ zero", otherwise the relative error is assigned the value of 1 if only
+ one of the terms is zero. The threshold is currently set at <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;&gt;::</span><span class="identifier">min</span><span class="special">()</span></code>: in other words all denormalised numbers
+ are regarded as a zero.
+ </p>
+<p>
+ All the test programs calculate <span class="emphasis"><em>quantized relative error</em></span>,
+ whereas the graphs in this manual are produced with the <span class="emphasis"><em>actual
+ error</em></span>. The difference is as follows: in the test programs, the
+ test data is rounded to the target real type under test when the program
+ is compiled, so the error observed will then be a whole number of <span class="emphasis"><em>units
+ in the last place</em></span> either rounded up from the actual error, or
+ rounded down (possibly to zero). In contrast the <span class="emphasis"><em>true error</em></span>
+ is obtained by extending the precision of the calculated value, and then
+ comparing to the actual value: in this case the calculated error may be some
+ fraction of <span class="emphasis"><em>units in the last place</em></span>.
+ </p>
+<p>
+ Note that throughout this manual and the test programs the relative error
+ is usually quoted in units of epsilon. However, remember that <span class="emphasis"><em>units
+ in the last place</em></span> more accurately reflect the number of contaminated
+ digits, and that relative error can <span class="emphasis"><em>"wobble"</em></span>
+ by a factor of 2 compared to <span class="emphasis"><em>units in the last place</em></span>.
+ In other words: two implementations of the same function, whose maximum relative
+ errors differ by a factor of 2, can actually be accurate to the same number
+ of binary digits. You have been warned!
+ </p>
+<a name="zero_error"></a><p>
+ </p>
+<a name="math_toolkit.backgrounders.relative_error.the_impossibility_of_zero_error"></a><h5>
+<a name="id787547"></a>
+ <a href="relative_error.html#math_toolkit.backgrounders.relative_error.the_impossibility_of_zero_error">The
+ Impossibility of Zero Error</a>
+ </h5>
+<p>
+ For many of the functions in this library, it is assumed that the error is
+ "effectively zero" if the computation can be done with a number
+ of guard digits. However it should be remembered that if the result is a
+ <span class="emphasis"><em>transcendental number</em></span> then as a point of principle we
+ can never be sure that the result is accurate to more than 1 ulp. This is
+ an example of <span class="emphasis"><em>the table makers dilemma</em></span>: consider what
+ happens if the first guard digit is a one, and the remaining guard digits
+ are all zero. Do we have a tie or not? Since the only thing we can tell about
+ a transcendental number is that its digits have no particular pattern, we
+ can never tell if we have a tie, no matter how many guard digits we have.
+ Therefore, we can never be completely sure that the result has been rounded
+ in the right direction. Of course, transcendental numbers that just happen
+ to be a tie - for however many guard digits we have - are extremely rare,
+ and get rarer the more guard digits we have, but even so....
+ </p>
+<p>
+ Refer to the classic text <a href="http://docs.sun.com/source/806-3568/ncg_goldberg.html" target="_top">What
+ Every Computer Scientist Should Know About Floating-Point Arithmetic</a>
+ for more information.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="implementation.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="lanczos.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders/remez.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/backgrounders/remez.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,538 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>The Remez Method</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../backgrounders.html" title="Backgrounders">
+<link rel="prev" href="lanczos.html" title="The Lanczos Approximation">
+<link rel="next" href="refs.html" title="References">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lanczos.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="refs.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.backgrounders.remez"></a> The Remez Method
+</h3></div></div></div>
+<p>
+ The Remez algorithm
+ is a methodology for locating the minimax rational approximation to a function.
+ This short article gives a brief overview of the method, but it should not
+ be regarded as a thorough theoretical treatment, for that you should consult
+ your favorite textbook.
+ </p>
+<p>
+ Imagine that you want to approximate some function f(x) by way of a rational
+ function R(x), where R(x) may be either a polynomial P(x) or a ratio of two
+ polynomials P(x)/Q(x) (a rational function). Initially we'll concentrate
+ on the polynomial case, as it's by far the easier to deal with, later we'll
+ extend to the full rational function case.
+ </p>
+<p>
+ We want to find the "best" rational approximation, where "best"
+ is defined to be the approximation that has the least deviation from f(x).
+ We can measure the deviation by way of an error function:
+ </p>
+<p>
+ E<sub>abs</sub>(x) = f(x) - R(x)
+ </p>
+<p>
+ which is expressed in terms of absolute error, but we can equally use relative
+ error:
+ </p>
+<p>
+ E<sub>rel</sub>(x) = (f(x) - R(x)) / |f(x)|
+ </p>
+<p>
+ And indeed in general we can scale the error function in any way we want,
+ it makes no difference to the maths, although the two forms above cover almost
+ every practical case that you're likely to encounter.
+ </p>
+<p>
+ The minimax rational function R(x) is then defined to be the function that
+ yields the smallest maximal value of the error function. Chebyshev showed
+ that there is a unique minimax solution for R(x) that has the following properties:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ If R(x) is a polynomial of degree N, then there are N+2 unknowns: the N+1
+ coefficients of the polynomial, and maximal value of the error function.
+ </li>
+<li>
+ The error function has N+1 roots, and N+2 extrema (minima and maxima).
+ </li>
+<li>
+ The extrema alternate in sign, and all have the same magnitude.
+ </li>
+</ul></div>
+<p>
+ That means that if we know the location of the extrema of the error function
+ then we can write N+2 simultaneous equations:
+ </p>
+<p>
+ R(x<sub>i</sub>) + (-1)<sup>i</sup>E = f(x<sub>i</sub>)
+ </p>
+<p>
+ where E is the maximal error term, and x<sub>i</sub> are the abscissa values of the N+2
+ extrema of the error function. It is then trivial to solve the simultaneous
+ equations to obtain the polynomial coefficients and the error term.
+ </p>
+<p>
+ <span class="emphasis"><em>Unfortunately we don't know where the extrema of the error function
+ are located!</em></span>
+ </p>
+<a name="math_toolkit.backgrounders.remez.the_remez_method"></a><h5>
+<a name="id789413"></a>
+ <a href="remez.html#math_toolkit.backgrounders.remez.the_remez_method">The Remez
+ Method</a>
+ </h5>
+<p>
+ The Remez method is an iterative technique which, given a broad range of
+ assumptions, will converge on the extrema of the error function, and therefore
+ the minimax solution.
+ </p>
+<p>
+ In the following discussion we'll use a concrete example to illustrate the
+ Remez method: an approximation to the function e<sup>x</sup> over the range [-1, 1].
+ </p>
+<p>
+ Before we can begin the Remez method, we must obtain an initial value for
+ the location of the extrema of the error function. We could "guess"
+ these, but a much closer first approximation can be obtained by first constructing
+ an interpolated polynomial approximation to f(x).
+ </p>
+<p>
+ In order to obtain the N+1 coefficients of the interpolated polynomial we
+ need N+1 points (x<sub>0</sub>...x<sub>N</sub>): with our interpolated form passing through each
+ of those points that yields N+1 simultaneous equations:
+ </p>
+<p>
+ f(x<sub>i</sub>) = P(x<sub>i</sub>) = c<sub>0</sub> + c<sub>1</sub>x<sub>i</sub> ... + c<sub>N</sub>x<sub>i</sub><sup>N</sup>
+ </p>
+<p>
+ Which can be solved for the coefficients c<sub>0</sub>...c<sub>N</sub> in P(x).
+ </p>
+<p>
+ Obviously this is not a minimax solution, indeed our only guarantee is that
+ f(x) and P(x) touch at N+1 locations, away from those points the error may
+ be arbitrarily large. However, we would clearly like this initial approximation
+ to be as close to f(x) as possible, and it turns out that using the zeros
+ of an orthogonal polynomial as the initial interpolation points is a good
+ choice. In our example we'll use the zeros of a Chebyshev polynomial as these
+ are particularly easy to calculate, interpolating for a polynomial of degree
+ 4, and measuring <span class="emphasis"><em>relative error</em></span> we get the following
+ error function:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../graphs/remez-2.png" alt="remez-2"></span>
+ </p>
+<p>
+ Which has a peak relative error of 1.2x10<sup>-3</sup>.
+ </p>
+<p>
+ While this is a pretty good approximation already, judging by the shape of
+ the error function we can clearly do better. Before starting on the Remez
+ method propper, we have one more step to perform: locate all the extrema
+ of the error function, and store these locations as our initial <span class="emphasis"><em>Chebyshev
+ control points</em></span>.
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ In the simple case of a polynomial approximation, by interpolating through
+ the roots of a Chebyshev polynomial we have in fact created a <span class="emphasis"><em>Chebyshev
+ approximation</em></span> to the function: in terms of <span class="emphasis"><em>absolute
+ error</em></span> this is the best a priori choice for the interpolated
+ form we can achieve, and typically is very close to the minimax solution.
+ </p>
+<p>
+ However, if we want to optimise for <span class="emphasis"><em>relative error</em></span>,
+ or if the approximation is a rational function, then the initial Chebyshev
+ solution can be quite far from the ideal minimax solution.
+ </p>
+<p>
+ A more technical discussion of the theory involved can be found in this
+ <a href="http://math.fullerton.edu/mathews/n2003/ChebyshevPolyMod.html" target="_top">online
+ course</a>.
+ </p>
+</td></tr>
+</table></div>
+<a name="math_toolkit.backgrounders.remez.remez_step_1"></a><h5>
+<a name="id789633"></a>
+ <a href="remez.html#math_toolkit.backgrounders.remez.remez_step_1">Remez Step
+ 1</a>
+ </h5>
+<p>
+ The first step in the Remez method, given our current set of N+2 Chebyshev
+ control points x<sub>i</sub>, is to solve the N+2 simultaneous equations:
+ </p>
+<p>
+ P(x<sub>i</sub>) + (-1)<sup>i</sup>E = f(x<sub>i</sub>)
+ </p>
+<p>
+ To obtain the error term E, and the coefficients of the polynomial P(x).
+ </p>
+<p>
+ This gives us a new approximation to f(x) that has the same error <span class="emphasis"><em>E</em></span>
+ at each of the control points, and whose error function <span class="emphasis"><em>alternates
+ in sign</em></span> at the control points. This is still not necessarily the
+ minimax solution though: since the control points may not be at the extrema
+ of the error function. After this first step here's what our approximation's
+ error function looks like:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../graphs/remez-3.png" alt="remez-3"></span>
+ </p>
+<p>
+ Clearly this is still not the minimax solution since the control points are
+ not located at the extrema, but the maximum relative error has now dropped
+ to 5.6x10<sup>-4</sup>.
+ </p>
+<a name="math_toolkit.backgrounders.remez.remez_step_2"></a><h5>
+<a name="id789739"></a>
+ <a href="remez.html#math_toolkit.backgrounders.remez.remez_step_2">Remez Step
+ 2</a>
+ </h5>
+<p>
+ The second step is to locate the extrema of the new approximation, which
+ we do in two stages: first, since the error function changes sign at each
+ control point, we must have N+1 roots of the error function located between
+ each pair of N+2 control points. Once these roots are found by standard root
+ finding techniques, we know that N extrema are bracketed between each pair
+ of roots, plus two more between the endpoints of the range and the first
+ and last roots. The N+2 extrema can then be found using standard function
+ minimisation techniques.
+ </p>
+<p>
+ We now have a choice: multi-point exchange, or single point exchange.
+ </p>
+<p>
+ In single point exchange, we move the control point nearest to the largest
+ extrema to the absissa value of the extrema.
+ </p>
+<p>
+ In multi-point exchange we swap all the current control points, for the locations
+ of the extrema.
+ </p>
+<p>
+ In our example we perform multi-point exchange.
+ </p>
+<a name="math_toolkit.backgrounders.remez.iteration"></a><h5>
+<a name="id789799"></a>
+ Iteration
+ </h5>
+<p>
+ The Remez method then performs steps 1 and 2 above iteratively until the
+ control points are located at the extrema of the error function: this is
+ then the minimax solution.
+ </p>
+<p>
+ For our current example, two more iterations converges on a minimax solution
+ with a peak relative error of 5x10<sup>-4</sup> and an error function that looks like:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../graphs/remez-4.png" alt="remez-4"></span>
+ </p>
+<a name="math_toolkit.backgrounders.remez.rational_approximations"></a><h5>
+<a name="id789860"></a>
+ <a href="remez.html#math_toolkit.backgrounders.remez.rational_approximations">Rational
+ Approximations</a>
+ </h5>
+<p>
+ If we wish to extend the Remez method to a rational approximation of the
+ form
+ </p>
+<p>
+ f(x) = R(x) = P(x) / Q(x)
+ </p>
+<p>
+ where P(x) and Q(x) are polynomials, then we proceed as before, except that
+ now we have N+M+2 unknowns if P(x) is of order N and Q(x) is of order M.
+ This assumes that Q(x) is normalised so that it's leading coefficient is
+ 1, giving N+M+1 polynomial coefficients in total, plus the error term E.
+ </p>
+<p>
+ The simultaneous equations to be solved are now:
+ </p>
+<p>
+ P(x<sub>i</sub>) / Q(x<sub>i</sub>) + (-1)<sup>i</sup>E = f(x<sub>i</sub>)
+ </p>
+<p>
+ Evaluated at the N+M+2 control points x<sub>i</sub>.
+ </p>
+<p>
+ Unfortunately these equations are non-linear in the error term E: we can
+ only solve them if we know E, and yet E is one of the unknowns!
+ </p>
+<p>
+ The method usually adopted to solve these equations is an iterative one:
+ we guess the value of E, solve the equations to obtain a new value for E
+ (as well as the polynomial coefficients), then use the new value of E as
+ the next guess. The method is repeated until E converges on a stable value.
+ </p>
+<p>
+ These complications extend the running time required for the development
+ of rational approximations quite considerably. It is often desirable to obtain
+ a rational rather than polynomial approximation none the less: rational approximations
+ will often match more difficult to approximate functions, to greater accuracy,
+ and with greater efficiency, than their polynomial alternatives. For example,
+ if we takes our previous example of an approximation to e<sup>x</sup>, we obtained 5x10<sup>-4</sup> accuracy
+ with an order 4 polynomial. If we move two of the unknowns into the denominator
+ to give a pair of order 2 polynomials, and re-minimise, then the peak relative
+ error drops to 8.7x10<sup>-5</sup>. That's a 5 fold increase in accuracy, for the same
+ number of terms overall.
+ </p>
+<a name="math_toolkit.backgrounders.remez.practical_considerations"></a><h5>
+<a name="id789983"></a>
+ <a href="remez.html#math_toolkit.backgrounders.remez.practical_considerations">Practical
+ Considerations</a>
+ </h5>
+<p>
+ Most treatises on approximation theory stop at this point. However, from
+ a practical point of view, most of the work involves finding the right approximating
+ form, and then persuading the Remez method to converge on a solution.
+ </p>
+<p>
+ So far we have used a direct approximation:
+ </p>
+<p>
+ f(x) = R(x)
+ </p>
+<p>
+ But this will converge to a useful approximation only if f(x) is smooth.
+ In addition round-off errors when evaluating the rational form mean that
+ this will never get closer than within a few epsilon of machine precision.
+ Therefore this form of direct approximation is often reserved for situations
+ where we want efficiency, rather than accuracy.
+ </p>
+<p>
+ The first step in improving the situation is generally to split f(x) into
+ a dominant part that we can compute accurately by another method, and a slowly
+ changing remainder which can be approximated by a rational approximation.
+ We might be tempted to write:
+ </p>
+<p>
+ f(x) = g(x) + R(x)
+ </p>
+<p>
+ where g(x) is the dominant part of f(x), but if f(x)/g(x) is approximately
+ constant over the interval of interest then:
+ </p>
+<p>
+ f(x) = g(x)(c + R(x))
+ </p>
+<p>
+ Will yield a much better solution: here <span class="emphasis"><em>c</em></span> is a constant
+ that is the approximate value of f(x)/g(x) and R(x) is typically tiny compared
+ to <span class="emphasis"><em>c</em></span>. In this situation if R(x) is optimised for absolute
+ error, then as long as its error is small compared to the constant <span class="emphasis"><em>c</em></span>,
+ that error will effectively get wiped out when R(x) is added to <span class="emphasis"><em>c</em></span>.
+ </p>
+<p>
+ The difficult part is obviously finding the right g(x) to extract from your
+ function: often the asymptotic behaviour of the function will give a clue,
+ so for example the function erfc
+ becomes proportional to e<sup>-x<sup>2</sup></sup>/x as x becomes large. Therefore using:
+ </p>
+<p>
+ erfc(z) = (C + R(x)) e<sup>-x<sup>2</sup></sup>/x
+ </p>
+<p>
+ as the approximating form seems like an obvious thing to try, and does indeed
+ yield a useful approximation.
+ </p>
+<p>
+ However, the difficulty then becomes one of converging the minimax solution.
+ Unfortunately, it is known that for some functions the Remez method can lead
+ to divergent behaviour, even when the initial starting approximation is quite
+ good. Furthermore, it is not uncommon for the solution obtained in the first
+ Remez step above to be a bad one: the equations to be solved are generally
+ "stiff", often very close to being singular, and assuming a solution
+ is found at all, round-off errors and a rapidly changing error function,
+ can lead to a situation where the error function does not in fact change
+ sign at each control point as required. If this occurs, it is fatal to the
+ Remez method. It is also possible to obtain solutions that are perfectly
+ valid mathematically, but which are quite useless computationally: either
+ because there is an unavoidable amount of roundoff error in the computation
+ of the rational function, or because the denominator has one or more roots
+ over the interval of the approximation. In the latter case while the approximation
+ may have the correct limiting value at the roots, the approximation is nonetheless
+ useless.
+ </p>
+<p>
+ Assuming that the approximation does not have any fatal errors, and that
+ the only issue is converging adequately on the minimax solution, the aim
+ is to get as close as possible to the minimax solution before beginning the
+ Remez method. Using the zeros of a Chebyshev polynomial for the initial interpolation
+ is a good start, but may not be ideal when dealing with relative errors and/or
+ rational (rather than polynomial) approximations. One approach is to skew
+ the initial interpolation points to one end: for example if we raise the
+ roots of the Chebyshev polynomial to a positive power greater than 1 then
+ the roots will be skewed towards the middle of the [-1,1] interval, while
+ a positive power less than one will skew them towards either end. More usefully,
+ if we initially rescale the points over [0,1] and then raise to a positive
+ power, we can skew them to the left or right. Returning to our example of
+ e<sup>x</sup> over [-1,1], the initial interpolated form was some way from the minimax
+ solution:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../graphs/remez-2.png" alt="remez-2"></span>
+ </p>
+<p>
+ However, if we first skew the interpolation points to the left (rescale them
+ to [0, 1], raise to the power 1.3, and then rescale back to [-1,1]) we reduce
+ the error from 1.3x10<sup>-3</sup>to 6x10<sup>-4</sup>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../graphs/remez-5.png" alt="remez-5"></span>
+ </p>
+<p>
+ It's clearly still not ideal, but it is only a few percent away from our
+ desired minimax solution (5x10<sup>-4</sup>).
+ </p>
+<a name="math_toolkit.backgrounders.remez.remez_method_checklist"></a><h5>
+<a name="id790241"></a>
+ <a href="remez.html#math_toolkit.backgrounders.remez.remez_method_checklist">Remez
+ Method Checklist</a>
+ </h5>
+<p>
+ The following lists some of the things to check if the Remez method goes
+ wrong, it is by no means an exhaustive list, but is provided in the hopes
+ that it will prove useful.
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Is the function smooth enough? Can it be better separated into a rapidly
+ changing part, and an asymptotic part?
+ </li>
+<li>
+ Does the function being approximated have any "blips" in it?
+ Check for problems as the function changes computation method, or if a
+ root, or an infinity has been divided out. The telltale sign is if there
+ is a narrow region where the Remez method will not converge.
+ </li>
+<li>
+ Check you have enough accuracy in your calculations: remember that the
+ Remez method works on the difference between the approximation and the
+ function being approximated: so you must have more digits of precision
+ available than the precision of the approximation being constructed. So
+ for example at double precision, you shouldn't expect to be able to get
+ better than a float precision approximation.
+ </li>
+<li>
+ Try skewing the initial interpolated approximation to minimise the error
+ before you begin the Remez steps.
+ </li>
+<li>
+ If the approximation won't converge or is ill-conditioned from one starting
+ location, try starting from a different location.
+ </li>
+<li>
+ If a rational function won't converge, one can minimise a polynomial (which
+ presents no problems), then rotate one term from the numerator to the denominator
+ and minimise again. In theory one can continue moving terms one at a time
+ from numerator to denominator, and then re-minimising, retaining the last
+ set of control points at each stage.
+ </li>
+<li>
+ Try using a smaller interval. It may also be possible to optimise over
+ one (small) interval, rescale the control points over a larger interval,
+ and then re-minimise.
+ </li>
+<li>
+ Keep absissa values small: use a change of variable to keep the abscissa
+ over, say [0, b], for some smallish value <span class="emphasis"><em>b</em></span>.
+ </li>
+</ul></div>
+<a name="math_toolkit.backgrounders.remez.references"></a><h5>
+<a name="id790344"></a>
+ References
+ </h5>
+<p>
+ The original references for the Remez Method and it's extension to rational
+ functions are unfortunately in Russian:
+ </p>
+<p>
+ Remez, E.Ya., <span class="emphasis"><em>Fundamentals of numerical methods for Chebyshev approximations</em></span>,
+ "Naukova Dumka", Kiev, 1969.
+ </p>
+<p>
+ Remez, E.Ya., Gavrilyuk, V.T., <span class="emphasis"><em>Computer development of certain
+ approaches to the approximate construction of solutions of Chebyshev problems
+ nonlinearly depending on parameters</em></span>, Ukr. Mat. Zh. 12 (1960),
+ 324-338.
+ </p>
+<p>
+ Gavrilyuk, V.T., <span class="emphasis"><em>Generalization of the first polynomial algorithm
+ of E.Ya.Remez for the problem of constructing rational-fractional Chebyshev
+ approximations</em></span>, Ukr. Mat. Zh. 16 (1961), 575-585.
+ </p>
+<p>
+ Some English language sources include:
+ </p>
+<p>
+ Fraser, W., Hart, J.F., <span class="emphasis"><em>On the computation of rational approximations
+ to continuous functions</em></span>, Comm. of the ACM 5 (1962), 401-403, 414.
+ </p>
+<p>
+ Ralston, A., <span class="emphasis"><em>Rational Chebyshev approximation by Remes' algorithms</em></span>,
+ Numer.Math. 7 (1965), no. 4, 322-330.
+ </p>
+<p>
+ A. Ralston, <span class="emphasis"><em>Rational Chebyshev approximation, Mathematical Methods
+ for Digital Computers v. 2</em></span> (Ralston A., Wilf H., eds.), Wiley,
+ New York, 1967, pp. 264-284.
+ </p>
+<p>
+ Hart, J.F. e.a., <span class="emphasis"><em>Computer approximations</em></span>, Wiley, New
+ York a.o., 1968.
+ </p>
+<p>
+ Cody, W.J., Fraser, W., Hart, J.F., <span class="emphasis"><em>Rational Chebyshev approximation
+ using linear equations</em></span>, Numer.Math. 12 (1968), 242-251.
+ </p>
+<p>
+ Cody, W.J., <span class="emphasis"><em>A survey of practical rational and polynomial approximation
+ of functions</em></span>, SIAM Review 12 (1970), no. 3, 400-423.
+ </p>
+<p>
+ Barrar, R.B., Loeb, H.J., <span class="emphasis"><em>On the Remez algorithm for non-linear
+ families</em></span>, Numer.Math. 15 (1970), 382-391.
+ </p>
+<p>
+ Dunham, Ch.B., <span class="emphasis"><em>Convergence of the Fraser-Hart algorithm for rational
+ Chebyshev approximation</em></span>, Math. Comp. 29 (1975), no. 132, 1078-1082.
+ </p>
+<p>
+ G. L. Litvinov, <span class="emphasis"><em>Approximate construction of rational approximations
+ and the effect of error autocorrection</em></span>, Russian Journal of Mathematical
+ Physics, vol.1, No. 3, 1994.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lanczos.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="refs.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,176 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Statistical Distributions and Functions</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../index.html" title="Math Toolkit">
+<link rel="up" href="../index.html" title="Math Toolkit">
+<link rel="prev" href="main_overview/contact.html" title="Contact Info and Support">
+<link rel="next" href="dist/stat_tut.html" title="Statistical Distributions Tutorial">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="main_overview/contact.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="dist/stat_tut.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="math_toolkit.dist"></a> Statistical Distributions and Functions
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="dist/stat_tut.html"> Statistical Distributions
+ Tutorial</a></span></dt>
+<dd><dl>
+<dt><span class="section"> Overview</span></dt>
+<dt><span class="section"> Worked Examples</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="dist/stat_tut/weg/dist_construct_eg.html">
+ Distribution Construction Example</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/st_eg.html"> Student's
+ t Distribution Examples</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="dist/stat_tut/weg/st_eg/tut_mean_intervals.html">
+ Calculating confidence intervals on the mean with the Students-t distribution</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/st_eg/tut_mean_test.html">
+ Testing a sample mean for difference from a "true" mean</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/st_eg/tut_mean_size.html">
+ Estimating how large a sample size would have to become in order to give
+ a significant Students-t test result with a single sample test</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/st_eg/two_sample_students_t.html">
+ Comparing the means of two samples with the Students-t test</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/st_eg/paired_st.html">
+ Comparing two paired samples with the Student's t distribution</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="dist/stat_tut/weg/cs_eg.html"> Chi Squared
+ Distribution Examples</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="dist/stat_tut/weg/cs_eg/chi_sq_intervals.html">
+ Confidence Intervals on the Standard Deviation</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/cs_eg/chi_sq_test.html">
+ Chi-Square Test for the Standard Deviation</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/cs_eg/chi_sq_size.html">
+ Estimating the Required Sample Sizes for a Chi-Square Test for the Standard
+ Deviation</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="dist/stat_tut/weg/f_eg.html"> F Distribution
+ Examples</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/binom_eg.html"> Binomial
+ Distribution Examples</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="dist/stat_tut/weg/binom_eg/binomial_coinflip_example.html">
+ Binomial Coin-Flipping Example</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/binom_eg/binomial_quiz_example.html">
+ Binomial Quiz Example</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/binom_eg/binom_conf.html">
+ Calculating Confidence Limits on the Frequency of Occurrence for a Binomial
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/binom_eg/binom_size_eg.html">
+ Estimating Sample Sizes for a Binomial Distribution.</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="dist/stat_tut/weg/neg_binom_eg.html"> Negative
+ Binomial Distribution Examples</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="dist/stat_tut/weg/neg_binom_eg/neg_binom_conf.html">
+ Calculating Confidence Limits on the Frequency of Occurrence for the
+ Negative Binomial Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/neg_binom_eg/neg_binom_size_eg.html">
+ Estimating Sample Sizes for the Negative Binomial.</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/neg_binom_eg/negative_binomial_example1.html">
+ Negative Binomial Sales Quota Example.</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/neg_binom_eg/negative_binomial_example2.html">
+ Negative Binomial Table Printing Example.</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="dist/stat_tut/weg/normal_example.html"> Normal
+ Distribution Examples</a></span></dt>
+<dd><dl><dt><span class="section"><a href="dist/stat_tut/weg/normal_example/normal_misc.html">
+ Some Miscellaneous Examples of the Normal (Gaussian) Distribution</a></span></dt></dl></dd>
+<dt><span class="section"><a href="dist/stat_tut/weg/error_eg.html"> Error Handling
+ Example</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/find_eg.html"> Find Location
+ and Scale Examples</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="dist/stat_tut/weg/find_eg/find_location_eg.html">
+ Find Location (Mean) Example</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/find_eg/find_scale_eg.html">
+ Find Scale (Standard Deviation) Example</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/weg/find_eg/find_mean_and_sd_eg.html">
+ Find mean and standard deviation example</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="dist/stat_tut/weg/nag_library.html"> Comparison
+ with C, R, FORTRAN-style Free Functions</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="dist/stat_tut/variates.html"> Random Variates
+ and Distribution Parameters</a></span></dt>
+<dt><span class="section"><a href="dist/stat_tut/dist_params.html"> Discrete Probability
+ Distributions</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="dist/dist_ref.html"> Statistical Distributions
+ Reference</a></span></dt>
+<dd><dl>
+<dt><span class="section"> Non-Member Properties</span></dt>
+<dt><span class="section"> Distributions</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="dist/dist_ref/dists/bernoulli_dist.html">
+ Bernoulli Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/beta_dist.html"> Beta
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/binomial_dist.html">
+ Binomial Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/cauchy_dist.html"> Cauchy-Lorentz
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/chi_squared_dist.html">
+ Chi Squared Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/exp_dist.html"> Exponential
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/extreme_dist.html"> Extreme
+ Value Distribution</a></span></dt>
+<dt><span class="section"> F Distribution</span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/gamma_dist.html"> Gamma
+ (and Erlang) Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/lognormal_dist.html">
+ Log Normal Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/negative_binomial_dist.html">
+ Negative Binomial Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/normal_dist.html"> Normal
+ (Gaussian) Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/pareto.html"> Pareto
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/poisson_dist.html"> Poisson
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/rayleigh.html"> Rayleigh
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/students_t_dist.html">
+ Students t Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/triangular_dist.html">
+ Triangular Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/weibull.html"> Weibull
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dist/dist_ref/dists/uniform_dist.html"> Uniform
+ Distribution</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="dist/dist_ref/dist_algorithms.html"> Distribution
+ Algorithms</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Extras/Future Directions</span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="main_overview/contact.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="dist/stat_tut.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,86 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Statistical Distributions Reference</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../dist.html" title="Statistical Distributions and Functions">
+<link rel="prev" href="stat_tut/dist_params.html" title="Discrete Probability Distributions">
+<link rel="next" href="dist_ref/nmp.html" title="Non-Member Properties">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="stat_tut/dist_params.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dist.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="dist_ref/nmp.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.dist.dist_ref"></a><a href="dist_ref.html" title="Statistical Distributions Reference"> Statistical Distributions
+ Reference</a>
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"> Non-Member Properties</span></dt>
+<dt><span class="section"> Distributions</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="dist_ref/dists/bernoulli_dist.html">
+ Bernoulli Distribution</a></span></dt>
+<dt><span class="section"><a href="dist_ref/dists/beta_dist.html"> Beta
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dist_ref/dists/binomial_dist.html">
+ Binomial Distribution</a></span></dt>
+<dt><span class="section"><a href="dist_ref/dists/cauchy_dist.html"> Cauchy-Lorentz
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dist_ref/dists/chi_squared_dist.html">
+ Chi Squared Distribution</a></span></dt>
+<dt><span class="section"><a href="dist_ref/dists/exp_dist.html"> Exponential
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dist_ref/dists/extreme_dist.html"> Extreme
+ Value Distribution</a></span></dt>
+<dt><span class="section"> F Distribution</span></dt>
+<dt><span class="section"><a href="dist_ref/dists/gamma_dist.html"> Gamma
+ (and Erlang) Distribution</a></span></dt>
+<dt><span class="section"><a href="dist_ref/dists/lognormal_dist.html">
+ Log Normal Distribution</a></span></dt>
+<dt><span class="section"><a href="dist_ref/dists/negative_binomial_dist.html">
+ Negative Binomial Distribution</a></span></dt>
+<dt><span class="section"><a href="dist_ref/dists/normal_dist.html"> Normal
+ (Gaussian) Distribution</a></span></dt>
+<dt><span class="section"><a href="dist_ref/dists/pareto.html"> Pareto
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dist_ref/dists/poisson_dist.html"> Poisson
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dist_ref/dists/rayleigh.html"> Rayleigh
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dist_ref/dists/students_t_dist.html">
+ Students t Distribution</a></span></dt>
+<dt><span class="section"><a href="dist_ref/dists/triangular_dist.html">
+ Triangular Distribution</a></span></dt>
+<dt><span class="section"><a href="dist_ref/dists/weibull.html"> Weibull
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dist_ref/dists/uniform_dist.html"> Uniform
+ Distribution</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="dist_ref/dist_algorithms.html"> Distribution
+ Algorithms</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="stat_tut/dist_params.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dist.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="dist_ref/nmp.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dist_algorithms.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dist_algorithms.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,146 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Distribution Algorithms</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dist_ref.html" title="Statistical Distributions Reference">
+<link rel="prev" href="dists/uniform_dist.html" title="Uniform Distribution">
+<link rel="next" href="../future.html" title="Extras/Future Directions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="dists/uniform_dist.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dist_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../future.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.dist.dist_ref.dist_algorithms"></a><a href="dist_algorithms.html" title="Distribution Algorithms"> Distribution
+ Algorithms</a>
+</h4></div></div></div>
+<a name="math_toolkit.dist.dist_ref.dist_algorithms.finding_the_location_and_scale_for_normal_and_similar_distributions"></a><h5>
+<a name="id615034"></a>
+ <a href="dist_algorithms.html#math_toolkit.dist.dist_ref.dist_algorithms.finding_the_location_and_scale_for_normal_and_similar_distributions">Finding
+ the Location and Scale for Normal and similar distributions</a>
+ </h5>
+<p>
+ Two functions aid finding location and scale of random variable z to give
+ probability p (given a scale or location). Only applies to distributions
+ like normal, lognormal, extreme value, Cauchy, (and symmetrical triangular),
+ that have scale and location properties.
+ </p>
+<p>
+ These functions are useful to predict the mean and/or standard deviation
+ that will be needed to meet a specified minimum weight or maximum dose.
+ </p>
+<p>
+ Complement versions are also provided, both with explicit and implicit
+ (default) policy.
+ </p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">;</span> <span class="comment">// May be needed by users defining their own policies.
+</span><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">complement</span><span class="special">;</span> <span class="comment">// Will be needed by users who want to use complements.
+</span></pre>
+<a name="math_toolkit.dist.dist_ref.dist_algorithms.find_location_function"></a><h5>
+<a name="id615190"></a>
+ <a href="dist_algorithms.html#math_toolkit.dist.dist_ref.dist_algorithms.find_location_function">find_location
+ function</a>
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">find_location</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Dist</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span> <span class="comment">// explicit error handling policy
+</span> <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">find_location</span><span class="special">(</span> <span class="comment">// For example, normal mean.
+</span> <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">z</span><span class="special">,</span> <span class="comment">// location of random variable z to give probability, P(X &gt; z) == p.
+</span> <span class="comment">// For example, a nominal minimum acceptable z, so that p * 100 % are &gt; z
+</span> <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// probability value desired at x, say 0.95 for 95% &gt; z.
+</span> <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">scale</span><span class="special">,</span> <span class="comment">// scale parameter, for example, normal standard deviation.
+</span> <span class="keyword">const</span> Policy<span class="special">&amp;</span> <span class="identifier">pol</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Dist</span><span class="special">&gt;</span> <span class="comment">// with default policy.
+</span> <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">find_location</span><span class="special">(</span> <span class="comment">// For example, normal mean.
+</span> <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">z</span><span class="special">,</span> <span class="comment">// location of random variable z to give probability, P(X &gt; z) == p.
+</span> <span class="comment">// For example, a nominal minimum acceptable z, so that p * 100 % are &gt; z
+</span> <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// probability value desired at x, say 0.95 for 95% &gt; z.
+</span> <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">scale</span><span class="special">);</span> <span class="comment">// scale parameter, for example, normal standard deviation.
+</span>
+ <span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.dist.dist_ref.dist_algorithms.find_scale_function"></a><h5>
+<a name="id615813"></a>
+ <a href="dist_algorithms.html#math_toolkit.dist.dist_ref.dist_algorithms.find_scale_function">find_scale
+ function</a>
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">find_scale</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Dist</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+ <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">find_scale</span><span class="special">(</span> <span class="comment">// For example, normal mean.
+</span> <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">z</span><span class="special">,</span> <span class="comment">// location of random variable z to give probability, P(X &gt; z) == p.
+</span> <span class="comment">// For example, a nominal minimum acceptable weight z, so that p * 100 % are &gt; z
+</span> <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// probability value desired at x, say 0.95 for 95% &gt; z.
+</span> <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">location</span><span class="special">,</span> <span class="comment">// location parameter, for example, normal distribution mean.
+</span> <span class="keyword">const</span> Policy<span class="special">&amp;</span> <span class="identifier">pol</span><span class="special">);</span>
+
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Dist</span><span class="special">&gt;</span> <span class="comment">// with default policy.
+</span> <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">find_scale</span><span class="special">(</span> <span class="comment">// For example, normal mean.
+</span> <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">z</span><span class="special">,</span> <span class="comment">// location of random variable z to give probability, P(X &gt; z) == p.
+</span> <span class="comment">// For example, a nominal minimum acceptable z, so that p * 100 % are &gt; z
+</span> <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// probability value desired at x, say 0.95 for 95% &gt; z.
+</span> <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">location</span><span class="special">)</span> <span class="comment">// location parameter, for example, normal distribution mean.
+</span><span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ All argument must be finite, otherwise domain_error
+ is called.
+ </p>
+<p>
+ Probability arguments must be [0, 1], otherwise domain_error
+ is called.
+ </p>
+<p>
+ If the choice of arguments would give a negative scale, domain_error
+ is called, unless the policy is to ignore, when the negative (impossible)
+ value of scale is returned.
+ </p>
+<p>
+ <a href="../stat_tut/weg/find_eg.html" title="Find Location and Scale Examples">Find Mean and standard
+ deviation examples</a> gives simple examples of use of both find_scale
+ and find_location, and a longer example finding means and standard deviations
+ of normally distributed weights to meet a specification.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="dists/uniform_dist.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dist_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../future.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,79 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Distributions</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dist_ref.html" title="Statistical Distributions Reference">
+<link rel="prev" href="nmp.html" title="Non-Member Properties">
+<link rel="next" href="dists/bernoulli_dist.html" title="Bernoulli Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="nmp.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dist_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="dists/bernoulli_dist.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.dist.dist_ref.dists"></a> Distributions
+</h4></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="dists/bernoulli_dist.html">
+ Bernoulli Distribution</a></span></dt>
+<dt><span class="section"><a href="dists/beta_dist.html"> Beta
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dists/binomial_dist.html">
+ Binomial Distribution</a></span></dt>
+<dt><span class="section"><a href="dists/cauchy_dist.html"> Cauchy-Lorentz
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dists/chi_squared_dist.html">
+ Chi Squared Distribution</a></span></dt>
+<dt><span class="section"><a href="dists/exp_dist.html"> Exponential
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dists/extreme_dist.html"> Extreme
+ Value Distribution</a></span></dt>
+<dt><span class="section"> F Distribution</span></dt>
+<dt><span class="section"><a href="dists/gamma_dist.html"> Gamma
+ (and Erlang) Distribution</a></span></dt>
+<dt><span class="section"><a href="dists/lognormal_dist.html">
+ Log Normal Distribution</a></span></dt>
+<dt><span class="section"><a href="dists/negative_binomial_dist.html">
+ Negative Binomial Distribution</a></span></dt>
+<dt><span class="section"><a href="dists/normal_dist.html"> Normal
+ (Gaussian) Distribution</a></span></dt>
+<dt><span class="section"><a href="dists/pareto.html"> Pareto
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dists/poisson_dist.html"> Poisson
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dists/rayleigh.html"> Rayleigh
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dists/students_t_dist.html">
+ Students t Distribution</a></span></dt>
+<dt><span class="section"><a href="dists/triangular_dist.html">
+ Triangular Distribution</a></span></dt>
+<dt><span class="section"><a href="dists/weibull.html"> Weibull
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="dists/uniform_dist.html"> Uniform
+ Distribution</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="nmp.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dist_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="dists/bernoulli_dist.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/bernoulli_dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/bernoulli_dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,354 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Bernoulli Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="../dists.html" title="Distributions">
+<link rel="next" href="beta_dist.html" title="Beta Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../dists.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="beta_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.bernoulli_dist"></a><a href="bernoulli_dist.html" title="Bernoulli Distribution">
+ Bernoulli Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">bernoulli</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+ <span class="keyword">class</span> <span class="identifier">bernoulli_distribution</span><span class="special">;</span>
+
+ <span class="keyword">typedef</span> <span class="identifier">bernoulli_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">bernoulli</span><span class="special">;</span>
+
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+ <span class="keyword">class</span> <span class="identifier">bernoulli_distribution</span>
+ <span class="special">{</span>
+ <span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span>
+
+ <span class="identifier">bernoulli_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">);</span> <span class="comment">// Constructor.
+</span> <span class="comment">// Accessor function.
+</span> <span class="identifier">RealType</span> <span class="identifier">success_fraction</span><span class="special">()</span> <span class="keyword">const</span>
+ <span class="comment">// Probability of success (as a fraction).
+</span> <span class="special">};</span>
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The Bernoulli distribution is a discrete distribution of the outcome
+ of a single trial with only two results, 0 (failure) or 1 (success),
+ with a probability of success p.
+ </p>
+<p>
+ The Bernoulli distribution is the simplest building block on which other
+ discrete distributions of sequences of independent Bernoulli trials can
+ be based.
+ </p>
+<p>
+ The Bernoulli is the binomial distribution (k = 1, p) with only one trial.
+ </p>
+<p>
+ <a href="http://en.wikipedia.org/wiki/Probability_density_function" target="_top">probability
+ density function pdf</a> f(0) = 1 - p, f(1) = p. <a href="http://en.wikipedia.org/wiki/Cumulative_Distribution_Function" target="_top">Cumulative
+ distribution function</a> D(k) = if (k == 0) 1 - p else 1.
+ </p>
+<p>
+ The following graph illustrates how the <a href="http://en.wikipedia.org/wiki/Probability_density_function" target="_top">probability
+ density function pdf</a> varies with the outcome of the single trial:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/bernoulli_pdf.png" alt="bernoulli_pdf"></span>
+ </p>
+<p>
+ and the <a href="http://en.wikipedia.org/wiki/Cumulative_Distribution_Function" target="_top">Cumulative
+ distribution function</a>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/bernoulli_cdf.png" alt="bernoulli_cdf"></span>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.bernoulli_dist.member_functions"></a><h5>
+<a name="id576561"></a>
+ <a href="bernoulli_dist.html#math_toolkit.dist.dist_ref.dists.bernoulli_dist.member_functions">Member
+ Functions</a>
+ </h5>
+<pre class="programlisting">
+<span class="identifier">bernoulli_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs a <a href="http://en.wikipedia.org/wiki/bernoulli_distribution" target="_top">bernoulli
+ distribution</a> with success_fraction <span class="emphasis"><em>p</em></span>.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">success_fraction</span><span class="special">()</span> <span class="keyword">const</span>
+</pre>
+<p>
+ Returns the <span class="emphasis"><em>success_fraction</em></span> parameter of this distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.bernoulli_dist.non_member_accessors"></a><h5>
+<a name="id576679"></a>
+ <a href="bernoulli_dist.html#math_toolkit.dist.dist_ref.dists.bernoulli_dist.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The domain of the random variable is 0 and 1, and the useful supported
+ range is only 0 or 1.
+ </p>
+<p>
+ Outside this range, functions are undefined, or may throw domain_error
+ exception and make an error message available.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.bernoulli_dist.accuracy"></a><h5>
+<a name="id576854"></a>
+ Accuracy
+ </h5>
+<p>
+ The Bernoulli distribution is implemented with simple arithmetic operators
+ and so should have errors within an epsilon or two.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.bernoulli_dist.implementation"></a><h5>
+<a name="id576885"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table <span class="emphasis"><em>p</em></span> is the probability of success
+ and <span class="emphasis"><em>q = 1-p</em></span>. <span class="emphasis"><em>k</em></span> is the random
+ variate, either 0 or 1.
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ The Bernoulli distribution is implemented here as a <span class="emphasis"><em>strict
+ discrete</em></span> distribution. If a generalised version, allowing
+ k to be any real, is required then the binomial distribution with a
+ single trial should be used, for example:
+ </p>
+<p>
+ <code class="computeroutput"><span class="identifier">binomial_distribution</span><span class="special">(</span><span class="number">1</span><span class="special">,</span>
+ <span class="number">0.25</span><span class="special">)</span></code>
+ </p>
+</td></tr>
+</table></div>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ Supported range
+ </p>
+ </td>
+<td>
+ <p>
+ {0, 1}
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: pdf = 1 - p for k = 0, else p
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: cdf = 1 - p for k = 0, else 1
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ q = 1 - p
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ if x &lt;= (1-p) 0 else 1
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ if x &lt;= (1-p) 1 else 0
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ p
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ variance
+ </p>
+ </td>
+<td>
+ <p>
+ p * (1 - p)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ if (p &lt; 0.5) 0 else 1
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ (1 - 2 * p) / sqrt(p * q)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ 6 * p * p - 6 * p +1/ p * q
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ kurtosis -3
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.dist.dist_ref.dists.bernoulli_dist.references"></a><h5>
+<a name="id577256"></a>
+ References
+ </h5>
+<div class="itemizedlist"><ul type="disc">
+<li><a href="http://en.wikipedia.org/wiki/Bernoulli_distribution" target="_top">Wikpedia
+ Bernoulli distribution</a></li>
+<li><a href="../../../../" target="_top">Weisstein, Eric W. "Bernoulli Distribution."
+ From MathWorld--A Wolfram Web Resource.</a></li>
+</ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../dists.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="beta_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/beta_dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/beta_dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,637 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Beta Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="bernoulli_dist.html" title="Bernoulli Distribution">
+<link rel="next" href="binomial_dist.html" title="Binomial Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="bernoulli_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="binomial_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.beta_dist"></a><a href="beta_dist.html" title="Beta Distribution"> Beta
+ Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">beta</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">beta_distribution</span><span class="special">;</span>
+
+<span class="comment">// typedef beta_distribution&lt;double&gt; beta;
+</span><span class="comment">// Note that this is deliberately NOT provided,
+</span><span class="comment">// to avoid a clash with the function name beta.
+</span>
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">beta_distribution</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span>
+ <span class="comment">// Constructor from two shape parameters, alpha &amp; beta:
+</span> <span class="identifier">beta_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">b</span><span class="special">);</span>
+
+ <span class="comment">// Parameter accessors:
+</span> <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">RealType</span> <span class="identifier">beta</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
+
+ <span class="comment">// Parameter estimators of alpha or beta from mean and variance.
+</span> <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_alpha</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">mean</span><span class="special">,</span> <span class="comment">// Expected value of mean.
+</span> <span class="identifier">RealType</span> <span class="identifier">variance</span><span class="special">);</span> <span class="comment">// Expected value of variance.
+</span>
+ <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_beta</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">mean</span><span class="special">,</span> <span class="comment">// Expected value of mean.
+</span> <span class="identifier">RealType</span> <span class="identifier">variance</span><span class="special">);</span> <span class="comment">// Expected value of variance.
+</span>
+ <span class="comment">// Parameter estimators from from
+</span> <span class="comment">// either alpha or beta, and x and probability.
+</span>
+ <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_alpha</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">beta</span><span class="special">,</span> <span class="comment">// from beta.
+</span> <span class="identifier">RealType</span> <span class="identifier">x</span><span class="special">,</span> <span class="comment">// x.
+</span> <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// cdf
+</span>
+ <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_beta</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">,</span> <span class="comment">// alpha.
+</span> <span class="identifier">RealType</span> <span class="identifier">x</span><span class="special">,</span> <span class="comment">// probability x.
+</span> <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// probability cdf.
+</span><span class="special">};</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The class type <code class="computeroutput"><span class="identifier">beta_distribution</span></code>
+ represents a <a href="http://en.wikipedia.org/wiki/Beta_distribution" target="_top">beta
+ </a> <a href="http://en.wikipedia.org/wiki/Probability_distribution" target="_top">probability
+ distribution function</a>.
+ </p>
+<p>
+ The <a href="http://mathworld.wolfram.com/BetaDistribution.htm" target="_top">beta
+ distribution </a> is used as a <a href="http://en.wikipedia.org/wiki/Prior_distribution" target="_top">prior
+ distribution</a> for binomial proportions in <a href="http://mathworld.wolfram.com/BayesianAnalysis.html" target="_top">Bayesian
+ analysis</a>.
+ </p>
+<p>
+ See also: <a href="http://documents.wolfram.com/calculationcenter/v2/Functions/ListsMatrices/Statistics/BetaDistribution.html" target="_top">beta
+ distribution</a> and <a href="http://en.wikipedia.org/wiki/Bayesian_statistics" target="_top">Bayesian
+ statistics</a>.
+ </p>
+<p>
+ How the beta distribution is used for <a href="http://home.uchicago.edu/~grynav/bayes/ABSLec5.ppt" target="_top">Bayesian
+ analysis of one parameter models</a> is discussed by Jeff Grynaviski.
+ </p>
+<p>
+ The <a href="http://en.wikipedia.org/wiki/Probability_density_function" target="_top">probability
+ density function PDF</a> for the <a href="http://en.wikipedia.org/wiki/Beta_distribution" target="_top">beta
+ distribution</a> defined on the interval [0,1] is given by:
+ </p>
+<p>
+ f(x;&#945;,&#946;) = x<sup>&#945; - 1</sup> (1 - x)<sup>&#946; -1</sup> / B(&#945;, &#946;)
+ </p>
+<p>
+ where B(&#945;, &#946;) is the <a href="http://en.wikipedia.org/wiki/Beta_function" target="_top">beta
+ function</a>, implemented in this library as beta.
+ Division by the beta function ensures that the pdf is normalized to the
+ range zero to unity.
+ </p>
+<p>
+ The following graph illustrates examples of the pdf for various values
+ of the shape parameters. Note the &#945; = &#946; = 2 (blue line) is dome-shaped, and
+ might be approximated by a symmetrical triangular distribution.
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/beta_dist.png" alt="beta_dist"></span>
+ </p>
+<p>
+ If &#945; = &#946; = 1, then it is a &#8203;
+<a href="http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29" target="_top">uniform
+ distribution</a>, equal to unity in the entire interval x = 0 to
+ 1. If &#945; &#8203; and &#946; &#8203; are &lt; 1, then the pdf is U-shaped. If &#945; != &#946;, then the shape
+ is asymmetric and could be approximated by a triangle whose apex is away
+ from the centre (where x = half).
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.beta_dist.member_functions"></a><h5>
+<a name="id578391"></a>
+ <a href="beta_dist.html#math_toolkit.dist.dist_ref.dists.beta_dist.member_functions">Member
+ Functions</a>
+ </h5>
+<a name="math_toolkit.dist.dist_ref.dists.beta_dist.constructor"></a><h6>
+<a name="id578417"></a>
+ Constructor
+ </h6>
+<pre class="programlisting">
+<span class="identifier">beta_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">beta</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs a beta distribution with shape parameters <span class="emphasis"><em>alpha</em></span>
+ and <span class="emphasis"><em>beta</em></span>.
+ </p>
+<p>
+ Requires alpha,beta &gt; 0,otherwise domain_error
+ is called. Note that technically the beta distribution is defined for
+ alpha,beta &gt;= 0, but it's not clear whether any program can actually
+ make use of that latitude or how many of the non-member functions can
+ be usefully defined in that case. Therefore for now, we regard it as
+ an error if alpha or beta is zero.
+ </p>
+<p>
+ For example:
+ </p>
+<pre class="programlisting">
+<span class="identifier">beta_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">mybeta</span><span class="special">(</span><span class="number">2</span><span class="special">,</span> <span class="number">5</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs a the beta distribution with alpha=2 and beta=5 (shown in
+ yellow in the graph above).
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.beta_dist.parameter_accessors"></a><h6>
+<a name="id578600"></a>
+ <a href="beta_dist.html#math_toolkit.dist.dist_ref.dists.beta_dist.parameter_accessors">Parameter
+ Accessors</a>
+ </h6>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the parameter <span class="emphasis"><em>alpha</em></span> from which this distribution
+ was constructed.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">beta</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the parameter <span class="emphasis"><em>beta</em></span> from which this distribution
+ was constructed.
+ </p>
+<p>
+ So for example:
+ </p>
+<pre class="programlisting">
+<span class="identifier">beta_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">mybeta</span><span class="special">(</span><span class="number">2</span><span class="special">,</span> <span class="number">5</span><span class="special">);</span>
+<span class="identifier">assert</span><span class="special">(</span><span class="identifier">mybeta</span><span class="special">.</span><span class="identifier">alpha</span><span class="special">()</span> <span class="special">==</span> <span class="number">2.</span><span class="special">);</span> <span class="comment">// mybeta.alpha() returns 2
+</span><span class="identifier">assert</span><span class="special">(</span><span class="identifier">mybeta</span><span class="special">.</span><span class="identifier">beta</span><span class="special">()</span> <span class="special">==</span> <span class="number">5.</span><span class="special">);</span> <span class="comment">// mybeta.beta() returns 5
+</span></pre>
+<a name="math_toolkit.dist.dist_ref.dists.beta_dist.parameter_estimators"></a><h5>
+<a name="id578879"></a>
+ <a href="beta_dist.html#math_toolkit.dist.dist_ref.dists.beta_dist.parameter_estimators">Parameter
+ Estimators</a>
+ </h5>
+<p>
+ Two pairs of parameter estimators are provided.
+ </p>
+<p>
+ One estimates either &#945; &#8203; or &#946; &#8203;
+from presumed-known mean and variance.
+ </p>
+<p>
+ The other pair estimates either &#945; &#8203; or &#946; &#8203; from the cdf and x.
+ </p>
+<p>
+ It is also possible to estimate &#945; &#8203; and &#946; &#8203; from 'known' mode &amp; quantile.
+ For example, calculators are provided by the <a href="http://www.ausvet.com.au/pprev/content.php?page=PPscript" target="_top">Pooled
+ Prevalence Calculator</a> and <a href="http://www.epi.ucdavis.edu/diagnostictests/betabuster.html" target="_top">Beta
+ Buster</a> but this is not yet implemented here.
+ </p>
+<pre class="programlisting">
+<span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_alpha</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">mean</span><span class="special">,</span> <span class="comment">// Expected value of mean.
+</span> <span class="identifier">RealType</span> <span class="identifier">variance</span><span class="special">);</span> <span class="comment">// Expected value of variance.
+</span></pre>
+<p>
+ Returns the unique value of &#945; that corresponds to a beta distribution with
+ mean <span class="emphasis"><em>mean</em></span> and variance <span class="emphasis"><em>variance</em></span>.
+ </p>
+<pre class="programlisting">
+<span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_beta</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">mean</span><span class="special">,</span> <span class="comment">// Expected value of mean.
+</span> <span class="identifier">RealType</span> <span class="identifier">variance</span><span class="special">);</span> <span class="comment">// Expected value of variance.
+</span></pre>
+<p>
+ Returns the unique value of &#946; that corresponds to a beta distribution with
+ mean <span class="emphasis"><em>mean</em></span> and variance <span class="emphasis"><em>variance</em></span>.
+ </p>
+<pre class="programlisting">
+<span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_alpha</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">beta</span><span class="special">,</span> <span class="comment">// from beta.
+</span> <span class="identifier">RealType</span> <span class="identifier">x</span><span class="special">,</span> <span class="comment">// x.
+</span> <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// probability cdf
+</span></pre>
+<p>
+ Returns the value of &#945; that gives: <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">beta_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;(</span><span class="identifier">alpha</span><span class="special">,</span> <span class="identifier">beta</span><span class="special">),</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">probability</span></code>.
+ </p>
+<pre class="programlisting">
+<span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_beta</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">,</span> <span class="comment">// alpha.
+</span> <span class="identifier">RealType</span> <span class="identifier">x</span><span class="special">,</span> <span class="comment">// probability x.
+</span> <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// probability cdf.
+</span></pre>
+<p>
+ Returns the value of &#946; that gives: <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">beta_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;(</span><span class="identifier">alpha</span><span class="special">,</span> <span class="identifier">beta</span><span class="special">),</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">probability</span></code>.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.beta_dist.non_member_accessor_functions"></a><h5>
+<a name="id579518"></a>
+ <a href="beta_dist.html#math_toolkit.dist.dist_ref.dists.beta_dist.non_member_accessor_functions">Non-member
+ Accessor Functions</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The formulae for calculating these are shown in the table below, and
+ at <a href="http://mathworld.wolfram.com/BetaDistribution.html" target="_top">Wolfram
+ Mathworld</a>.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.beta_dist.applications"></a><h5>
+<a name="id579696"></a>
+ Applications
+ </h5>
+<p>
+ The beta distribution can be used to model events constrained to take
+ place within an interval defined by a minimum and maximum value: so it
+ is used in project management systems.
+ </p>
+<p>
+ It is also widely used in <a href="http://en.wikipedia.org/wiki/Bayesian_inference" target="_top">Bayesian
+ statistical inference</a>.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.beta_dist.related_distributions"></a><h5>
+<a name="id579742"></a>
+ <a href="beta_dist.html#math_toolkit.dist.dist_ref.dists.beta_dist.related_distributions">Related
+ distributions</a>
+ </h5>
+<p>
+ The beta distribution with both &#945; &#8203; and &#946; = 1 follows a <a href="http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29" target="_top">uniform
+ distribution</a>.
+ </p>
+<p>
+ The triangular
+ is used when less precise information is available.
+ </p>
+<p>
+ The <a href="http://en.wikipedia.org/wiki/Binomial_distribution" target="_top">binomial
+ distribution</a> is closely related when &#945; &#8203; and &#946; &#8203; are integers.
+ </p>
+<p>
+ With integer values of &#945; &#8203; and &#946; &#8203; the distribution B(i, j) is that of the j-th
+ highest of a sample of i + j + 1 independent random variables uniformly
+ distributed between 0 and 1. The cumulative probability from 0 to x is
+ thus the probability that the j-th highest value is less than x. Or it
+ is the probability that that at least i of the random variables are less
+ than x, a probability given by summing over the <a href="binomial_dist.html" title="Binomial Distribution">Binomial
+ Distribution</a> with its p parameter set to x.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.beta_dist.accuracy"></a><h5>
+<a name="id579831"></a>
+ Accuracy
+ </h5>
+<p>
+ This distribution is implemented using the <a href="../../../special/sf_beta/beta_function.html" title="Beta">beta
+ functions</a> beta
+ and <a href="../../../special/sf_beta/ibeta_function.html" title="Incomplete Beta Functions">incomplete
+ beta functions</a> ibeta
+ and ibetac;
+ please refer to these functions for information on accuracy.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.beta_dist.implementation"></a><h5>
+<a name="id579909"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span>
+ are the parameters &#945; and &#946;, <span class="emphasis"><em>x</em></span> is the random variable,
+ <span class="emphasis"><em>p</em></span> is the probability and <span class="emphasis"><em>q = 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ f(x;&#945;,&#946;) = x<sup>&#945; - 1</sup> (1 - x)<sup>&#946; -1</sup> / B(&#945;, &#946;)
+ </p>
+ <p>
+ Implemented using ibeta_derivative(a,
+ b, x).
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the incomplete beta function ibeta(a,
+ b, x)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ ibetac(a,
+ b, x)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ Using the inverse incomplete beta function ibeta_inv(a,
+ b, p)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ ibetac_inv(a,
+ b, q)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">a</span><span class="special">/(</span><span class="identifier">a</span><span class="special">+</span><span class="identifier">b</span><span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ variance
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">a</span> <span class="special">*</span>
+ <span class="identifier">b</span> <span class="special">/</span>
+ <span class="special">(</span><span class="identifier">a</span><span class="special">+</span><span class="identifier">b</span><span class="special">)^</span><span class="number">2</span> <span class="special">*</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">+</span>
+ <span class="identifier">b</span> <span class="special">+</span>
+ <span class="number">1</span><span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special">(</span><span class="identifier">a</span><span class="special">-</span><span class="number">1</span><span class="special">)</span> <span class="special">/</span>
+ <span class="special">(</span><span class="identifier">a</span>
+ <span class="special">+</span> <span class="identifier">b</span>
+ <span class="special">-</span> <span class="number">2</span><span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="number">2</span> <span class="special">(</span><span class="identifier">b</span><span class="special">-</span><span class="identifier">a</span><span class="special">)</span>
+ <span class="identifier">sqrt</span><span class="special">(</span><span class="identifier">a</span><span class="special">+</span><span class="identifier">b</span><span class="special">+</span><span class="number">1</span><span class="special">)/(</span><span class="identifier">a</span><span class="special">+</span><span class="identifier">b</span><span class="special">+</span><span class="number">2</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">sqrt</span><span class="special">(</span><span class="identifier">a</span>
+ <span class="special">*</span> <span class="identifier">b</span><span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ <span class="inlinemediaobject"><img src="../../../../../equations/beta_dist_kurtosis.png"></span>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">kurtosis</span> <span class="special">+</span>
+ <span class="number">3</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ parameter estimation
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ alpha
+ </p>
+ <p>
+ from mean and variance
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">mean</span> <span class="special">*</span>
+ <span class="special">((</span> <span class="special">(</span><span class="identifier">mean</span> <span class="special">*</span>
+ <span class="special">(</span><span class="number">1</span>
+ <span class="special">-</span> <span class="identifier">mean</span><span class="special">))</span> <span class="special">/</span>
+ <span class="identifier">variance</span><span class="special">)-</span>
+ <span class="number">1</span><span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ beta
+ </p>
+ <p>
+ from mean and variance
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special">(</span><span class="number">1</span>
+ <span class="special">-</span> <span class="identifier">mean</span><span class="special">)</span> <span class="special">*</span>
+ <span class="special">(((</span><span class="identifier">mean</span>
+ <span class="special">*</span> <span class="special">(</span><span class="number">1</span> <span class="special">-</span> <span class="identifier">mean</span><span class="special">))</span>
+ <span class="special">/</span><span class="identifier">variance</span><span class="special">)-</span><span class="number">1</span><span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ The member functions <code class="computeroutput"><span class="identifier">find_alpha</span></code>
+ and <code class="computeroutput"><span class="identifier">find_beta</span></code>
+ </p>
+ <p>
+ from cdf and probability x
+ </p>
+ <p>
+ and <span class="bold"><strong>either</strong></span> <code class="computeroutput"><span class="identifier">alpha</span></code>
+ or <code class="computeroutput"><span class="identifier">beta</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ Implemented in terms of the inverse incomplete beta functions
+ </p>
+ <p>
+ ibeta_inva,
+ and ibeta_invb
+ respectively.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">find_alpha</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">ibeta_inva</span><span class="special">(</span><span class="identifier">beta</span><span class="special">,</span>
+ <span class="identifier">x</span><span class="special">,</span>
+ <span class="identifier">probability</span><span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">find_beta</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">ibeta_invb</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">,</span>
+ <span class="identifier">x</span><span class="special">,</span>
+ <span class="identifier">probability</span><span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.dist.dist_ref.dists.beta_dist.references"></a><h5>
+<a name="id581207"></a>
+ References
+ </h5>
+<p>
+ <a href="http://en.wikipedia.org/wiki/Beta_distribution" target="_top">Wikipedia
+ Beta distribution</a>
+ </p>
+<p>
+ <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366h.htm" target="_top">NIST
+ Exploratory Data Analysis</a>
+ </p>
+<p>
+ <a href="http://mathworld.wolfram.com/BetaDistribution.html" target="_top">Wolfram
+ MathWorld</a>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="bernoulli_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="binomial_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/binomial_dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/binomial_dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,933 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Binomial Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="beta_dist.html" title="Beta Distribution">
+<link rel="next" href="cauchy_dist.html" title="Cauchy-Lorentz Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="beta_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="cauchy_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.binomial_dist"></a><a href="binomial_dist.html" title="Binomial Distribution">
+ Binomial Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">binomial_distribution</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">binomial_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">binomial</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">binomial_distribution</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span>
+
+ <span class="keyword">static</span> <span class="keyword">const</span> <span class="emphasis"><em>unspecified-type</em></span> <span class="identifier">cloppper_pearson_exact_interval</span><span class="special">;</span>
+ <span class="keyword">static</span> <span class="keyword">const</span> <span class="emphasis"><em>unspecified-type</em></span> <span class="identifier">jeffreys_prior_interval</span><span class="special">;</span>
+
+ <span class="comment">// construct:
+</span> <span class="identifier">binomial_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">);</span>
+
+ <span class="comment">// parameter access::
+</span> <span class="identifier">RealType</span> <span class="identifier">success_fraction</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
+
+ <span class="comment">// Bounds on success fraction:
+</span> <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_lower_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">,</span>
+ <span class="emphasis"><em>unspecified-type</em></span> <span class="identifier">method</span> <span class="special">=</span> <span class="identifier">clopper_pearson_exact_interval</span><span class="special">);</span>
+ <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_upper_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">,</span>
+ <span class="emphasis"><em>unspecified-type</em></span> <span class="identifier">method</span> <span class="special">=</span> <span class="identifier">clopper_pearson_exact_interval</span><span class="special">);</span>
+
+ <span class="comment">// estimate min/max number of trials:
+</span> <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span> <span class="comment">// number of events
+</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// success fraction
+</span> <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// risk level
+</span>
+ <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_maximum_number_of_trials</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span> <span class="comment">// number of events
+</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// success fraction
+</span> <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// risk level
+</span><span class="special">};</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The class type <code class="computeroutput"><span class="identifier">binomial_distribution</span></code>
+ represents a <a href="http://mathworld.wolfram.com/BinomialDistribution.html" target="_top">binomial
+ distribution</a>: it is used when there are exactly two mutually
+ exclusive outcomes of a trial. These outcomes are labelled "success"
+ and "failure". The binomial distribution
+ is used to obtain the probability of observing k successes in N trials,
+ with the probability of success on a single trial denoted by p. The binomial
+ distribution assumes that p is fixed for all trials.
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ The random variable for the binomial distribution is the number of
+ successes, (the number of trials is a fixed property of the distribution)
+ whereas for the negative binomial, the random variable is the number
+ of trials, for a fixed number of successes.
+ </p></td></tr>
+</table></div>
+<p>
+ The PDF for the binomial distribution is given by:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../equations/binomial_ref2.png"></span>
+ </p>
+<p>
+ The following two graphs illustrate how the PDF changes depending upon
+ the distributions parameters, first we'll keep the success fraction
+ <span class="emphasis"><em>p</em></span> fixed at 0.5, and vary the sample size:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/binomial_pdf_1.png" alt="binomial_pdf_1"></span>
+ </p>
+<p>
+ Alternatively, we can keep the sample size fixed at N=20 and vary the
+ success fraction <span class="emphasis"><em>p</em></span>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/binomial_pdf_2.png" alt="binomial_pdf_2"></span>
+ </p>
+<p>
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ The Binomial distribution is a discrete distribution: internally
+ functions like the <code class="computeroutput"><span class="identifier">cdf</span></code>
+ and <code class="computeroutput"><span class="identifier">pdf</span></code> 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.
+ </p>
+<p>
+ The quantile function will by default return an integer result that
+ has been <span class="emphasis"><em>rounded outwards</em></span>. 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 <span class="emphasis"><em>at least</em></span> the requested coverage
+ will be present in the central region, and <span class="emphasis"><em>no more than</em></span>
+ the requested coverage will be present in the tails.
+ </p>
+<p>
+ This behaviour can be changed so that the quantile functions are
+ rounded differently, or even return a real-valued result using Policies. It is
+ strongly recommended that you read the tutorial <a href="../../../policy/pol_tutorial/understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">Understanding
+ Quantiles of Discrete Distributions</a> before using the quantile
+ function on the Binomial distribution. The <a href="../../../policy/pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">reference
+ docs</a> describe how to change the rounding policy for these
+ distributions.
+ </p>
+</td></tr>
+</table></div>
+<p>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.binomial_dist.member_functions"></a><h5>
+<a name="id582510"></a>
+ <a href="binomial_dist.html#math_toolkit.dist.dist_ref.dists.binomial_dist.member_functions">Member
+ Functions</a>
+ </h5>
+<a name="math_toolkit.dist.dist_ref.dists.binomial_dist.construct"></a><h6>
+<a name="id582535"></a>
+ Construct
+ </h6>
+<pre class="programlisting">
+<span class="identifier">binomial_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">);</span>
+</pre>
+<p>
+ Constructor: <span class="emphasis"><em>n</em></span> is the total number of trials, <span class="emphasis"><em>p</em></span>
+ is the probability of success of a single trial.
+ </p>
+<p>
+ Requires <code class="computeroutput"><span class="number">0</span> <span class="special">&lt;=</span>
+ <span class="identifier">p</span> <span class="special">&lt;=</span>
+ <span class="number">1</span></code>, and <code class="computeroutput"><span class="identifier">n</span>
+ <span class="special">&gt;=</span> <span class="number">0</span></code>,
+ otherwise calls domain_error.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.binomial_dist.accessors"></a><h6>
+<a name="id582697"></a>
+ Accessors
+ </h6>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">success_fraction</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the parameter <span class="emphasis"><em>p</em></span> from which this distribution
+ was constructed.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the parameter <span class="emphasis"><em>n</em></span> from which this distribution
+ was constructed.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.binomial_dist.lower_bound_on_the_success_fraction"></a><h6>
+<a name="id582815"></a>
+ <a href="binomial_dist.html#math_toolkit.dist.dist_ref.dists.binomial_dist.lower_bound_on_the_success_fraction">Lower
+ Bound on the Success Fraction</a>
+ </h6>
+<pre class="programlisting">
+<span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_lower_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">,</span>
+ <span class="emphasis"><em>unspecified-type</em></span> <span class="identifier">method</span> <span class="special">=</span> <span class="identifier">clopper_pearson_exact_interval</span><span class="special">);</span>
+</pre>
+<p>
+ Returns a lower bound on the success fraction:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">trials</span></dt>
+<dd><p>
+ The total number of trials conducted.
+ </p></dd>
+<dt><span class="term">successes</span></dt>
+<dd><p>
+ The number of successes that occurred.
+ </p></dd>
+<dt><span class="term">alpha</span></dt>
+<dd><p>
+ The largest acceptable probability that the true value of the success
+ fraction is <span class="bold"><strong>less than</strong></span> the value
+ returned.
+ </p></dd>
+<dt><span class="term">method</span></dt>
+<dd><p>
+ An optional parameter that specifies the method to be used to compute
+ the interval (See below).
+ </p></dd>
+</dl>
+</div>
+<p>
+ For example, if you observe <span class="emphasis"><em>k</em></span> successes from <span class="emphasis"><em>n</em></span>
+ trials the best estimate for the success fraction is simply <span class="emphasis"><em>k/n</em></span>,
+ but if you want to be 95% sure that the true value is <span class="bold"><strong>greater
+ than</strong></span> some value, <span class="emphasis"><em>p<sub>min</sub></em></span>, then:
+ </p>
+<pre class="programlisting">
+<span class="identifier">p</span><sub>min</sub> <span class="special">=</span> <span class="identifier">binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">find_lower_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">n</span><span class="special">,</span> <span class="identifier">k</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
+</pre>
+<p>
+ <a href="../../stat_tut/weg/binom_eg/binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for a Binomial Distribution">See
+ worked example.</a>
+ </p>
+<p>
+ There are currently two possible values available for the <span class="emphasis"><em>method</em></span>
+ optional parameter: <span class="emphasis"><em>clopper_pearson_exact_interval</em></span>
+ or <span class="emphasis"><em>jeffreys_prior_interval</em></span>. These constants are
+ both members of class template <code class="computeroutput"><span class="identifier">binomial_distribution</span></code>,
+ so usage is for example:
+ </p>
+<pre class="programlisting">
+<span class="identifier">p</span> <span class="special">=</span> <span class="identifier">binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">find_lower_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">n</span><span class="special">,</span> <span class="identifier">k</span><span class="special">,</span> <span class="number">0.05</span><span class="special">,</span> <span class="identifier">binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">jeffreys_prior_interval</span><span class="special">);</span>
+</pre>
+<p>
+ The default method if this parameter is not specified is the Clopper
+ Pearson "exact" interval. This produces an interval that guarantees
+ at least <code class="computeroutput"><span class="number">100</span><span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">alpha</span><span class="special">)%</span></code> coverage, but which is known to be
+ overly conservative, sometimes producing intervals with much greater
+ than the requested coverage.
+ </p>
+<p>
+ The alternative calculation method produces a non-informative Jeffreys
+ Prior interval. It produces <code class="computeroutput"><span class="number">100</span><span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">alpha</span><span class="special">)%</span></code>
+ coverage only <span class="emphasis"><em>in the average case</em></span>, though is typically
+ very close to the requested coverage level. It is one of the main methods
+ of calculation recommended in the review by Brown, Cai and DasGupta.
+ </p>
+<p>
+ Please note that the "textbook" calculation method using a
+ normal approximation (the Wald interval) is deliberately not provided:
+ it is known to produce consistently poor results, even when the sample
+ size is surprisingly large. Refer to Brown, Cai and DasGupta for a full
+ explanation. Many other methods of calculation are available, and may
+ be more appropriate for specific situations. Unfortunately there appears
+ to be no consensus amongst statisticians as to which is "best":
+ refer to the discussion at the end of Brown, Cai and DasGupta for examples.
+ </p>
+<p>
+ The two methods provided here were chosen principally because they can
+ be used for both one and two sided intervals. See also:
+ </p>
+<p>
+ Lawrence D. Brown, T. Tony Cai and Anirban DasGupta (2001), Interval
+ Estimation for a Binomial Proportion, Statistical Science, Vol. 16, No.
+ 2, 101-133.
+ </p>
+<p>
+ T. Tony Cai (2005), One-sided confidence intervals in discrete distributions,
+ Journal of Statistical Planning and Inference 131, 63-88.
+ </p>
+<p>
+ Agresti, A. and Coull, B. A. (1998). Approximate is better than "exact"
+ for interval estimation of binomial proportions. Amer. Statist. 52 119-126.
+ </p>
+<p>
+ Clopper, C. J. and Pearson, E. S. (1934). The use of confidence or fiducial
+ limits illustrated in the case of the binomial. Biometrika 26 404-413.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.binomial_dist.upper_bound_on_the_success_fraction"></a><h6>
+<a name="id583450"></a>
+ <a href="binomial_dist.html#math_toolkit.dist.dist_ref.dists.binomial_dist.upper_bound_on_the_success_fraction">Upper
+ Bound on the Success Fraction</a>
+ </h6>
+<pre class="programlisting">
+<span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_upper_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">,</span>
+ <span class="emphasis"><em>unspecified-type</em></span> <span class="identifier">method</span> <span class="special">=</span> <span class="identifier">clopper_pearson_exact_interval</span><span class="special">);</span>
+</pre>
+<p>
+ Returns an upper bound on the success fraction:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">trials</span></dt>
+<dd><p>
+ The total number of trials conducted.
+ </p></dd>
+<dt><span class="term">successes</span></dt>
+<dd><p>
+ The number of successes that occurred.
+ </p></dd>
+<dt><span class="term">alpha</span></dt>
+<dd><p>
+ The largest acceptable probability that the true value of the success
+ fraction is <span class="bold"><strong>greater than</strong></span> the value
+ returned.
+ </p></dd>
+<dt><span class="term">method</span></dt>
+<dd><p>
+ An optional parameter that specifies the method to be used to compute
+ the interval. Refer to the documentation for <code class="computeroutput"><span class="identifier">find_upper_bound_on_p</span></code>
+ above for the meaning of the method options.
+ </p></dd>
+</dl>
+</div>
+<p>
+ For example, if you observe <span class="emphasis"><em>k</em></span> successes from <span class="emphasis"><em>n</em></span>
+ trials the best estimate for the success fraction is simply <span class="emphasis"><em>k/n</em></span>,
+ but if you want to be 95% sure that the true value is <span class="bold"><strong>less
+ than</strong></span> some value, <span class="emphasis"><em>p<sub>max</sub></em></span>, then:
+ </p>
+<pre class="programlisting">
+<span class="identifier">p</span><sub>max</sub> <span class="special">=</span> <span class="identifier">binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">find_upper_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">n</span><span class="special">,</span> <span class="identifier">k</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
+</pre>
+<p>
+ <a href="../../stat_tut/weg/binom_eg/binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for a Binomial Distribution">See
+ worked example.</a>
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ In order to obtain a two sided bound on the success fraction, you call
+ both <code class="computeroutput"><span class="identifier">find_lower_bound_on_p</span></code>
+ <span class="bold"><strong>and</strong></span> <code class="computeroutput"><span class="identifier">find_upper_bound_on_p</span></code>
+ each with the same arguments.
+ </p>
+<p>
+ If the desired risk level that the true success fraction lies outside
+ the bounds is &#945;, then you pass &#945;/2 to these functions.
+ </p>
+<p>
+ So for example a two sided 95% confidence interval would be obtained
+ by passing &#945; = 0.025 to each of the functions.
+ </p>
+<p>
+ <a href="../../stat_tut/weg/binom_eg/binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for a Binomial Distribution">See
+ worked example.</a>
+ </p>
+</td></tr>
+</table></div>
+<a name="math_toolkit.dist.dist_ref.dists.binomial_dist.estimating_the_number_of_trials_required_for_a_certain_number_of_successes"></a><h6>
+<a name="id583892"></a>
+ <a href="binomial_dist.html#math_toolkit.dist.dist_ref.dists.binomial_dist.estimating_the_number_of_trials_required_for_a_certain_number_of_successes">Estimating
+ the Number of Trials Required for a Certain Number of Successes</a>
+ </h6>
+<pre class="programlisting">
+<span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span> <span class="comment">// number of events
+</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// success fraction
+</span> <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// probability threshold
+</span></pre>
+<p>
+ This function estimates the minimum number of trials required to ensure
+ that more than k events is observed with a level of risk <span class="emphasis"><em>alpha</em></span>
+ that k or fewer events occur.
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">k</span></dt>
+<dd><p>
+ The number of success observed.
+ </p></dd>
+<dt><span class="term">p</span></dt>
+<dd><p>
+ The probability of success for each trial.
+ </p></dd>
+<dt><span class="term">alpha</span></dt>
+<dd><p>
+ The maximum acceptable probability that k events or fewer will be
+ observed.
+ </p></dd>
+</dl>
+</div>
+<p>
+ For example:
+ </p>
+<pre class="programlisting">
+<span class="identifier">binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">find_number_of_trials</span><span class="special">(</span><span class="number">10</span><span class="special">,</span> <span class="number">0.5</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the smallest number of trials we must conduct to be 95% sure
+ of seeing 10 events that occur with frequency one half.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.binomial_dist.estimating_the_maximum_number_of_trials_to_ensure_no_more_than_a_certain_number_of_successes"></a><h6>
+<a name="id584168"></a>
+ <a href="binomial_dist.html#math_toolkit.dist.dist_ref.dists.binomial_dist.estimating_the_maximum_number_of_trials_to_ensure_no_more_than_a_certain_number_of_successes">Estimating
+ the Maximum Number of Trials to Ensure no more than a Certain Number
+ of Successes</a>
+ </h6>
+<pre class="programlisting">
+<span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_maximum_number_of_trials</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span> <span class="comment">// number of events
+</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// success fraction
+</span> <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// probability threshold
+</span></pre>
+<p>
+ This function estimates the maximum number of trials we can conduct to
+ ensure that k successes or fewer are observed, with a risk <span class="emphasis"><em>alpha</em></span>
+ that more than k occur.
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">k</span></dt>
+<dd><p>
+ The number of success observed.
+ </p></dd>
+<dt><span class="term">p</span></dt>
+<dd><p>
+ The probability of success for each trial.
+ </p></dd>
+<dt><span class="term">alpha</span></dt>
+<dd><p>
+ The maximum acceptable probability that more than k events will be
+ observed.
+ </p></dd>
+</dl>
+</div>
+<p>
+ For example:
+ </p>
+<pre class="programlisting">
+<span class="identifier">binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">find_maximum_number_of_trials</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">1e-6</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the largest number of trials we can conduct and still be 95%
+ certain of not observing any events that occur with one in a million
+ frequency. This is typically used in failure analysis.
+ </p>
+<p>
+ <a href="../../stat_tut/weg/binom_eg/binom_size_eg.html" title="Estimating Sample Sizes for a Binomial Distribution.">See
+ Worked Example.</a>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.binomial_dist.non_member_accessors"></a><h5>
+<a name="id584462"></a>
+ <a href="binomial_dist.html#math_toolkit.dist.dist_ref.dists.binomial_dist.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The domain for the random variable <span class="emphasis"><em>k</em></span> is <code class="computeroutput"><span class="number">0</span> <span class="special">&lt;=</span> <span class="identifier">k</span> <span class="special">&lt;=</span> <span class="identifier">N</span></code>, otherwise a domain_error
+ is returned.
+ </p>
+<p>
+ It's worth taking a moment to define what these accessors actually mean
+ in the context of this distribution:
+ </p>
+<div class="table">
+<a name="id584676"></a><p class="title"><b>Table 7. Meaning of the non-member accessors</b></p>
+<div class="table-contents"><table class="table" summary="Meaning of the non-member accessors">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Meaning
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ Probability Density Function
+ </p>
+ </td>
+<td>
+ <p>
+ The probability of obtaining <span class="bold"><strong>exactly k successes</strong></span>
+ from n trials with success fraction p. For example:
+ </p>
+ <p>
+ <code class="computeroutput"><span class="identifier">pdf</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="identifier">n</span><span class="special">,</span>
+ <span class="identifier">p</span><span class="special">),</span>
+ <span class="identifier">k</span><span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Cumulative Distribution Function
+ </p>
+ </td>
+<td>
+ <p>
+ The probability of obtaining <span class="bold"><strong>k successes
+ or fewer</strong></span> from n trials with success fraction p. For
+ example:
+ </p>
+ <p>
+ <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="identifier">n</span><span class="special">,</span>
+ <span class="identifier">p</span><span class="special">),</span>
+ <span class="identifier">k</span><span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../nmp.html#math.dist.ccdf">Complement of the Cumulative Distribution
+ Function</a>
+ </p>
+ </td>
+<td>
+ <p>
+ The probability of obtaining <span class="bold"><strong>more than k
+ successes</strong></span> from n trials with success fraction p. For
+ example:
+ </p>
+ <p>
+ <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="identifier">n</span><span class="special">,</span>
+ <span class="identifier">p</span><span class="special">),</span>
+ <span class="identifier">k</span><span class="special">))</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ The <span class="bold"><strong>greatest</strong></span> number of successes
+ that may be observed from n trials with success fraction p, at
+ probability P. Note that the value returned is a real-number, and
+ not an integer. Depending on the use case you may want to take
+ either the floor or ceiling of the result. For example:
+ </p>
+ <p>
+ <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="identifier">n</span><span class="special">,</span>
+ <span class="identifier">p</span><span class="special">),</span>
+ <span class="identifier">P</span><span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../nmp.html#math.dist.quantile_c">Quantile from the complement
+ of the probability</a>
+ </p>
+ </td>
+<td>
+ <p>
+ The <span class="bold"><strong>smallest</strong></span> number of successes
+ that may be observed from n trials with success fraction p, at
+ probability P. Note that the value returned is a real-number, and
+ not an integer. Depending on the use case you may want to take
+ either the floor or ceiling of the result. For example:
+ </p>
+ <p>
+ <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="identifier">n</span><span class="special">,</span>
+ <span class="identifier">p</span><span class="special">),</span>
+ <span class="identifier">P</span><span class="special">))</span></code>`
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><a name="math_toolkit.dist.dist_ref.dists.binomial_dist.examples"></a><h5>
+<a name="id585235"></a>
+ Examples
+ </h5>
+<p>
+ Various <a href="../../stat_tut/weg/binom_eg.html" title="Binomial Distribution Examples">worked
+ examples</a> are available illustrating the use of the binomial distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.binomial_dist.accuracy"></a><h5>
+<a name="id585275"></a>
+ Accuracy
+ </h5>
+<p>
+ This distribution is implemented using the incomplete beta functions
+ ibeta
+ and ibetac,
+ please refer to these functions for information on accuracy.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.binomial_dist.implementation"></a><h5>
+<a name="id585325"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table <span class="emphasis"><em>p</em></span> is the probability that
+ one trial will be successful (the success fraction), <span class="emphasis"><em>n</em></span>
+ is the number of trials, <span class="emphasis"><em>k</em></span> is the number of successes,
+ <span class="emphasis"><em>p</em></span> is the probability and <span class="emphasis"><em>q = 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ Implementation is in terms of ibeta_derivative:
+ if <sub>n</sub>C<sub>k </sub> is the binomial coefficient of a and b, then we have:
+ </p>
+ <p>
+ <span class="inlinemediaobject"><img src="../../../../../equations/binomial_ref1.png"></span>
+ </p>
+ <p>
+ Which can be evaluated as <code class="computeroutput"><span class="identifier">ibeta_derivative</span><span class="special">(</span><span class="identifier">k</span><span class="special">+</span><span class="number">1</span><span class="special">,</span> <span class="identifier">n</span><span class="special">-</span><span class="identifier">k</span><span class="special">+</span><span class="number">1</span><span class="special">,</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">/</span>
+ <span class="special">(</span><span class="identifier">n</span><span class="special">+</span><span class="number">1</span><span class="special">)</span></code>
+ </p>
+ <p>
+ The function ibeta_derivative
+ is used here, since it has already been optimised for the lowest
+ possible error - indeed this is really just a thin wrapper around
+ part of the internals of the incomplete beta function.
+ </p>
+ <p>
+ There are also various special cases: refer to the code for details.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation:
+ </p>
+ <p>
+
+</p>
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">
+<span class="identifier">p</span> <span class="special">=</span> <span class="identifier">I</span><span class="special">[</span><span class="identifier">sub</span> <span class="number">1</span><span class="special">-</span><span class="identifier">p</span><span class="special">](</span><span class="identifier">n</span> <span class="special">-</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">k</span> <span class="special">+</span> <span class="number">1</span><span class="special">)</span>
+ <span class="special">=</span> <span class="number">1</span> <span class="special">-</span> <span class="identifier">I</span><span class="special">[</span><span class="identifier">sub</span> <span class="identifier">p</span><span class="special">](</span><span class="identifier">k</span> <span class="special">+</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">n</span> <span class="special">-</span> <span class="identifier">k</span><span class="special">)</span>
+ <span class="special">=</span> ibetac<span class="special">(</span><span class="identifier">k</span> <span class="special">+</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">n</span> <span class="special">-</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">p</span><span class="special">)</span></pre>
+<p>
+ </p>
+ <p>
+ There are also various special cases: refer to the code for details.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: q = ibeta(k
+ + 1, n - k, p)
+ </p>
+ <p>
+ There are also various special cases: refer to the code for details.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ Since the cdf is non-linear in variate <span class="emphasis"><em>k</em></span>
+ none of the inverse incomplete beta functions can be used here.
+ Instead the quantile is found numerically using a derivative
+ free method (<a href="../../../toolkit/internals1/roots2.html" title="Root Finding Without Derivatives">TOMS
+ Algorithm 748</a>).
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ Found numerically as above.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">p</span> <span class="special">*</span>
+ <span class="identifier">n</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ variance
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">p</span> <span class="special">*</span>
+ <span class="identifier">n</span> <span class="special">*</span>
+ <span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">p</span><span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">floor</span><span class="special">(</span><span class="identifier">p</span> <span class="special">*</span>
+ <span class="special">(</span><span class="identifier">n</span>
+ <span class="special">+</span> <span class="number">1</span><span class="special">))</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special">(</span><span class="number">1</span>
+ <span class="special">-</span> <span class="number">2</span>
+ <span class="special">*</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">/</span>
+ <span class="identifier">sqrt</span><span class="special">(</span><span class="identifier">n</span> <span class="special">*</span>
+ <span class="identifier">p</span> <span class="special">*</span>
+ <span class="special">(</span><span class="number">1</span>
+ <span class="special">-</span> <span class="identifier">p</span><span class="special">))</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="number">3</span> <span class="special">-</span>
+ <span class="special">(</span><span class="number">6</span>
+ <span class="special">/</span> <span class="identifier">n</span><span class="special">)</span> <span class="special">+</span>
+ <span class="special">(</span><span class="number">1</span>
+ <span class="special">/</span> <span class="special">(</span><span class="identifier">n</span> <span class="special">*</span>
+ <span class="identifier">p</span> <span class="special">*</span>
+ <span class="special">(</span><span class="number">1</span>
+ <span class="special">-</span> <span class="identifier">p</span><span class="special">)))</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special">(</span><span class="number">1</span>
+ <span class="special">-</span> <span class="number">6</span>
+ <span class="special">*</span> <span class="identifier">p</span>
+ <span class="special">*</span> <span class="identifier">q</span><span class="special">)</span> <span class="special">/</span>
+ <span class="special">(</span><span class="identifier">n</span>
+ <span class="special">*</span> <span class="identifier">p</span>
+ <span class="special">*</span> <span class="identifier">q</span><span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ parameter estimation
+ </p>
+ </td>
+<td>
+ <p>
+ The member functions <code class="computeroutput"><span class="identifier">find_upper_bound_on_p</span></code>
+ <code class="computeroutput"><span class="identifier">find_lower_bound_on_p</span></code>
+ and <code class="computeroutput"><span class="identifier">find_number_of_trials</span></code>
+ are implemented in terms of the inverse incomplete beta functions
+ ibetac_inv,
+ ibeta_inv,
+ and ibetac_invb
+ respectively
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.dist.dist_ref.dists.binomial_dist.references"></a><h5>
+<a name="id586665"></a>
+ References
+ </h5>
+<div class="itemizedlist"><ul type="disc">
+<li>
+<a href="http://mathworld.wolfram.com/BinomialDistribution.html" target="_top">Weisstein,
+ Eric W. "Binomial Distribution." From MathWorld--A Wolfram
+ Web Resource</a>.
+ </li>
+<li>
+<a href="http://en.wikipedia.org/wiki/Beta_distribution" target="_top">Wikipedia
+ binomial distribution</a>.
+ </li>
+<li>
+<a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366i.htm" target="_top">NIST
+ Explorary Data Analysis</a>.
+ </li>
+</ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="beta_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="cauchy_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/cauchy_dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/cauchy_dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,307 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Cauchy-Lorentz Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="binomial_dist.html" title="Binomial Distribution">
+<link rel="next" href="chi_squared_dist.html" title="Chi Squared Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="binomial_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="chi_squared_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.cauchy_dist"></a><a href="cauchy_dist.html" title="Cauchy-Lorentz Distribution"> Cauchy-Lorentz
+ Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">cauchy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">cauchy_distribution</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">cauchy_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">cauchy</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">cauchy_distribution</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span>
+
+ <span class="identifier">cauchy_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">location</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+
+ <span class="identifier">RealType</span> <span class="identifier">location</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ The <a href="http://en.wikipedia.org/wiki/Cauchy_distribution" target="_top">Cauchy-Lorentz
+ distribution</a> is named after Augustin Cauchy and Hendrik Lorentz.
+ It is a <a href="http://en.wikipedia.org/wiki/Probability_distribution" target="_top">continuous
+ probability distribution</a> with <a href="http://en.wikipedia.org/wiki/Probability_distribution" target="_top">probability
+ distribution function PDF</a> given by:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../equations/cauchy_ref1.png"></span>
+ </p>
+<p>
+ The location parameter x<sub>0</sub> is the location of the peak of the distribution
+ (the mode of the distribution), while the scale parameter &#947; specifies half
+ the width of the PDF at half the maximum height. If the location is zero,
+ and the scale 1, then the result is a standard Cauchy distribution.
+ </p>
+<p>
+ The distribution is important in physics as it is the solution to the
+ differential equation describing forced resonance, while in spectroscopy
+ it is the description of the line shape of spectral lines.
+ </p>
+<p>
+ The following graph shows how the distributions moves as the location
+ parameter changes:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/cauchy1.png" alt="cauchy1"></span>
+ </p>
+<p>
+ While the following graph shows how the shape (scale) parameter alters
+ the distribution:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/cauchy2.png" alt="cauchy2"></span>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.cauchy_dist.member_functions"></a><h5>
+<a name="id587348"></a>
+ <a href="cauchy_dist.html#math_toolkit.dist.dist_ref.dists.cauchy_dist.member_functions">Member
+ Functions</a>
+ </h5>
+<pre class="programlisting">
+<span class="identifier">cauchy_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">location</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs a Cauchy distribution, with location parameter <span class="emphasis"><em>location</em></span>
+ and scale parameter <span class="emphasis"><em>scale</em></span>. When these parameters
+ take their default values (location = 0, scale = 1) then the result is
+ a Standard Cauchy Distribution.
+ </p>
+<p>
+ Requires scale &gt; 0, otherwise calls domain_error.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">location</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the location parameter of the distribution.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the scale parameter of the distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.cauchy_dist.non_member_accessors"></a><h5>
+<a name="id587562"></a>
+ <a href="cauchy_dist.html#math_toolkit.dist.dist_ref.dists.cauchy_dist.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ Note however that the Cauchy distribution does not have a mean, standard
+ deviation, etc. See <a href="../../../policy/pol_ref/assert_undefined.html" title="Mathematically Undefined Function Policies">mathematically
+ undefined function</a>
+ </p>
+<p>
+ to control whether these should fail to compile with a BOOST_STATIC_ASSERTION_FAILURE,
+ which is the default.
+ </p>
+<p>
+ Alternately, the functions mean,
+ standard deviation, variance,
+ skewness, kurtosis
+ and kurtosis_excess
+ will all return a domain_error if
+ called.
+ </p>
+<p>
+ The domain of the random variable is [-[max_value], +[min_value]].
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.cauchy_dist.accuracy"></a><h5>
+<a name="id587817"></a>
+ Accuracy
+ </h5>
+<p>
+ The Cauchy distribution is implemented in terms of the standard library
+ <code class="computeroutput"><span class="identifier">tan</span></code> and <code class="computeroutput"><span class="identifier">atan</span></code> functions, and as such should
+ have very low error rates.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.cauchy_dist.implementation"></a><h5>
+<a name="id587872"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table x<sub>0 </sub> is the location parameter of the distribution,
+ &#947; is its scale parameter, <span class="emphasis"><em>x</em></span> is the random variate,
+ <span class="emphasis"><em>p</em></span> is the probability and <span class="emphasis"><em>q = 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: pdf = 1 / (&#960; * &#947; * (1 + ((x - x<sub>0 </sub>) / &#947;)<sup>2</sup>)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf and its complement
+ </p>
+ </td>
+<td>
+ <p>
+ The cdf is normally given by:
+ </p>
+ <p>
+ p = 0.5 + atan(x)/&#960;
+ </p>
+ <p>
+ But that suffers from cancellation error as x -&gt; -&#8734;. So recall
+ that for <code class="computeroutput"><span class="identifier">x</span> <span class="special">&lt;</span>
+ <span class="number">0</span></code>:
+ </p>
+ <p>
+ atan(x) = -&#960;/2 - atan(1/x)
+ </p>
+ <p>
+ Substituting into the above we get:
+ </p>
+ <p>
+ p = -atan(1/x) ; x &lt; 0
+ </p>
+ <p>
+ So the procedure is to calculate the cdf for -fabs(x) using the
+ above formula. Note that to factor in the location and scale
+ parameters you must substitute (x - x<sub>0 </sub>) / &#947; for x in the above.
+ </p>
+ <p>
+ This procedure yields the smaller of <span class="emphasis"><em>p</em></span> and
+ <span class="emphasis"><em>q</em></span>, so the result may need subtracting from
+ 1 depending on whether we want the complement or not, and whether
+ <span class="emphasis"><em>x</em></span> is less than x<sub>0 </sub> or not.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ The same procedure is used irrespective of whether we're starting
+ from the probability or it's complement. First the argument
+ <span class="emphasis"><em>p</em></span> is reduced to the range [-0.5, 0.5], then
+ the relation
+ </p>
+ <p>
+ x = x<sub>0 </sub> ± &#947; / tan(&#960; * p)
+ </p>
+ <p>
+ is used to obtain the result. Whether we're adding or subtracting
+ from x<sub>0 </sub> is determined by whether we're starting from the complement
+ or not.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ The location parameter.
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.dist.dist_ref.dists.cauchy_dist.references"></a><h5>
+<a name="id588162"></a>
+ References
+ </h5>
+<div class="itemizedlist"><ul type="disc">
+<li><a href="http://en.wikipedia.org/wiki/Cauchy_distribution" target="_top">Cauchy-Lorentz
+ distribution</a></li>
+<li><a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3663.htm" target="_top">NIST
+ Exploratory Data Analysis</a></li>
+<li><a href="http://mathworld.wolfram.com/CauchyDistribution.html" target="_top">Weisstein,
+ Eric W. "Cauchy Distribution." From MathWorld--A Wolfram
+ Web Resource.</a></li>
+</ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="binomial_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="chi_squared_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/chi_squared_dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/chi_squared_dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,404 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Chi Squared Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="cauchy_dist.html" title="Cauchy-Lorentz Distribution">
+<link rel="next" href="exp_dist.html" title="Exponential Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="cauchy_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="exp_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.chi_squared_dist"></a><a href="chi_squared_dist.html" title="Chi Squared Distribution">
+ Chi Squared Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">chi_squared</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">chi_squared_distribution</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">chi_squared_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">chi_squared</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">chi_squared_distribution</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span>
+
+ <span class="comment">// Constructor:
+</span> <span class="identifier">chi_squared_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">i</span><span class="special">);</span>
+
+ <span class="comment">// Accessor to parameter:
+</span> <span class="identifier">RealType</span> <span class="identifier">degrees_of_freedom</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+
+ <span class="comment">// Parameter estimation:
+</span> <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_degrees_of_freedom</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">difference_from_mean</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">beta</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">sd</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">hint</span> <span class="special">=</span> <span class="number">100</span><span class="special">);</span>
+<span class="special">};</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The Chi-Squared distribution is one of the most widely used distributions
+ in statistical tests. If &#967;<sub>i</sub> are &#957;
+independent, normally distributed random
+ variables with means &#956;<sub>i</sub> and variances &#963;<sub>i</sub><sup>2</sup>, then the random variable:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../equations/chi_squ_ref1.png"></span>
+ </p>
+<p>
+ is distributed according to the Chi-Squared distribution.
+ </p>
+<p>
+ The Chi-Squared distribution is a special case of the gamma distribution
+ and has a single parameter &#957; that specifies the number of degrees of freedom.
+ The following graph illustrates how the distribution changes for different
+ values of &#957;:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/chi_square.png" alt="chi_square"></span>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.chi_squared_dist.member_functions"></a><h5>
+<a name="id588926"></a>
+ <a href="chi_squared_dist.html#math_toolkit.dist.dist_ref.dists.chi_squared_dist.member_functions">Member
+ Functions</a>
+ </h5>
+<pre class="programlisting">
+<span class="identifier">chi_squared_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">v</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs a Chi-Squared distribution with <span class="emphasis"><em>v</em></span> degrees
+ of freedom.
+ </p>
+<p>
+ Requires v &gt; 0, otherwise calls domain_error.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">degrees_of_freedom</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the parameter <span class="emphasis"><em>v</em></span> from which this object was
+ constructed.
+ </p>
+<pre class="programlisting">
+<span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_degrees_of_freedom</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">difference_from_variance</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">beta</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">variance</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">hint</span> <span class="special">=</span> <span class="number">100</span><span class="special">);</span>
+</pre>
+<p>
+ Estimates the sample size required to detect a difference from a nominal
+ variance in a Chi-Squared test for equal standard deviations.
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">difference_from_variance</span></dt>
+<dd><p>
+ The difference from the assumed nominal variance that is to be detected:
+ Note that the sign of this value is critical, see below.
+ </p></dd>
+<dt><span class="term">alpha</span></dt>
+<dd><p>
+ The maximum acceptable risk of rejecting the null hypothesis when
+ it is in fact true.
+ </p></dd>
+<dt><span class="term">beta</span></dt>
+<dd><p>
+ The maximum acceptable risk of falsely failing to reject the null
+ hypothesis.
+ </p></dd>
+<dt><span class="term">variance</span></dt>
+<dd><p>
+ The nominal variance being tested against.
+ </p></dd>
+<dt><span class="term">hint</span></dt>
+<dd><p>
+ An optional hint on where to start looking for a result: the current
+ sample size would be a good choice.
+ </p></dd>
+</dl>
+</div>
+<p>
+ Note that this calculation works with <span class="emphasis"><em>variances</em></span>
+ and not <span class="emphasis"><em>standard deviations</em></span>.
+ </p>
+<p>
+ The sign of the parameter <span class="emphasis"><em>difference_from_variance</em></span>
+ is important: the Chi Squared distribution is asymmetric, and the caller
+ must decide in advance whether they are testing for a variance greater
+ than a nominal value (positive <span class="emphasis"><em>difference_from_variance</em></span>)
+ or testing for a variance less than a nominal value (negative <span class="emphasis"><em>difference_from_variance</em></span>).
+ If the latter, then obviously it is a requirement that <code class="computeroutput"><span class="identifier">variance</span> <span class="special">+</span>
+ <span class="identifier">difference_from_variance</span> <span class="special">&gt;</span>
+ <span class="number">0</span></code>, since no sample can have a negative
+ variance!
+ </p>
+<p>
+ This procedure uses the method in Diamond, W. J. (1989). Practical Experiment
+ Designs, Van-Nostrand Reinhold, New York.
+ </p>
+<p>
+ See also section on Sample sizes required in <a href="http://www.itl.nist.gov/div898/handbook/prc/section2/prc232.htm" target="_top">the
+ NIST Engineering Statistics Handbook, Section 7.2.3.2</a>.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.chi_squared_dist.non_member_accessors"></a><h5>
+<a name="id589374"></a>
+ <a href="chi_squared_dist.html#math_toolkit.dist.dist_ref.dists.chi_squared_dist.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The domain of the random variable is [0, +&#8734;].
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.chi_squared_dist.examples"></a><h5>
+<a name="id589544"></a>
+ Examples
+ </h5>
+<p>
+ Various worked examples
+ are available illustrating the use of the Chi Squared Distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.chi_squared_dist.accuracy"></a><h5>
+<a name="id589585"></a>
+ Accuracy
+ </h5>
+<p>
+ The Chi-Squared distribution is implemented in terms of the <a href="../../../special/sf_gamma/igamma.html" title="Incomplete Gamma Functions">incomplete
+ gamma functions</a>: please refer to the accuracy data for those functions.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.chi_squared_dist.implementation"></a><h5>
+<a name="id589627"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table <span class="emphasis"><em>v</em></span> is the number of degrees
+ of freedom of the distribution, <span class="emphasis"><em>x</em></span> is the random
+ variate, <span class="emphasis"><em>p</em></span> is the probability, and <span class="emphasis"><em>q =
+ 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: pdf = gamma_p_derivative(v
+ / 2, x / 2) / 2
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: p = gamma_p(v
+ / 2, x / 2)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: q = gamma_q(v
+ / 2, x / 2)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = 2 * gamma_p_inv(v
+ / 2, p)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = 2 * gamma_q_inv(v
+ / 2, p)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ v
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ variance
+ </p>
+ </td>
+<td>
+ <p>
+ 2v
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ v - 2 (if v &gt;= 2)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ 2 * sqrt(2 / v) == sqrt(8 / v)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ 3 + 12 / v
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ 12 / v
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.dist.dist_ref.dists.chi_squared_dist.references"></a><h5>
+<a name="id589971"></a>
+ References
+ </h5>
+<div class="itemizedlist"><ul type="disc">
+<li><a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3666.htm" target="_top">NIST
+ Exploratory Data Analysis</a></li>
+<li><a href="http://en.wikipedia.org/wiki/Chi-square_distribution" target="_top">Chi-square
+ distribution</a></li>
+<li><a href="http://mathworld.wolfram.com/Chi-SquaredDistribution.html" target="_top">Weisstein,
+ Eric W. "Chi-Squared Distribution." From MathWorld--A Wolfram
+ Web Resource.</a></li>
+</ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="cauchy_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="exp_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/exp_dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/exp_dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,315 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Exponential Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="chi_squared_dist.html" title="Chi Squared Distribution">
+<link rel="next" href="extreme_dist.html" title="Extreme Value Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="chi_squared_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="extreme_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.exp_dist"></a><a href="exp_dist.html" title="Exponential Distribution"> Exponential
+ Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">exponential</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">exponential_distribution</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">exponential_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">exponential</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">exponential_distribution</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span>
+
+ <span class="identifier">exponential_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">lambda</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+
+ <span class="identifier">RealType</span> <span class="identifier">lambda</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ The <a href="http://en.wikipedia.org/wiki/Exponential_distribution" target="_top">exponential
+ distribution</a> is a <a href="http://en.wikipedia.org/wiki/Probability_distribution" target="_top">continuous
+ probability distribution</a> with PDF:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../equations/exponential_dist_ref1.png"></span>
+ </p>
+<p>
+ It is often used to model the time between independent events that happen
+ at a constant average rate.
+ </p>
+<p>
+ The following graph shows how the distribution changes for different
+ values of the rate parameter lambda:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/exponential_dist.png" alt="exponential_dist"></span>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.exp_dist.member_functions"></a><h5>
+<a name="id590540"></a>
+ <a href="exp_dist.html#math_toolkit.dist.dist_ref.dists.exp_dist.member_functions">Member
+ Functions</a>
+ </h5>
+<pre class="programlisting">
+<span class="identifier">exponential_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">lambda</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs an <a href="http://en.wikipedia.org/wiki/Exponential_distribution" target="_top">Exponential
+ distribution</a> with parameter <span class="emphasis"><em>lambda</em></span>. Lambda
+ is defined as the reciprocal of the scale parameter.
+ </p>
+<p>
+ Requires lambda &gt; 0, otherwise calls domain_error.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">lambda</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Accessor function returns the lambda parameter of the distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.exp_dist.non_member_accessors"></a><h5>
+<a name="id590684"></a>
+ <a href="exp_dist.html#math_toolkit.dist.dist_ref.dists.exp_dist.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The domain of the random variable is [0, +&#8734;].
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.exp_dist.accuracy"></a><h5>
+<a name="id590856"></a>
+ Accuracy
+ </h5>
+<p>
+ The exponential distribution is implemented in terms of the standard
+ library functions <code class="computeroutput"><span class="identifier">exp</span></code>,
+ <code class="computeroutput"><span class="identifier">log</span></code>, <code class="computeroutput"><span class="identifier">log1p</span></code>
+ and <code class="computeroutput"><span class="identifier">expm1</span></code> and as such
+ should have very low error rates.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.exp_dist.implementation"></a><h5>
+<a name="id590933"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table &#955; is the parameter lambda of the distribution,
+ <span class="emphasis"><em>x</em></span> is the random variate, <span class="emphasis"><em>p</em></span>
+ is the probability and <span class="emphasis"><em>q = 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: pdf = &#955; * exp(-&#955; * x)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: p = 1 - exp(-x * &#955;) = -expm1(-x * &#955;)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: q = exp(-x * &#955;)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = -log(1-p) / &#955; = -log1p(-p) / &#955;
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = -log(q) / &#955;
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ 1/&#955;
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ standard deviation
+ </p>
+ </td>
+<td>
+ <p>
+ 1/&#955;
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ 0
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ 2
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ 9
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ 6
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.dist.dist_ref.dists.exp_dist.references"></a><h5>
+<a name="id591235"></a>
+ references
+ </h5>
+<div class="itemizedlist"><ul type="disc">
+<li><a href="http://mathworld.wolfram.com/ExponentialDistribution.html" target="_top">Weisstein,
+ Eric W. "Exponential Distribution." From MathWorld--A Wolfram
+ Web Resource</a></li>
+<li><a href="http://documents.wolfram.com/calccenter/Functions/ListsMatrices/Statistics/ExponentialDistribution.html" target="_top">Wolfram
+ Mathematica calculator</a></li>
+<li><a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm" target="_top">NIST
+ Exploratory Data Analysis</a></li>
+<li><a href="http://en.wikipedia.org/wiki/Exponential_distribution" target="_top">Wikipedia
+ Exponential distribution</a></li>
+</ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="chi_squared_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="extreme_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/extreme_dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/extreme_dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,330 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Extreme Value Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="exp_dist.html" title="Exponential Distribution">
+<link rel="next" href="f_dist.html" title="F Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="exp_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="f_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.extreme_dist"></a><a href="extreme_dist.html" title="Extreme Value Distribution"> Extreme
+ Value Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">extreme</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">extreme_value_distribution</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">extreme_value_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">extreme_value</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">extreme_value_distribution</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+
+ <span class="identifier">extreme_value_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">location</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+
+ <span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">RealType</span> <span class="identifier">location</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ There are various <a href="http://mathworld.wolfram.com/ExtremeValueDistribution.html" target="_top">extreme
+ value distributions</a> : this implementation represents the maximum
+ case, and is variously known as a Fisher-Tippett distribution, a log-Weibull
+ distribution or a Gumbel distribution.
+ </p>
+<p>
+ Extreme value theory is important for assessing risk for highly unusual
+ events, such as 100-year floods.
+ </p>
+<p>
+ More information can be found on the NIST,
+ Wikipedia,
+ Mathworld,
+ and <a href="http://en.wikipedia.org/wiki/Extreme_value_theory" target="_top">Extreme
+ value theory</a> websites.
+ </p>
+<p>
+ The distribution has a PDF given by:
+ </p>
+<p>
+ f(x) = (1/scale) e<sup>-(x-location)/scale</sup> e<sup>-e<sup>-(x-location)/scale</sup></sup>
+ </p>
+<p>
+ Which in the standard case (scale = 1, location = 0) reduces to:
+ </p>
+<p>
+ f(x) = e<sup>-x</sup>e<sup>-e<sup>-x</sup></sup>
+ </p>
+<p>
+ The following graph illustrates how the PDF varies with the location
+ parameter:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/extreme_val_dist.png" alt="extreme_val_dist"></span>
+ </p>
+<p>
+ And this graph illustrates how the PDF varies with the shape parameter:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/extreme_val_dist2.png" alt="extreme_val_dist2"></span>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.extreme_dist.member_functions"></a><h5>
+<a name="id591918"></a>
+ <a href="extreme_dist.html#math_toolkit.dist.dist_ref.dists.extreme_dist.member_functions">Member
+ Functions</a>
+ </h5>
+<pre class="programlisting">
+<span class="identifier">extreme_value_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">location</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs an Extreme Value distribution with the specified location
+ and scale parameters.
+ </p>
+<p>
+ Requires <code class="computeroutput"><span class="identifier">scale</span> <span class="special">&gt;</span>
+ <span class="number">0</span></code>, otherwise calls domain_error.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">location</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the location parameter of the distribution.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the scale parameter of the distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.extreme_dist.non_member_accessors"></a><h5>
+<a name="id592145"></a>
+ <a href="extreme_dist.html#math_toolkit.dist.dist_ref.dists.extreme_dist.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The domain of the random parameter is [-&#8734;, +&#8734;].
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.extreme_dist.accuracy"></a><h5>
+<a name="id592316"></a>
+ Accuracy
+ </h5>
+<p>
+ The extreme value distribution is implemented in terms of the standard
+ library <code class="computeroutput"><span class="identifier">exp</span></code> and <code class="computeroutput"><span class="identifier">log</span></code> functions and as such should have
+ very low error rates.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.extreme_dist.implementation"></a><h5>
+<a name="id592369"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table: <span class="emphasis"><em>a</em></span> is the location parameter,
+ <span class="emphasis"><em>b</em></span> is the scale parameter, <span class="emphasis"><em>x</em></span>
+ is the random variate, <span class="emphasis"><em>p</em></span> is the probability and
+ <span class="emphasis"><em>q = 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: pdf = exp((a-x)/b) * exp(-exp((a-x)/b)) /
+ b
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: p = exp(-exp((a-x)/b))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: q = -expm1(-exp((a-x)/b))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: a - log(-log(p)) * b
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: a - log(-log1p(-q)) * b
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ a + Euler-Mascheroni-constant
+ * b
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ standard deviation
+ </p>
+ </td>
+<td>
+ <p>
+ pi * b / sqrt(6)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ The same as the location parameter <span class="emphasis"><em>a</em></span>.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ 12 * sqrt(6) * zeta(3) / pi<sup>3</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ 27 / 5
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ kurtosis - 3 or 12 / 5
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="exp_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="f_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/f_dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/f_dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,439 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>F Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="extreme_dist.html" title="Extreme Value Distribution">
+<link rel="next" href="gamma_dist.html" title="Gamma (and Erlang) Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="extreme_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="gamma_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.f_dist"></a> F Distribution
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">fisher_f</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">fisher_f_distribution</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">fisher_f_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">fisher_f</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">fisher_f_distribution</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+
+ <span class="comment">// Construct:
+</span> <span class="identifier">fisher_f_distribution</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">RealType</span><span class="special">&amp;</span> <span class="identifier">i</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">RealType</span><span class="special">&amp;</span> <span class="identifier">j</span><span class="special">);</span>
+
+ <span class="comment">// Accessors:
+</span> <span class="identifier">RealType</span> <span class="identifier">degrees_of_freedom1</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">RealType</span> <span class="identifier">degrees_of_freedom2</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+<span class="special">};</span>
+
+<span class="special">}}</span> <span class="comment">//namespaces
+</span></pre>
+<p>
+ The F distribution is a continuous distribution that arises when testing
+ whether two samples have the same variance. If &#967;<sup>2</sup><sub>m</sub> and &#967;<sup>2</sup><sub>n</sub> are independent
+ variates each distributed as Chi-Squared with <span class="emphasis"><em>m</em></span>
+ and <span class="emphasis"><em>n</em></span> degrees of freedom, then the test statistic:
+ </p>
+<p>
+ F<sub>n,m</sub> = (&#967;<sup>2</sup><sub>n</sub> / n) / (&#967;<sup>2</sup><sub>m</sub> / m)
+ </p>
+<p>
+ Is distributed over the range [0, &#8734;] with an F distribution, and has the
+ PDF:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../equations/fisher_pdf.png"></span>
+ </p>
+<p>
+ The following graph illustrates how the PDF varies depending on the two
+ degrees of freedom parameters.
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/fisher_f.png" alt="fisher_f"></span>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.f_dist.member_functions"></a><h5>
+<a name="id593316"></a>
+ <a href="f_dist.html#math_toolkit.dist.dist_ref.dists.f_dist.member_functions">Member
+ Functions</a>
+ </h5>
+<pre class="programlisting">
+<span class="identifier">fisher_f_distribution</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">RealType</span><span class="special">&amp;</span> <span class="identifier">df1</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">RealType</span><span class="special">&amp;</span> <span class="identifier">df2</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs an F-distribution with numerator degrees of freedom <span class="emphasis"><em>df1</em></span>
+ and denominator degrees of freedom <span class="emphasis"><em>df2</em></span>.
+ </p>
+<p>
+ Requires that <span class="emphasis"><em>df1</em></span> and <span class="emphasis"><em>df2</em></span> are
+ both greater than zero, otherwise domain_error
+ is called.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">degrees_of_freedom1</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the numerator degrees of freedom parameter of the distribution.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">degrees_of_freedom2</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the denominator degrees of freedom parameter of the distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.f_dist.non_member_accessors"></a><h5>
+<a name="id593533"></a>
+ <a href="f_dist.html#math_toolkit.dist.dist_ref.dists.f_dist.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The domain of the random variable is [0, +&#8734;].
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.f_dist.examples"></a><h5>
+<a name="id593704"></a>
+ Examples
+ </h5>
+<p>
+ Various worked examples
+ are available illustrating the use of the F Distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.f_dist.accuracy"></a><h5>
+<a name="id593744"></a>
+ Accuracy
+ </h5>
+<p>
+ The normal distribution is implemented in terms of the <a href="../../../special/sf_beta/ibeta_function.html" title="Incomplete Beta Functions">incomplete
+ beta function</a> and it's inverses,
+ refer to those functions for accuracy data.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.f_dist.implementation"></a><h5>
+<a name="id593793"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table <span class="emphasis"><em>v1</em></span> and <span class="emphasis"><em>v2</em></span>
+ are the first and second degrees of freedom parameters of the distribution,
+ <span class="emphasis"><em>x</em></span> is the random variate, <span class="emphasis"><em>p</em></span>
+ is the probability, and <span class="emphasis"><em>q = 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ The usual form of the PDF is given by:
+ </p>
+ <p>
+ <span class="inlinemediaobject"><img src="../../../../../equations/fisher_pdf.png"></span>
+ </p>
+ <p>
+ However, that form is hard to evaluate directly without incurring
+ problems with either accuracy or numeric overflow.
+ </p>
+ <p>
+ Direct differentiation of the CDF expressed in terms of the incomplete
+ beta function
+ </p>
+ <p>
+ led to the following two formulas:
+ </p>
+ <p>
+ f<sub>v1,v2</sub>(x) = y * ibeta_derivative(v2
+ / 2, v1 / 2, v2 / (v2 + v1 * x))
+ </p>
+ <p>
+ with y = (v2 * v1) / ((v2 + v1 * x) * (v2 + v1 * x))
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ f<sub>v1,v2</sub>(x) = y * ibeta_derivative(v1
+ / 2, v2 / 2, v1 * x / (v2 + v1 * x))
+ </p>
+ <p>
+ with y = (z * v1 - x * v1 * v1) / z<sup>2</sup>
+ </p>
+ <p>
+ and z = v2 + v1 * x
+ </p>
+ <p>
+ The first of these is used for v1 * x &gt; v2, otherwise the
+ second is used.
+ </p>
+ <p>
+ The aim is to keep the <span class="emphasis"><em>x</em></span> argument to ibeta_derivative
+ away from 1 to avoid rounding error.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relations:
+ </p>
+ <p>
+ p = ibeta(v1
+ / 2, v2 / 2, v1 * x / (v2 + v1 * x))
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ p = ibetac(v2
+ / 2, v1 / 2, v2 / (v2 + v1 * x))
+ </p>
+ <p>
+ The first is used for v1 * x &gt; v2, otherwise the second is
+ used.
+ </p>
+ <p>
+ The aim is to keep the <span class="emphasis"><em>x</em></span> argument to ibeta
+ well away from 1 to avoid rounding error.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relations:
+ </p>
+ <p>
+ p = ibetac(v1
+ / 2, v2 / 2, v1 * x / (v2 + v1 * x))
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ p = ibeta(v2
+ / 2, v1 / 2, v2 / (v2 + v1 * x))
+ </p>
+ <p>
+ The first is used for v1 * x &lt; v2, otherwise the second is
+ used.
+ </p>
+ <p>
+ The aim is to keep the <span class="emphasis"><em>x</em></span> argument to ibeta
+ well away from 1 to avoid rounding error.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation:
+ </p>
+ <p>
+ x = v2 * a / (v1 * b)
+ </p>
+ <p>
+ where:
+ </p>
+ <p>
+ a = ibeta_inv(v1
+ / 2, v2 / 2, p)
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ b = 1 - a
+ </p>
+ <p>
+ Quantities <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span>
+ are both computed by ibeta_inv
+ without the subtraction implied above.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ <p>
+ from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation:
+ </p>
+ <p>
+ x = v2 * a / (v1 * b)
+ </p>
+ <p>
+ where
+ </p>
+ <p>
+ a = ibetac_inv(v1
+ / 2, v2 / 2, p)
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ b = 1 - a
+ </p>
+ <p>
+ Quantities <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span>
+ are both computed by ibetac_inv
+ without the subtraction implied above.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ v2 / (v2 - 2)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ variance
+ </p>
+ </td>
+<td>
+ <p>
+ 2 * v2<sup>2 </sup> * (v1 + v2 - 2) / (v1 * (v2 - 2) * (v2 - 2) * (v2 - 4))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ v2 * (v1 - 2) / (v1 * (v2 + 2))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ 2 * (v2 + 2 * v1 - 2) * sqrt((2 * v2 - 8) / (v1 * (v2 + v1 -
+ 2))) / (v2 - 6)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis and kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ Refer to, <a href="http://mathworld.wolfram.com/F-Distribution.html" target="_top">Weisstein,
+ Eric W. "F-Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="extreme_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="gamma_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/gamma_dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/gamma_dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,381 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Gamma (and Erlang) Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="f_dist.html" title="F Distribution">
+<link rel="next" href="lognormal_dist.html" title="Log Normal Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="f_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="lognormal_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.gamma_dist"></a><a href="gamma_dist.html" title="Gamma (and Erlang) Distribution"> Gamma
+ (and Erlang) Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">gamma_distribution</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span>
+
+ <span class="identifier">gamma_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">shape</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">1</span><span class="special">)</span>
+
+ <span class="identifier">RealType</span> <span class="identifier">shape</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+<span class="special">};</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The gamma distribution is a continuous probability distribution. When
+ the shape parameter is an integer then it is known as the Erlang Distribution.
+ It is also closely related to the Poisson and Chi Squared Distributions.
+ </p>
+<p>
+ When the shape parameter has an integer value, the distribution is the
+ <a href="http://en.wikipedia.org/wiki/Erlang_distribution" target="_top">Erlang
+ distribution</a>. Since this can be produced by ensuring that the
+ shape parameter has an integer value &gt; 0, the Erlang distribution
+ is not separately implemented.
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ To avoid potential confusion with the gamma functions, this distribution
+ does not provide the typedef:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">typedef</span> <span class="identifier">gamma_distibution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">gamma</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ Instead if you want a double precision gamma distribution you can use
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">boost</span><span class="special">::</span><span class="identifier">gamma_distribution</span><span class="special">&lt;&gt;</span></pre>
+<p>
+ </p>
+</td></tr>
+</table></div>
+<p>
+ For shape parameter <span class="emphasis"><em>k</em></span> and scale parameter &#952; it is
+ defined by the probability density function:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../equations/gamma_dist_ref1.png"></span>
+ </p>
+<p>
+ Sometimes an alternative formulation is used: given parameters &#945;= k and
+ &#946;= 1 / &#952;, then the distribution can be defined by the PDF:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../equations/gamma_dist_ref2.png"></span>
+ </p>
+<p>
+ In this form the inverse scale parameter is called a <span class="emphasis"><em>rate parameter</em></span>.
+ </p>
+<p>
+ Both forms are in common usage: this library uses the first definition
+ throughout. Therefore to construct a Gamma Distribution from a <span class="emphasis"><em>rate
+ parameter</em></span>, you should pass the reciprocal of the rate as the
+ scale parameter.
+ </p>
+<p>
+ The following two graphs illustrate how the PDF of the gamma distribution
+ varies as the parameters vary:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/gamma_dist1.png" alt="gamma_dist1"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/gamma_dist2.png" alt="gamma_dist2"></span>
+ </p>
+<p>
+ The <span class="bold"><strong>Erlang Distribution</strong></span> is the same
+ as the Gamma, but with the shape parameter an integer. It is often expressed
+ using a <span class="emphasis"><em>rate</em></span> rather than a <span class="emphasis"><em>scale</em></span>
+ as the second parameter (remember that the rate is the reciprocal of
+ the scale).
+ </p>
+<p>
+ Internally the functions used to implement the Gamma Distribution are
+ already optimised for small-integer arguments, so in general there should
+ be no great loss of performance from using a Gamma Distribution rather
+ than a dedicated Erlang Distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.gamma_dist.member_functions"></a><h5>
+<a name="id595190"></a>
+ <a href="gamma_dist.html#math_toolkit.dist.dist_ref.dists.gamma_dist.member_functions">Member
+ Functions</a>
+ </h5>
+<pre class="programlisting">
+<span class="identifier">gamma_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">shape</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs a gamma distribution with shape <span class="emphasis"><em>shape</em></span>
+ and scale <span class="emphasis"><em>scale</em></span>.
+ </p>
+<p>
+ Requires that the shape and scale parameters are greater than zero, otherwise
+ calls domain_error.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">shape</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the <span class="emphasis"><em>shape</em></span> parameter of this distribution.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the <span class="emphasis"><em>scale</em></span> parameter of this distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.gamma_dist.non_member_accessors"></a><h5>
+<a name="id595398"></a>
+ <a href="gamma_dist.html#math_toolkit.dist.dist_ref.dists.gamma_dist.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The domain of the random variable is [0,+&#8734;].
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.gamma_dist.accuracy"></a><h5>
+<a name="id595568"></a>
+ Accuracy
+ </h5>
+<p>
+ The lognormal distribution is implemented in terms of the incomplete
+ gamma functions gamma_p
+ and gamma_q
+ and their inverses gamma_p_inv
+ and gamma_q_inv:
+ refer to the accuracy data for those functions for more information.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.gamma_dist.implementation"></a><h5>
+<a name="id595637"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table <span class="emphasis"><em>k</em></span> is the shape parameter
+ of the distribution, &#952; is it's scale parameter, <span class="emphasis"><em>x</em></span>
+ is the random variate, <span class="emphasis"><em>p</em></span> is the probability and
+ <span class="emphasis"><em>q = 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: pdf = gamma_p_derivative(k,
+ x / &#952;) / &#952;
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: p = gamma_p(k,
+ x / &#952;)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: q = gamma_q(k,
+ x / &#952;)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = &#952;* gamma_p_inv(k,
+ p)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = &#952;* gamma_q_inv(k,
+ p)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ k&#952;
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ variance
+ </p>
+ </td>
+<td>
+ <p>
+ k&#952;<sup>2</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ (k-1)&#952; for <span class="emphasis"><em>k&gt;1</em></span> otherwise a domain_error
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ 2 / sqrt(k)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ 3 + 6 / k
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ 6 / k
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="f_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="lognormal_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/lognormal_dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/lognormal_dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,334 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Log Normal Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="gamma_dist.html" title="Gamma (and Erlang) Distribution">
+<link rel="next" href="negative_binomial_dist.html" title="Negative Binomial Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="gamma_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="negative_binomial_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.lognormal_dist"></a><a href="lognormal_dist.html" title="Log Normal Distribution">
+ Log Normal Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">lognormal</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">lognormal_distribution</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">lognormal_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">lognormal</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">lognormal_distribution</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span>
+ <span class="comment">// Construct:
+</span> <span class="identifier">lognormal_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">location</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+ <span class="comment">// Accessors:
+</span> <span class="identifier">RealType</span> <span class="identifier">location</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+<span class="special">};</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The lognormal distribution is the distribution that arises when the logarithm
+ of the random variable is normally distributed. A lognormal distribution
+ results when the variable is the product of a large number of independent,
+ identically-distributed variables.
+ </p>
+<p>
+ For location and scale parameters <span class="emphasis"><em>m</em></span> and <span class="emphasis"><em>s</em></span>
+ it is defined by the probability density function:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../equations/lognormal_ref.png"></span>
+ </p>
+<p>
+ The location and scale parameters are equivalent to the mean and standard
+ deviation of the logarithm of the random variable.
+ </p>
+<p>
+ The following graph illustrates the effect of the location parameter
+ on the PDF, note that the range of the random variable remains [0,+&#8734;]
+ irrespective of the value of the location parameter:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/lognormal1.png" alt="lognormal1"></span>
+ </p>
+<p>
+ The next graph illustrates the effect of the scale parameter on the PDF:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/lognormal2.png" alt="lognormal2"></span>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.lognormal_dist.member_functions"></a><h5>
+<a name="id596659"></a>
+ <a href="lognormal_dist.html#math_toolkit.dist.dist_ref.dists.lognormal_dist.member_functions">Member
+ Functions</a>
+ </h5>
+<pre class="programlisting">
+<span class="identifier">lognormal_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">location</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs a lognormal distribution with location <span class="emphasis"><em>location</em></span>
+ and scale <span class="emphasis"><em>scale</em></span>.
+ </p>
+<p>
+ The location parameter is the same as the mean of the logarithm of the
+ random variate.
+ </p>
+<p>
+ The scale parameter is the same as the standard deviation of the logarithm
+ of the random variate.
+ </p>
+<p>
+ Requires that the scale parameter is greater than zero, otherwise calls
+ domain_error.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">location</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the <span class="emphasis"><em>location</em></span> parameter of this distribution.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the <span class="emphasis"><em>scale</em></span> parameter of this distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.lognormal_dist.non_member_accessors"></a><h5>
+<a name="id596890"></a>
+ <a href="lognormal_dist.html#math_toolkit.dist.dist_ref.dists.lognormal_dist.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The domain of the random variable is [0,+&#8734;].
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.lognormal_dist.accuracy"></a><h5>
+<a name="id597058"></a>
+ Accuracy
+ </h5>
+<p>
+ The lognormal distribution is implemented in terms of the standard library
+ log and exp functions, plus the <a href="../../../special/sf_erf/error_function.html" title="Error Functions">error
+ function</a>, and as such should have very low error rates.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.lognormal_dist.implementation"></a><h5>
+<a name="id597099"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table <span class="emphasis"><em>m</em></span> is the location parameter
+ of the distribution, <span class="emphasis"><em>s</em></span> is it's scale parameter,
+ <span class="emphasis"><em>x</em></span> is the random variate, <span class="emphasis"><em>p</em></span>
+ is the probability and <span class="emphasis"><em>q = 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: pdf = e<sup>-(ln(x) - m)<sup>2 </sup> / 2s<sup>2 </sup> </sup> / (x * s * sqrt(2pi))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: p = cdf(normal_distribtion&lt;RealType&gt;(m,
+ s), log(x))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: q = cdf(complement(normal_distribtion&lt;RealType&gt;(m,
+ s), log(x)))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = exp(quantile(normal_distribtion&lt;RealType&gt;(m,
+ s), p))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = exp(quantile(complement(normal_distribtion&lt;RealType&gt;(m,
+ s), q)))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ e<sup>m + s<sup>2 </sup> / 2 </sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ variance
+ </p>
+ </td>
+<td>
+ <p>
+ (e<sup>s<sup>2</sup> </sup> - 1) * e<sup>2m + s<sup>2 </sup> </sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ e<sup>m + s<sup>2 </sup> </sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ sqrt(e<sup>s<sup>2</sup> </sup> - 1) * (2 + e<sup>s<sup>2</sup> </sup>)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ e<sup>4s<sup>2</sup> </sup> + 2e<sup>3s<sup>2</sup> </sup> + 3e<sup>2s<sup>2</sup> </sup> - 3
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ e<sup>4s<sup>2</sup> </sup> + 2e<sup>3s<sup>2</sup> </sup> + 3e<sup>2s<sup>2</sup> </sup> - 6
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="gamma_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="negative_binomial_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/negative_binomial_dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/negative_binomial_dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,923 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Negative Binomial Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="lognormal_dist.html" title="Log Normal Distribution">
+<link rel="next" href="normal_dist.html" title="Normal (Gaussian) Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lognormal_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="normal_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist"></a><a href="negative_binomial_dist.html" title="Negative Binomial Distribution">
+ Negative Binomial Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">negative_binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">negative_binomial_distribution</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">negative_binomial</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">negative_binomial_distribution</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span>
+ <span class="comment">// Constructor from successes and success_fraction:
+</span> <span class="identifier">negative_binomial_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">r</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">);</span>
+
+ <span class="comment">// Parameter accessors:
+</span> <span class="identifier">RealType</span> <span class="identifier">success_fraction</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span>
+
+ <span class="comment">// Bounds on success fraction:
+</span> <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_lower_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// alpha
+</span> <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_upper_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// alpha
+</span>
+ <span class="comment">// Estimate min/max number of trials:
+</span> <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span> <span class="comment">// Number of failures.
+</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// Success fraction.
+</span> <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// Probability threshold alpha.
+</span> <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_maximum_number_of_trials</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span> <span class="comment">// Number of failures.
+</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// Success fraction.
+</span> <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// Probability threshold alpha.
+</span><span class="special">};</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The class type <code class="computeroutput"><span class="identifier">negative_binomial_distribution</span></code>
+ represents a <a href="http://en.wikipedia.org/wiki/Negative_binomial_distribution" target="_top">negative_binomial
+ distribution</a>: it is used when there are exactly two mutually
+ exclusive outcomes of a <a href="http://en.wikipedia.org/wiki/Bernoulli_trial" target="_top">Bernoulli
+ trial</a>: these outcomes are labelled "success" and "failure".
+ </p>
+<p>
+ For k + r Bernoulli trials each with success fraction p, the negative_binomial
+ distribution gives the probability of observing k failures and r successes
+ with success on the last trial. The negative_binomial distribution assumes
+ that success_fraction p is fixed for all (k + r) trials.
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ The random variable for the negative binomial distribution is the number
+ of trials, (the number of successes is a fixed property of the distribution)
+ whereas for the binomial, the random variable is the number of successes,
+ for a fixed number of trials.
+ </p></td></tr>
+</table></div>
+<p>
+ It has the PDF:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../equations/neg_binomial_ref.png"></span>
+ </p>
+<p>
+ The following graph illustrate how the PDF varies as the success fraction
+ <span class="emphasis"><em>p</em></span> changes:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/neg_binomial_pdf1.png" alt="neg_binomial_pdf1"></span>
+ </p>
+<p>
+ Alternatively, this graph shows how the shape of the PDF varies as the
+ number of successes changes:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/neg_binomial_pdf2.png" alt="neg_binomial_pdf2"></span>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.related_distributions"></a><h5>
+<a name="id598550"></a>
+ <a href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.related_distributions">Related
+ Distributions</a>
+ </h5>
+<p>
+ The name negative binomial distribution is reserved by some to the case
+ where the successes parameter r is an integer. This integer version is
+ also called the <a href="http://mathworld.wolfram.com/PascalDistribution.html" target="_top">Pascal
+ distribution</a>.
+ </p>
+<p>
+ This implementation uses real numbers for the computation throughout
+ (because it uses the <span class="bold"><strong>real-valued</strong></span> incomplete
+ beta function family of functions). This real-valued version is also
+ called the Polya Distribution.
+ </p>
+<p>
+ The Poisson distribution is a generalization of the Pascal distribution,
+ where the success parameter r is an integer: to obtain the Pascal distribution
+ you must ensure that an integer value is provided for r, and take integer
+ values (floor or ceiling) from functions that return a number of successes.
+ </p>
+<p>
+ For large values of r (successes), the negative binomial distribution
+ converges to the Poisson distribution.
+ </p>
+<p>
+ The geometric distribution is a special case where the successes parameter
+ r = 1, so only a first and only success is required. geometric(p) = negative_binomial(1,
+ p).
+ </p>
+<p>
+ The Poisson distribution is a special case for large successes
+ </p>
+<p>
+ poisson(&#955;) = lim <sub>r &#8594; &#8734;</sub> negative_binomial(r, r / (&#955; + r)))
+ </p>
+<p>
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ The Negative Binomial distribution is a discrete distribution: internally
+ functions like the <code class="computeroutput"><span class="identifier">cdf</span></code>
+ and <code class="computeroutput"><span class="identifier">pdf</span></code> 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.
+ </p>
+<p>
+ The quantile function will by default return an integer result that
+ has been <span class="emphasis"><em>rounded outwards</em></span>. 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 <span class="emphasis"><em>at least</em></span> the requested coverage
+ will be present in the central region, and <span class="emphasis"><em>no more than</em></span>
+ the requested coverage will be present in the tails.
+ </p>
+<p>
+ This behaviour can be changed so that the quantile functions are
+ rounded differently, or even return a real-valued result using Policies. It is
+ strongly recommended that you read the tutorial <a href="../../../policy/pol_tutorial/understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">Understanding
+ Quantiles of Discrete Distributions</a> before using the quantile
+ function on the Negative Binomial distribution. The <a href="../../../policy/pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">reference
+ docs</a> describe how to change the rounding policy for these
+ distributions.
+ </p>
+</td></tr>
+</table></div>
+<p>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.member_functions"></a><h5>
+<a name="id598754"></a>
+ <a href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.member_functions">Member
+ Functions</a>
+ </h5>
+<a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.construct"></a><h6>
+<a name="id598782"></a>
+ Construct
+ </h6>
+<pre class="programlisting">
+<span class="identifier">negative_binomial_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">r</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">);</span>
+</pre>
+<p>
+ Constructor: <span class="emphasis"><em>r</em></span> is the total number of successes,
+ <span class="emphasis"><em>p</em></span> is the probability of success of a single trial.
+ </p>
+<p>
+ Requires: <code class="computeroutput"><span class="identifier">r</span> <span class="special">&gt;</span>
+ <span class="number">0</span></code> and <code class="computeroutput"><span class="number">0</span>
+ <span class="special">&lt;=</span> <span class="identifier">p</span>
+ <span class="special">&lt;=</span> <span class="number">1</span></code>.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.accessors"></a><h6>
+<a name="id598938"></a>
+ Accessors
+ </h6>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">success_fraction</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> <span class="comment">// successes / trials (0 &lt;= p &lt;= 1)
+</span></pre>
+<p>
+ Returns the parameter <span class="emphasis"><em>p</em></span> from which this distribution
+ was constructed.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> <span class="comment">// required successes (r &gt; 0)
+</span></pre>
+<p>
+ Returns the parameter <span class="emphasis"><em>r</em></span> from which this distribution
+ was constructed.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.lower_bound_on_parameter_p"></a><h6>
+<a name="id599066"></a>
+ <a href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.lower_bound_on_parameter_p">Lower
+ Bound on Parameter p</a>
+ </h6>
+<pre class="programlisting">
+<span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_lower_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">failures</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">)</span> <span class="comment">// (0 &lt;= alpha &lt;= 1), 0.05 equivalent to 95% confidence.
+</span></pre>
+<p>
+ Returns a <span class="bold"><strong>lower bound</strong></span> on the success
+ fraction:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">failures</span></dt>
+<dd><p>
+ The total number of failures before the r th success.
+ </p></dd>
+<dt><span class="term">successes</span></dt>
+<dd><p>
+ The number of successes required.
+ </p></dd>
+<dt><span class="term">alpha</span></dt>
+<dd><p>
+ The largest acceptable probability that the true value of the success
+ fraction is <span class="bold"><strong>less than</strong></span> the value
+ returned.
+ </p></dd>
+</dl>
+</div>
+<p>
+ For example, if you observe <span class="emphasis"><em>k</em></span> failures and <span class="emphasis"><em>r</em></span>
+ successes from <span class="emphasis"><em>n</em></span> = k + r trials the best estimate
+ for the success fraction is simply <span class="emphasis"><em>r/n</em></span>, but if you
+ want to be 95% sure that the true value is <span class="bold"><strong>greater
+ than</strong></span> some value, <span class="emphasis"><em>p<sub>min</sub></em></span>, then:
+ </p>
+<pre class="programlisting">
+<span class="identifier">p</span><sub>min</sub> <span class="special">=</span> <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">find_lower_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">failures</span><span class="special">,</span> <span class="identifier">successes</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
+</pre>
+<p>
+ <a href="../../stat_tut/weg/neg_binom_eg/neg_binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for the Negative Binomial Distribution">See
+ negative binomial confidence interval example.</a>
+ </p>
+<p>
+ This function uses the Clopper-Pearson method of computing the lower
+ bound on the success fraction, whilst many texts refer to this method
+ as giving an "exact" result in practice it produces an interval
+ that guarantees <span class="emphasis"><em>at least</em></span> the coverage required,
+ and may produce pessimistic estimates for some combinations of <span class="emphasis"><em>failures</em></span>
+ and <span class="emphasis"><em>successes</em></span>. See:
+ </p>
+<p>
+ <a href="http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf" target="_top">Yong
+ Cai and K. Krishnamoorthy, A Simple Improved Inferential Method for Some
+ Discrete Distributions. Computational statistics and data analysis, 2005,
+ vol. 48, no3, 605-621</a>.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.upper_bound_on_parameter_p"></a><h6>
+<a name="id599432"></a>
+ <a href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.upper_bound_on_parameter_p">Upper
+ Bound on Parameter p</a>
+ </h6>
+<pre class="programlisting">
+<span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_upper_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// (0 &lt;= alpha &lt;= 1), 0.05 equivalent to 95% confidence.
+</span></pre>
+<p>
+ Returns an <span class="bold"><strong>upper bound</strong></span> on the success
+ fraction:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">trials</span></dt>
+<dd><p>
+ The total number of trials conducted.
+ </p></dd>
+<dt><span class="term">successes</span></dt>
+<dd><p>
+ The number of successes that occurred.
+ </p></dd>
+<dt><span class="term">alpha</span></dt>
+<dd><p>
+ The largest acceptable probability that the true value of the success
+ fraction is <span class="bold"><strong>greater than</strong></span> the value
+ returned.
+ </p></dd>
+</dl>
+</div>
+<p>
+ For example, if you observe <span class="emphasis"><em>k</em></span> successes from <span class="emphasis"><em>n</em></span>
+ trials the best estimate for the success fraction is simply <span class="emphasis"><em>k/n</em></span>,
+ but if you want to be 95% sure that the true value is <span class="bold"><strong>less
+ than</strong></span> some value, <span class="emphasis"><em>p<sub>max</sub></em></span>, then:
+ </p>
+<pre class="programlisting">
+<span class="identifier">p</span><sub>max</sub> <span class="special">=</span> <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">find_upper_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">r</span><span class="special">,</span> <span class="identifier">k</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
+</pre>
+<p>
+ <a href="../../stat_tut/weg/neg_binom_eg/neg_binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for the Negative Binomial Distribution">See
+ negative binomial confidence interval example.</a>
+ </p>
+<p>
+ This function uses the Clopper-Pearson method of computing the lower
+ bound on the success fraction, whilst many texts refer to this method
+ as giving an "exact" result in practice it produces an interval
+ that guarantees <span class="emphasis"><em>at least</em></span> the coverage required,
+ and may produce pessimistic estimates for some combinations of <span class="emphasis"><em>failures</em></span>
+ and <span class="emphasis"><em>successes</em></span>. See:
+ </p>
+<p>
+ <a href="http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf" target="_top">Yong
+ Cai and K. Krishnamoorthy, A Simple Improved Inferential Method for Some
+ Discrete Distributions. Computational statistics and data analysis, 2005,
+ vol. 48, no3, 605-621</a>.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.estimating_number_of_trials_to_ensure_at_least_a_certain_number_of_failures"></a><h6>
+<a name="id599796"></a>
+ <a href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.estimating_number_of_trials_to_ensure_at_least_a_certain_number_of_failures">Estimating
+ Number of Trials to Ensure at Least a Certain Number of Failures</a>
+ </h6>
+<pre class="programlisting">
+<span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span> <span class="comment">// number of failures.
+</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// success fraction.
+</span> <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// probability threshold (0.05 equivalent to 95%).
+</span></pre>
+<p>
+ This functions estimates the number of trials required to achieve a certain
+ probability that <span class="bold"><strong>more than k failures will be observed</strong></span>.
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">k</span></dt>
+<dd><p>
+ The target number of failures to be observed.
+ </p></dd>
+<dt><span class="term">p</span></dt>
+<dd><p>
+ The probability of <span class="emphasis"><em>success</em></span> for each trial.
+ </p></dd>
+<dt><span class="term">alpha</span></dt>
+<dd><p>
+ The maximum acceptable risk that only k failures or fewer will be
+ observed.
+ </p></dd>
+</dl>
+</div>
+<p>
+ For example:
+ </p>
+<pre class="programlisting">
+<span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span><span class="number">10</span><span class="special">,</span> <span class="number">0.5</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the smallest number of trials we must conduct to be 95% sure
+ of seeing 10 failures that occur with frequency one half.
+ </p>
+<p>
+ <a href="../../stat_tut/weg/neg_binom_eg/neg_binom_size_eg.html" title="Estimating Sample Sizes for the Negative Binomial.">Worked
+ Example.</a>
+ </p>
+<p>
+ This function uses numeric inversion of the negative binomial distribution
+ to obtain the result: another interpretation of the result, is that it
+ finds the number of trials (success+failures) that will lead to an <span class="emphasis"><em>alpha</em></span>
+ probability of observing k failures or fewer.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.estimating_number_of_trials_to_ensure_a_maximum_number_of_failures_or_less"></a><h6>
+<a name="id600106"></a>
+ <a href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.estimating_number_of_trials_to_ensure_a_maximum_number_of_failures_or_less">Estimating
+ Number of Trials to Ensure a Maximum Number of Failures or Less</a>
+ </h6>
+<pre class="programlisting">
+<span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_maximum_number_of_trials</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span> <span class="comment">// number of failures.
+</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// success fraction.
+</span> <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// probability threshold (0.05 equivalent to 95%).
+</span></pre>
+<p>
+ This functions estimates the maximum number of trials we can conduct
+ and achieve a certain probability that <span class="bold"><strong>k failures
+ or fewer will be observed</strong></span>.
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">k</span></dt>
+<dd><p>
+ The maximum number of failures to be observed.
+ </p></dd>
+<dt><span class="term">p</span></dt>
+<dd><p>
+ The probability of <span class="emphasis"><em>success</em></span> for each trial.
+ </p></dd>
+<dt><span class="term">alpha</span></dt>
+<dd><p>
+ The maximum acceptable <span class="emphasis"><em>risk</em></span> that more than k
+ failures will be observed.
+ </p></dd>
+</dl>
+</div>
+<p>
+ For example:
+ </p>
+<pre class="programlisting">
+<span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;::</span><span class="identifier">find_maximum_number_of_trials</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">1.0</span><span class="special">-</span><span class="number">1.0</span><span class="special">/</span><span class="number">1000000</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the largest number of trials we can conduct and still be 95%
+ sure of seeing no failures that occur with frequency one in one million.
+ </p>
+<p>
+ This function uses numeric inversion of the negative binomial distribution
+ to obtain the result: another interpretation of the result, is that it
+ finds the number of trials (success+failures) that will lead to an <span class="emphasis"><em>alpha</em></span>
+ probability of observing more than k failures.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.non_member_accessors"></a><h5>
+<a name="id600425"></a>
+ <a href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ However it's worth taking a moment to define what these actually mean
+ in the context of this distribution:
+ </p>
+<div class="table">
+<a name="id600589"></a><p class="title"><b>Table 8. Meaning of the non-member accessors.</b></p>
+<div class="table-contents"><table class="table" summary="Meaning of the non-member accessors.">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Meaning
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ Probability Density Function
+ </p>
+ </td>
+<td>
+ <p>
+ The probability of obtaining <span class="bold"><strong>exactly k failures</strong></span>
+ from k+r trials with success fraction p. For example:
+ </p>
+ <p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">pdf</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">)</span></pre>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Cumulative Distribution Function
+ </p>
+ </td>
+<td>
+ <p>
+ The probability of obtaining <span class="bold"><strong>k failures or
+ fewer</strong></span> from k+r trials with success fraction p and success
+ on the last trial. For example:
+ </p>
+ <p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cdf</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">)</span></pre>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../nmp.html#math.dist.ccdf">Complement of the Cumulative Distribution
+ Function</a>
+ </p>
+ </td>
+<td>
+ <p>
+ The probability of obtaining <span class="bold"><strong>more than k
+ failures</strong></span> from k+r trials with success fraction p and
+ success on the last trial. For example:
+ </p>
+ <p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">))</span></pre>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ The <span class="bold"><strong>greatest</strong></span> number of failures
+ k expected to be observed from k+r trials with success fraction
+ p, at probability P. Note that the value returned is a real-number,
+ and not an integer. Depending on the use case you may want to take
+ either the floor or ceiling of the real result. For example:
+ </p>
+ <p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">quantile</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">P</span><span class="special">)</span></pre>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../nmp.html#math.dist.quantile_c">Quantile from the complement
+ of the probability</a>
+ </p>
+ </td>
+<td>
+ <p>
+ The <span class="bold"><strong>smallest</strong></span> number of failures
+ k expected to be observed from k+r trials with success fraction
+ p, at probability P. Note that the value returned is a real-number,
+ and not an integer. Depending on the use case you may want to take
+ either the floor or ceiling of the real result. For example:
+</p>
+<pre class="programlisting">
+<span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">P</span><span class="special">))</span></pre>
+<p>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.accuracy"></a><h5>
+<a name="id601153"></a>
+ Accuracy
+ </h5>
+<p>
+ This distribution is implemented using the incomplete beta functions
+ ibeta
+ and ibetac:
+ please refer to these functions for information on accuracy.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.implementation"></a><h5>
+<a name="id601202"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table, <span class="emphasis"><em>p</em></span> is the probability that
+ any one trial will be successful (the success fraction), <span class="emphasis"><em>r</em></span>
+ is the number of successes, <span class="emphasis"><em>k</em></span> is the number of failures,
+ <span class="emphasis"><em>p</em></span> is the probability and <span class="emphasis"><em>q = 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ pdf = exp(lgamma(r + k) - lgamma(r) - lgamma(k+1)) * pow(p, r)
+ * pow((1-p), k)
+ </p>
+ <p>
+ Implementation is in terms of ibeta_derivative:
+ </p>
+ <p>
+ (p/(r + k)) * ibeta_derivative(r, static_cast&lt;RealType&gt;(k+1),
+ p) The function ibeta_derivative
+ is used here, since it has already been optimised for the lowest
+ possible error - indeed this is really just a thin wrapper around
+ part of the internals of the incomplete beta function.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation:
+ </p>
+ <p>
+ cdf = I<sub>p</sub>(r, k+1) = ibeta(r, k+1, p)
+ </p>
+ <p>
+ = ibeta(r, static_cast&lt;RealType&gt;(k+1), p)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation:
+ </p>
+ <p>
+ 1 - cdf = I<sub>p</sub>(k+1, r)
+ </p>
+ <p>
+ = ibetac(r, static_cast&lt;RealType&gt;(k+1), p)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ ibeta_invb(r, p, P) - 1
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ ibetac_invb(r, p, Q) -1)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">r</span><span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">p</span><span class="special">)/</span><span class="identifier">p</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ variance
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">r</span> <span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">p</span><span class="special">)</span>
+ <span class="special">/</span> <span class="identifier">p</span>
+ <span class="special">*</span> <span class="identifier">p</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">floor</span><span class="special">((</span><span class="identifier">r</span><span class="special">-</span><span class="number">1</span><span class="special">)</span> <span class="special">*</span> <span class="special">(</span><span class="number">1</span> <span class="special">-</span> <span class="identifier">p</span><span class="special">)/</span><span class="identifier">p</span><span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special">(</span><span class="number">2</span>
+ <span class="special">-</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">/</span>
+ <span class="identifier">sqrt</span><span class="special">(</span><span class="identifier">r</span> <span class="special">*</span>
+ <span class="special">(</span><span class="number">1</span>
+ <span class="special">-</span> <span class="identifier">p</span><span class="special">))</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="number">6</span> <span class="special">/</span>
+ <span class="identifier">r</span> <span class="special">+</span>
+ <span class="special">(</span><span class="identifier">p</span>
+ <span class="special">*</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">/</span>
+ <span class="identifier">r</span> <span class="special">*</span>
+ <span class="special">(</span><span class="number">1</span>
+ <span class="special">-</span> <span class="identifier">p</span>
+ <span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="computeroutput"><span class="number">6</span> <span class="special">/</span>
+ <span class="identifier">r</span> <span class="special">+</span>
+ <span class="special">(</span><span class="identifier">p</span>
+ <span class="special">*</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">/</span>
+ <span class="identifier">r</span> <span class="special">*</span>
+ <span class="special">(</span><span class="number">1</span>
+ <span class="special">-</span> <span class="identifier">p</span>
+ <span class="special">)</span> <span class="special">-</span><span class="number">3</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ parameter estimation member functions
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">find_lower_bound_on_p</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ ibeta_inv(successes, failures + 1, alpha)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">find_upper_bound_on_p</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ ibetac_inv(successes, failures, alpha) plus see comments in code.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">find_minimum_number_of_trials</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ ibeta_inva(k + 1, p, alpha)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">find_maximum_number_of_trials</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ ibetac_inva(k + 1, p, alpha)
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<p>
+ Implementation notes:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ The real concept type (that deliberately lacks the Lanczos approximation),
+ was found to take several minutes to evaluate some extreme test values,
+ so the test has been disabled for this type.
+ </li>
+<li>
+ Much greater speed, and perhaps greater accuracy, might be achieved
+ for extreme values by using a normal approximation. This is NOT been
+ tested or implemented.
+ </li>
+</ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lognormal_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="normal_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/normal_dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/normal_dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,305 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Normal (Gaussian) Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="negative_binomial_dist.html" title="Negative Binomial Distribution">
+<link rel="next" href="pareto.html" title="Pareto Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="negative_binomial_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="pareto.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.normal_dist"></a><a href="normal_dist.html" title="Normal (Gaussian) Distribution"> Normal
+ (Gaussian) Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">normal</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">normal_distribution</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">normal_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">normal</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">normal_distribution</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span>
+ <span class="comment">// Construct:
+</span> <span class="identifier">normal_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">mean</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">sd</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+ <span class="comment">// Accessors:
+</span> <span class="identifier">RealType</span> <span class="identifier">mean</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span> <span class="comment">// location.
+</span> <span class="identifier">RealType</span> <span class="identifier">standard_deviation</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span> <span class="comment">// scale.
+</span> <span class="comment">// Synonyms, provided to allow generic use of find_location and find_scale.
+</span> <span class="identifier">RealType</span> <span class="identifier">location</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+<span class="special">};</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The normal distribution is probably the most well known statistical distribution:
+ it is also known as the Gaussian Distribution. A normal distribution
+ with mean zero and standard deviation one is known as the <span class="emphasis"><em>Standard
+ Normal Distribution</em></span>.
+ </p>
+<p>
+ Given mean &#956; and standard deviation &#963; it has the PDF:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../equations/normal_ref1.png"></span>
+ </p>
+<p>
+ The variation the PDF with its parameters is illustrated in the following
+ graph:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/normal.png" alt="normal"></span>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.normal_dist.member_functions"></a><h5>
+<a name="id602896"></a>
+ <a href="normal_dist.html#math_toolkit.dist.dist_ref.dists.normal_dist.member_functions">Member
+ Functions</a>
+ </h5>
+<pre class="programlisting">
+<span class="identifier">normal_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">mean</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">sd</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs a normal distribution with mean <span class="emphasis"><em>mean</em></span>
+ and standard deviation <span class="emphasis"><em>sd</em></span>.
+ </p>
+<p>
+ Requires sd &gt; 0, otherwise domain_error
+ is called.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">mean</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+<span class="identifier">RealType</span> <span class="identifier">location</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ both return the <span class="emphasis"><em>mean</em></span> of this distribution.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">standard_deviation</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+<span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ both return the <span class="emphasis"><em>standard deviation</em></span> of this distribution.
+ (Redundant location and scale function are provided to match other similar
+ distributions, allowing the functions find_location and find_scale to
+ be used generically).
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.normal_dist.non_member_accessors"></a><h5>
+<a name="id603174"></a>
+ <a href="normal_dist.html#math_toolkit.dist.dist_ref.dists.normal_dist.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The domain of the random variable is [-[max_value], +[min_value]]. However,
+ the pdf of +&#8734; and -&#8734; = 0 is also supported, and cdf at -&#8734; = 0, cdf at +&#8734; = 1,
+ and complement cdf -&#8734; = 1 and +&#8734; = 0, if RealType permits.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.normal_dist.accuracy"></a><h5>
+<a name="id603354"></a>
+ Accuracy
+ </h5>
+<p>
+ The normal distribution is implemented in terms of the <a href="../../../special/sf_erf/error_function.html" title="Error Functions">error
+ function</a>, and as such should have very low error rates.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.normal_dist.implementation"></a><h5>
+<a name="id603393"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table <span class="emphasis"><em>m</em></span> is the mean of the distribution,
+ and <span class="emphasis"><em>s</em></span> is its standard deviation.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: pdf = e<sup>-(x-m)<sup>2</sup>/(2s<sup>2</sup>)</sup> / (s * sqrt(2*pi))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: p = 0.5 * erfc(-(x-m)/(s*sqrt(2)))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: q = 0.5 * erfc((x-m)/(s*sqrt(2)))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = m - s * sqrt(2) * erfc_inv(2*p)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = m + s * sqrt(2) * erfc_inv(2*p)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean and standard deviation
+ </p>
+ </td>
+<td>
+ <p>
+ The same as <code class="computeroutput"><span class="identifier">dist</span><span class="special">.</span><span class="identifier">mean</span><span class="special">()</span></code> and <code class="computeroutput"><span class="identifier">dist</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ The same as the mean.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ 0
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ 3
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ 0
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="negative_binomial_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="pareto.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/pareto.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/pareto.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,338 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Pareto Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="normal_dist.html" title="Normal (Gaussian) Distribution">
+<link rel="next" href="poisson_dist.html" title="Poisson Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="normal_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="poisson_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.pareto"></a><a href="pareto.html" title="Pareto Distribution"> Pareto
+ Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">pareto</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">pareto_distribution</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">pareto_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">pareto</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">pareto_distribution</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="comment">// Constructor:
+</span> <span class="identifier">pareto_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">location</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">shape</span> <span class="special">=</span> <span class="number">1</span><span class="special">)</span>
+ <span class="comment">// Accessors:
+</span> <span class="identifier">RealType</span> <span class="identifier">location</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">RealType</span> <span class="identifier">shape</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+<span class="special">};</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The <a href="http://en.wikipedia.org/wiki/pareto_distribution" target="_top">Pareto
+ distribution</a> is a continuous distribution with the <a href="http://en.wikipedia.org/wiki/Probability_density_function" target="_top">probability
+ density function (pdf)</a>:
+ </p>
+<p>
+ f(x; &#945;, &#946;) = &#945;&#946;<sup>&#945;</sup> / x<sup>&#945;+ 1</sup>
+ </p>
+<p>
+ For shape parameter &#945; &gt; 0, and location parameter &#946; &gt; 0, and &#945; &gt; 0.
+ </p>
+<p>
+ The <a href="http://mathworld.wolfram.com/paretoDistribution.html" target="_top">Pareto
+ distribution</a> often describes the larger compared to the smaller.
+ A classic example is that 80% of the wealth is owned by 20% of the population.
+ </p>
+<p>
+ The following graph illustrates how the PDF varies with the shape parameter
+ &#945;:
+ </p>
+<p>
+ <a href="http://upload.wikimedia.org/wikipedia/commons/thumb/d/d9/Pareto_distributionPDF.png/325px-Pareto_distributionPDF.png" target="_top">Pareto
+ pdf</a>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.pareto.related_distributions"></a><h5>
+<a name="id604352"></a>
+ <a href="pareto.html#math_toolkit.dist.dist_ref.dists.pareto.related_distributions">Related
+ distributions</a>
+ </h5>
+<a name="math_toolkit.dist.dist_ref.dists.pareto.member_functions"></a><h5>
+<a name="id604376"></a>
+ <a href="pareto.html#math_toolkit.dist.dist_ref.dists.pareto.member_functions">Member
+ Functions</a>
+ </h5>
+<pre class="programlisting">
+<span class="identifier">pareto_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">location</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">shape</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs a <a href="http://en.wikipedia.org/wiki/pareto_distribution" target="_top">pareto
+ distribution</a> with shape <span class="emphasis"><em>shape</em></span> and scale
+ <span class="emphasis"><em>scale</em></span>.
+ </p>
+<p>
+ Requires that the <span class="emphasis"><em>shape</em></span> and <span class="emphasis"><em>scale</em></span>
+ parameters are both greater than zero, otherwise calls domain_error.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">location</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the <span class="emphasis"><em>location</em></span> parameter of this distribution.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">shape</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the <span class="emphasis"><em>shape</em></span> parameter of this distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.pareto.non_member_accessors"></a><h5>
+<a name="id604611"></a>
+ <a href="pareto.html#math_toolkit.dist.dist_ref.dists.pareto.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The supported domain of the random variable is [location, &#8734;].
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.pareto.accuracy"></a><h5>
+<a name="id604783"></a>
+ Accuracy
+ </h5>
+<p>
+ The pareto distribution is implemented in terms of the standard library
+ <code class="computeroutput"><span class="identifier">exp</span></code> functions plus expm1 and as such
+ should have very low error rates except when probability is very close
+ to unity.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.pareto.implementation"></a><h5>
+<a name="id604837"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table &#945; is the shape parameter of the distribution, and
+ &#946; is its location parameter, <span class="emphasis"><em>x</em></span> is the random variate,
+ <span class="emphasis"><em>p</em></span> is the probability and its complement <span class="emphasis"><em>q
+ = 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: pdf p = &#945;&#946;<sup>&#945;</sup>/x<sup>&#945; +1</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: cdf p = 1 - (&#946; / x)<sup>&#945;</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: q = 1 - p = -(&#946; / x)<sup>&#945;</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = &#945; / (1 - p)<sup>1/&#946;</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = &#945; / (q)<sup>1/&#946;</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ &#945;&#946; / (&#946; - 1)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ variance
+ </p>
+ </td>
+<td>
+ <p>
+ &#946;&#945;<sup>2</sup> / (&#946; - 1)<sup>2</sup> (&#946; - 2)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ &#945;
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ Refer to <a href="http://mathworld.wolfram.com/paretoDistribution.html" target="_top">Weisstein,
+ Eric W. "Pareto Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ Refer to <a href="http://mathworld.wolfram.com/paretoDistribution.html" target="_top">Weisstein,
+ Eric W. "Pareto Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ Refer to <a href="http://mathworld.wolfram.com/paretoDistribution.html" target="_top">Weisstein,
+ Eric W. "pareto Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.dist.dist_ref.dists.pareto.references"></a><h5>
+<a name="id605194"></a>
+ References
+ </h5>
+<div class="itemizedlist"><ul type="disc">
+<li><a href="http://en.wikipedia.org/wiki/pareto_distribution" target="_top">Pareto
+ Distribution</a></li>
+<li><a href="http://mathworld.wolfram.com/paretoDistribution.html" target="_top">Weisstein,
+ Eric W. "Pareto Distribution." From MathWorld--A Wolfram
+ Web Resource.</a></li>
+</ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="normal_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="poisson_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/poisson_dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/poisson_dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,341 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Poisson Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="pareto.html" title="Pareto Distribution">
+<link rel="next" href="rayleigh.html" title="Rayleigh Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="pareto.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="rayleigh.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.poisson_dist"></a><a href="poisson_dist.html" title="Poisson Distribution"> Poisson
+ Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">poisson</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span> <span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">poisson_distribution</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">poisson_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">poisson</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">poisson_distribution</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span>
+
+ <span class="identifier">poisson_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">mean</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// Constructor.
+</span> <span class="identifier">RealType</span> <span class="identifier">mean</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span> <span class="comment">// Accessor.
+</span><span class="special">}</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces boost::math
+</span></pre>
+<p>
+ The <a href="http://en.wikipedia.org/wiki/Poisson_distribution" target="_top">Poisson
+ distribution</a> is a well-known statistical discrete distribution.
+ It expresses the probability of a number of events (or failures, arrivals,
+ occurrences ...) occurring in a fixed period of time, provided these
+ events occur with a known mean rate &#955;
+(events/time), and are independent
+ of the time since the last event.
+ </p>
+<p>
+ The distribution was discovered by Simé on-Denis Poisson (1781 to 1840).
+ </p>
+<p>
+ It has the Probability Mass Function:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../equations/poisson_ref1.png"></span>
+ </p>
+<p>
+ for k events, with an expected number of events &#955;.
+ </p>
+<p>
+ The following graph illustrates how the PDF varies with the parameter
+ &#955;:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/poisson.png" alt="poisson"></span>
+ </p>
+<p>
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ The Poisson distribution is a discrete distribution: internally functions
+ like the <code class="computeroutput"><span class="identifier">cdf</span></code> and
+ <code class="computeroutput"><span class="identifier">pdf</span></code> 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.
+ </p>
+<p>
+ The quantile function will by default return an integer result that
+ has been <span class="emphasis"><em>rounded outwards</em></span>. 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 <span class="emphasis"><em>at least</em></span> the requested coverage
+ will be present in the central region, and <span class="emphasis"><em>no more than</em></span>
+ the requested coverage will be present in the tails.
+ </p>
+<p>
+ This behaviour can be changed so that the quantile functions are
+ rounded differently, or even return a real-valued result using Policies. It is
+ strongly recommended that you read the tutorial <a href="../../../policy/pol_tutorial/understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">Understanding
+ Quantiles of Discrete Distributions</a> before using the quantile
+ function on the Poisson distribution. The <a href="../../../policy/pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">reference
+ docs</a> describe how to change the rounding policy for these
+ distributions.
+ </p>
+</td></tr>
+</table></div>
+<p>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.poisson_dist.member_functions"></a><h5>
+<a name="id605938"></a>
+ <a href="poisson_dist.html#math_toolkit.dist.dist_ref.dists.poisson_dist.member_functions">Member
+ Functions</a>
+ </h5>
+<pre class="programlisting">
+<span class="identifier">poisson_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">mean</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs a poisson distribution with mean <span class="emphasis"><em>mean</em></span>.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">mean</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the <span class="emphasis"><em>mean</em></span> of this distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.poisson_dist.non_member_accessors"></a><h5>
+<a name="id606064"></a>
+ <a href="poisson_dist.html#math_toolkit.dist.dist_ref.dists.poisson_dist.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The domain of the random variable is [0, &#8734;].
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.poisson_dist.accuracy"></a><h5>
+<a name="id606233"></a>
+ Accuracy
+ </h5>
+<p>
+ The Poisson distribution is implemented in terms of the incomplete gamma
+ functions gamma_p
+ and gamma_q
+ and as such should have low error rates: but refer to the documentation
+ of those functions for more information. The quantile and its complement
+ use the inverse gamma functions and are therefore probably slightly less
+ accurate: this is because the inverse gamma functions are implemented
+ using an iterative method with a lower tolerance to avoid excessive computation.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.poisson_dist.implementation"></a><h5>
+<a name="id606282"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table &#955; is the mean of the distribution, <span class="emphasis"><em>k</em></span>
+ is the random variable, <span class="emphasis"><em>p</em></span> is the probability and
+ <span class="emphasis"><em>q = 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: pdf = e<sup>-&#955;</sup> &#955;<sup>k</sup> / k!
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: p = &#915;(k+1, &#955;) / k! = gamma_q(k+1,
+ &#955;)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: q = gamma_p(k+1,
+ &#955;)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: k = gamma_q_inva(&#955;,
+ p) - 1
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: k = gamma_p_inva(&#955;,
+ q) - 1
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ &#955;
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ floor (&#955;) or &#8970;&#955;&#8971;
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ 1/&#8730;&#955;
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ 3 + 1/&#955;
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ 1/&#955;
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="pareto.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="rayleigh.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/rayleigh.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/rayleigh.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,347 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Rayleigh Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="poisson_dist.html" title="Poisson Distribution">
+<link rel="next" href="students_t_dist.html" title="Students t Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="poisson_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="students_t_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.rayleigh"></a><a href="rayleigh.html" title="Rayleigh Distribution"> Rayleigh
+ Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">rayleigh</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">rayleigh_distribution</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">rayleigh_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">rayleigh</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">rayleigh_distribution</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span>
+ <span class="comment">// Construct:
+</span> <span class="identifier">rayleigh_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">sigma</span> <span class="special">=</span> <span class="number">1</span><span class="special">)</span>
+ <span class="comment">// Accessors:
+</span> <span class="identifier">RealType</span> <span class="identifier">sigma</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+<span class="special">};</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The <a href="http://en.wikipedia.org/wiki/Rayleigh_distribution" target="_top">Rayleigh
+ distribution</a> is a continuous distribution with the <a href="http://en.wikipedia.org/wiki/Probability_density_function" target="_top">probability
+ density function</a>:
+ </p>
+<p>
+ f(x; sigma) = x * exp(-x<sup>2</sup>/2 &#963;<sup>2</sup>) / &#963;<sup>2</sup>
+ </p>
+<p>
+ For sigma parameter &#963; &gt; 0, and x &gt; 0.
+ </p>
+<p>
+ The Rayleigh distribution is often used where two orthogonal components
+ have an absolute value, for example, wind velocity and direction may
+ be combined to yield a wind speed, or real and imaginary components may
+ have absolute values that are Rayleigh distributed.
+ </p>
+<p>
+ The following graph illustrates how the Probability density Function(pdf)
+ varies with the shape parameter &#963;:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/rayleigh_pdf.png" alt="rayleigh_pdf"></span>
+ </p>
+<p>
+ and the Cumulative Distribution Function (cdf)
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/rayleigh_cdf.png" alt="rayleigh_cdf"></span>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.rayleigh.related_distributions"></a><h5>
+<a name="id607194"></a>
+ <a href="rayleigh.html#math_toolkit.dist.dist_ref.dists.rayleigh.related_distributions">Related
+ distributions</a>
+ </h5>
+<p>
+ The absolute value of two independent normal distributions X and Y, &#8730; (X<sup>2</sup> +
+ Y<sup>2</sup>) is a Rayleigh distribution.
+ </p>
+<p>
+ The Chi,
+ Rice
+ and Weibull
+ distributions are generalizations of the <a href="http://en.wikipedia.org/wiki/Rayleigh_distribution" target="_top">Rayleigh
+ distribution</a>.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.rayleigh.member_functions"></a><h5>
+<a name="id607270"></a>
+ <a href="rayleigh.html#math_toolkit.dist.dist_ref.dists.rayleigh.member_functions">Member
+ Functions</a>
+ </h5>
+<pre class="programlisting">
+<span class="identifier">rayleigh_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">sigma</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs a <a href="http://en.wikipedia.org/wiki/Rayleigh_distribution" target="_top">Rayleigh
+ distribution</a> with &#963; <span class="emphasis"><em>sigma</em></span>.
+ </p>
+<p>
+ Requires that the &#963; parameter is greater than zero, otherwise calls domain_error.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">sigma</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the <span class="emphasis"><em>sigma</em></span> parameter of this distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.rayleigh.non_member_accessors"></a><h5>
+<a name="id607419"></a>
+ <a href="rayleigh.html#math_toolkit.dist.dist_ref.dists.rayleigh.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The domain of the random variable is [0, max_value].
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.rayleigh.accuracy"></a><h5>
+<a name="id607589"></a>
+ Accuracy
+ </h5>
+<p>
+ The Rayleigh distribution is implemented in terms of the standard library
+ <code class="computeroutput"><span class="identifier">sqrt</span></code> and <code class="computeroutput"><span class="identifier">exp</span></code> and as such should have very low
+ error rates. Some constants such as skewness and kurtosis were calculated
+ using NTL RR type with 150-bit accuracy, about 50 decimal digits.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.rayleigh.implementation"></a><h5>
+<a name="id607645"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table &#963; is the sigma parameter of the distribution, <span class="emphasis"><em>x</em></span>
+ is the random variate, <span class="emphasis"><em>p</em></span> is the probability and
+ <span class="emphasis"><em>q = 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: pdf = x * exp(-x<sup>2</sup>)/2 &#963;<sup>2</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: p = 1 - exp(-x<sup>2</sup>/2) &#963;<sup>2</sup> = -expm1(-x<sup>2</sup>/2)
+ &#963;<sup>2</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: q = exp(-x<sup>2</sup>/ 2) * &#963;<sup>2</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = sqrt(-2 * &#963; <sup>2</sup>) * log(1 - p)) = sqrt(-2
+ * &#963; <sup>2</sup>) * log1p(-p))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = sqrt(-2 * &#963; <sup>2</sup>) * log(q))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ &#963; * sqrt(&#960;/2)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ variance
+ </p>
+ </td>
+<td>
+ <p>
+ &#963;<sup>2</sup> * (4 - &#960;/2)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ &#963;
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ Constant from <a href="http://mathworld.wolfram.com/RayleighDistribution.html" target="_top">Weisstein,
+ Eric W. "Weibull Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ Constant from <a href="http://mathworld.wolfram.com/RayleighDistribution.html" target="_top">Weisstein,
+ Eric W. "Weibull Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ Constant from <a href="http://mathworld.wolfram.com/RayleighDistribution.html" target="_top">Weisstein,
+ Eric W. "Weibull Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.dist.dist_ref.dists.rayleigh.references"></a><h5>
+<a name="id608035"></a>
+ References
+ </h5>
+<div class="itemizedlist"><ul type="disc">
+<li>http://en.wikipedia.org/wiki/Rayleigh_distribution</li>
+<li><a href="http://mathworld.wolfram.com/RayleighDistribution.html" target="_top">Weisstein,
+ Eric W. "Rayleigh Distribution." From MathWorld--A Wolfram
+ Web Resource.</a></li>
+</ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="poisson_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="students_t_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/students_t_dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/students_t_dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,424 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Students t Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="rayleigh.html" title="Rayleigh Distribution">
+<link rel="next" href="triangular_dist.html" title="Triangular Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="rayleigh.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="triangular_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.students_t_dist"></a><a href="students_t_dist.html" title="Students t Distribution">
+ Students t Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">students_t</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">students_t_distribution</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">students_t_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">students_t</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">students_t_distribution</span>
+<span class="special">{</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span>
+
+ <span class="comment">// Construct:
+</span> <span class="identifier">students_t_distribution</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">RealType</span><span class="special">&amp;</span> <span class="identifier">v</span><span class="special">);</span>
+
+ <span class="comment">// Accessor:
+</span> <span class="identifier">RealType</span> <span class="identifier">degrees_of_freedom</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+
+ <span class="comment">// degrees of freedom estimation:
+</span> <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_degrees_of_freedom</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">difference_from_mean</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">beta</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">sd</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">hint</span> <span class="special">=</span> <span class="number">100</span><span class="special">);</span>
+<span class="special">};</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ A statistical distribution published by William Gosset in 1908. His employer,
+ Guinness Breweries, required him to publish under a pseudonym, so he
+ chose "Student". Given N independent measurements, let
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../equations/students_t_dist.png"></span>
+ </p>
+<p>
+ where <span class="emphasis"><em>M</em></span> is the population mean,<span class="emphasis"><em>&#956;</em></span>
+ is the sample mean, and <span class="emphasis"><em>s</em></span> is the sample variance.
+ </p>
+<p>
+ Student's t-distribution is defined as the distribution of the random
+ variable t which is - very loosely - the "best" that we can
+ do not knowing the true standard deviation of the sample. It has the
+ PDF:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../equations/students_t_ref1.png"></span>
+ </p>
+<p>
+ The Student's t-distribution takes a single parameter: the number of
+ degrees of freedom of the sample. When the degrees of freedom is <span class="emphasis"><em>one</em></span>
+ then this distribution is the same as the Cauchy-distribution. As the
+ number of degrees of freedom tends towards infinity, then this distribution
+ approaches the normal-distribution. The following graph illustrates how
+ the PDF varies with the degrees of freedom &#957;:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/students_t.png" alt="students_t"></span>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.students_t_dist.member_functions"></a><h5>
+<a name="id608826"></a>
+ <a href="students_t_dist.html#math_toolkit.dist.dist_ref.dists.students_t_dist.member_functions">Member
+ Functions</a>
+ </h5>
+<pre class="programlisting">
+<span class="identifier">students_t_distribution</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">RealType</span><span class="special">&amp;</span> <span class="identifier">v</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs a Student's t-distribution with <span class="emphasis"><em>v</em></span> degrees
+ of freedom.
+ </p>
+<p>
+ Requires v &gt; 0, otherwise calls domain_error.
+ Note that non-integral degrees of freedom are supported, and meaningful
+ under certain circumstances.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">degrees_of_freedom</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the number of degrees of freedom of this distribution.
+ </p>
+<pre class="programlisting">
+<span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_degrees_of_freedom</span><span class="special">(</span>
+ <span class="identifier">RealType</span> <span class="identifier">difference_from_mean</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">beta</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">sd</span><span class="special">,</span>
+ <span class="identifier">RealType</span> <span class="identifier">hint</span> <span class="special">=</span> <span class="number">100</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the number of degrees of freedom required to observe a significant
+ result in the Student's t test when the mean differs from the "true"
+ mean by <span class="emphasis"><em>difference_from_mean</em></span>.
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">difference_from_mean</span></dt>
+<dd><p>
+ The difference between the true mean and the sample mean that we
+ wish to show is significant.
+ </p></dd>
+<dt><span class="term">alpha</span></dt>
+<dd><p>
+ The maximum acceptable probability of rejecting the null hypothesis
+ when it is in fact true.
+ </p></dd>
+<dt><span class="term">beta</span></dt>
+<dd><p>
+ The maximum acceptable probability of failing to reject the null
+ hypothesis when it is in fact false.
+ </p></dd>
+<dt><span class="term">sd</span></dt>
+<dd><p>
+ The sample standard deviation.
+ </p></dd>
+<dt><span class="term">hint</span></dt>
+<dd><p>
+ A hint for the location to start looking for the result, a good choice
+ for this would be the sample size of a previous borderline Student's
+ t test.
+ </p></dd>
+</dl>
+</div>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ Remember that for a two-sided test, you must divide alpha by two before
+ calling this function.
+ </p></td></tr>
+</table></div>
+<p>
+ For more information on this function see the <a href="http://www.itl.nist.gov/div898/handbook/prc/section2/prc222.htm" target="_top">NIST
+ Engineering Statistics Handbook</a>.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.students_t_dist.non_member_accessors"></a><h5>
+<a name="id609215"></a>
+ <a href="students_t_dist.html#math_toolkit.dist.dist_ref.dists.students_t_dist.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The domain of the random variable is [-&#8734;, +&#8734;].
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.students_t_dist.examples"></a><h5>
+<a name="id609384"></a>
+ Examples
+ </h5>
+<p>
+ Various worked examples
+ are available illustrating the use of the Student's t distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.students_t_dist.accuracy"></a><h5>
+<a name="id609423"></a>
+ Accuracy
+ </h5>
+<p>
+ The normal distribution is implemented in terms of the <a href="../../../special/sf_beta/ibeta_function.html" title="Incomplete Beta Functions">incomplete
+ beta function</a> and <a href="../../../special/sf_beta/ibeta_inv_function.html" title="The Incomplete Beta Function Inverses">it's
+ inverses</a>, refer to accuracy data on those functions for more information.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.students_t_dist.implementation"></a><h5>
+<a name="id609472"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table <span class="emphasis"><em>v</em></span> is the degrees of freedom
+ of the distribution, <span class="emphasis"><em>t</em></span> is the random variate, <span class="emphasis"><em>p</em></span>
+ is the probability and <span class="emphasis"><em>q = 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: pdf = (v / (v + t<sup>2</sup>))<sup>(1+v)/2 </sup> / (sqrt(v) *
+ beta(v/2,
+ 0.5))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relations:
+ </p>
+ <p>
+ p = 1 - z <span class="emphasis"><em>iff t &gt; 0</em></span>
+ </p>
+ <p>
+ p = z <span class="emphasis"><em>otherwise</em></span>
+ </p>
+ <p>
+ where z is given by:
+ </p>
+ <p>
+ ibeta(v
+ / 2, 0.5, v / (v + t<sup>2</sup>)) / 2 <span class="emphasis"><em>iff v &lt; 2t<sup>2</sup></em></span>
+ </p>
+ <p>
+ ibetac(0.5,
+ v / 2, t<sup>2 </sup> / (v + t<sup>2</sup>) / 2 <span class="emphasis"><em>otherwise</em></span>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: q = cdf(-t)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: t = sign(p - 0.5) * sqrt(v * y / x)
+ </p>
+ <p>
+ where:
+ </p>
+ <p>
+ x = ibeta_inv(v
+ / 2, 0.5, 2 * min(p, q))
+ </p>
+ <p>
+ y = 1 - x
+ </p>
+ <p>
+ The quantities <span class="emphasis"><em>x</em></span> and <span class="emphasis"><em>y</em></span>
+ are both returned by ibeta_inv
+ without the subtraction implied above.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: t = -quantile(q)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ 0
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ variance
+ </p>
+ </td>
+<td>
+ <p>
+ v / (v - 2)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ 0
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ 0
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ 3 * (v - 2) / (v - 4)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ 6 / (df - 4)
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="rayleigh.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="triangular_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/triangular_dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/triangular_dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,421 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Triangular Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="students_t_dist.html" title="Students t Distribution">
+<link rel="next" href="weibull.html" title="Weibull Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="students_t_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="weibull.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.triangular_dist"></a><a href="triangular_dist.html" title="Triangular Distribution">
+ Triangular Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">triangular</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+ <span class="keyword">class</span> <span class="identifier">triangular_distribution</span><span class="special">;</span>
+
+ <span class="keyword">typedef</span> <span class="identifier">triangular_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">triangular</span><span class="special">;</span>
+
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+ <span class="keyword">class</span> <span class="identifier">triangular_distribution</span>
+ <span class="special">{</span>
+ <span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span>
+
+ <span class="identifier">triangular_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">lower</span> <span class="special">=</span> <span class="special">-</span><span class="number">1</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">mode</span> <span class="special">=</span> <span class="number">0</span><span class="special">)</span> <span class="identifier">RealType</span> <span class="identifier">upper</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// Constructor.
+</span> <span class="special">:</span> <span class="identifier">m_lower</span><span class="special">(</span><span class="identifier">lower</span><span class="special">),</span> <span class="identifier">m_mode</span><span class="special">(</span><span class="identifier">mode</span><span class="special">),</span> <span class="identifier">m_upper</span><span class="special">(</span><span class="identifier">upper</span><span class="special">)</span> <span class="comment">// Default is -1, 0, +1 triangular distribution.
+</span> <span class="comment">// Accessor functions.
+</span> <span class="identifier">RealType</span> <span class="identifier">lower</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">RealType</span> <span class="identifier">mode</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">RealType</span> <span class="identifier">upper</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="special">};</span> <span class="comment">// class triangular_distribution
+</span>
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The <a href="http://en.wikipedia.org/wiki/Triangular_distribution" target="_top">triangular
+ distribution</a> is a continuous
+ <a href="http://en.wikipedia.org/wiki/Probability_distribution" target="_top">probability
+ distribution</a> with a lower limit a, <a href="http://en.wikipedia.org/wiki/Mode_%28statistics%29" target="_top">mode
+ c</a>, and upper limit b.
+ </p>
+<p>
+ The triangular distribution is often used where the distribution is only
+ vaguely known, but, like the <a href="http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29" target="_top">uniform
+ distribution</a>, upper and limits are 'known', but a 'best guess',
+ the mode or center point, is also added. It has been recommended as a
+ <a href="http://www.worldscibooks.com/mathematics/etextbook/5720/5720_chap1.pdf" target="_top">proxy
+ for the beta distribution.</a> The distribution is used in business
+ decision making and project planning.
+ </p>
+<p>
+ The <a href="http://en.wikipedia.org/wiki/Triangular_distribution" target="_top">triangular
+ distribution</a> is a distribution with the <a href="http://en.wikipedia.org/wiki/Probability_density_function" target="_top">probability
+ density function</a>:
+ </p>
+<p>
+ f(x) =
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ 2(x-a)/(b-a) (c-a) for a &lt;= x &lt;= c
+ </li>
+<li>
+ 2(b-x)/(b-a)(b-c) for c &lt; x &lt;= b
+ </li>
+</ul></div>
+<p>
+ Parameter a (lower) can be any finite value. Parameter b (upper) can
+ be any finite value &gt; a (lower). Parameter c (mode) a &lt;= c &lt;=
+ b. This is the most probable value.
+ </p>
+<p>
+ The random variate
+ x must also be finite, and is supported lower &lt;= x &lt;= upper.
+ </p>
+<p>
+ The triangular distribution may be appropriate when an assumption of
+ a normal distribution is unjustified because uncertainty is caused by
+ rounding and quantization from analog to digital conversion. Upper and
+ lower limits are known, and the most probable value lies midway.
+ </p>
+<p>
+ The distribution simplifies when the 'best guess' is either the lower
+ or upper limit - a 90 degree angle triangle. The default chosen is the
+ 001 triangular distribution which expresses an estimate that the lowest
+ value is the most likely; for example, you believe that the next-day
+ quoted delivery date is most likely (knowing that a quicker delivery
+ is impossible - the postman only comes once a day), and that longer delays
+ are decreasingly likely, and delivery is assumed to never take more than
+ your upper limit.
+ </p>
+<p>
+ The following graph illustrates how the <a href="http://en.wikipedia.org/wiki/Probability_density_function" target="_top">probability
+ density function PDF</a> varies with the various parameters:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/triangular_pdf.png" alt="triangular_pdf"></span>
+ </p>
+<p>
+ and cumulative distribution function
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/triangular_cdf.png" alt="triangular_cdf"></span>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.triangular_dist.member_functions"></a><h5>
+<a name="id610788"></a>
+ <a href="triangular_dist.html#math_toolkit.dist.dist_ref.dists.triangular_dist.member_functions">Member
+ Functions</a>
+ </h5>
+<pre class="programlisting">
+<span class="identifier">triangular_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">lower</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">mode</span> <span class="special">=</span> <span class="number">0</span> <span class="identifier">RealType</span> <span class="identifier">upper</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs a <a href="http://en.wikipedia.org/wiki/triangular_distribution" target="_top">triangular
+ distribution</a> with lower <span class="emphasis"><em>lower</em></span> (a) and upper
+ <span class="emphasis"><em>upper</em></span> (b).
+ </p>
+<p>
+ Requires that the <span class="emphasis"><em>lower</em></span>, <span class="emphasis"><em>mode</em></span>
+ and <span class="emphasis"><em>upper</em></span> parameters are all finite, otherwise calls
+ domain_error.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">lower</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the <span class="emphasis"><em>lower</em></span> parameter of this distribution
+ (default -1).
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">mode</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the <span class="emphasis"><em>mode</em></span> parameter of this distribution
+ (default 0).
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">upper</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the <span class="emphasis"><em>upper</em></span> parameter of this distribution
+ (default+1).
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.triangular_dist.non_member_accessors"></a><h5>
+<a name="id611097"></a>
+ <a href="triangular_dist.html#math_toolkit.dist.dist_ref.dists.triangular_dist.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The domain of the random variable is \lowerto \upper, and the supported
+ range is lower &lt;= x &lt;= upper.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.triangular_dist.accuracy"></a><h5>
+<a name="id611271"></a>
+ Accuracy
+ </h5>
+<p>
+ The triangular distribution is implemented with simple arithmetic operators
+ and so should have errors within an epsilon or two, except quantiles
+ with arguments nearing the extremes of zero and unity.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.triangular_dist.implementation"></a><h5>
+<a name="id611303"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table, a is the <span class="emphasis"><em>lower</em></span> parameter
+ of the distribution, c is the <span class="emphasis"><em>mode</em></span> parameter, b
+ is the <span class="emphasis"><em>upper</em></span> parameter, <span class="emphasis"><em>x</em></span> is
+ the random variate, <span class="emphasis"><em>p</em></span> is the probability and <span class="emphasis"><em>q
+ = 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: pdf = 0 for x &lt; mode, 2(x-a)/(b-a)(c-a)
+ else 2*(b-x)/((b-a)(b-c))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: cdf = 0 for x &lt; mode (x-a)<sup>2</sup>/((b-a)(c-a))
+ else 1 - (b-x)<sup>2</sup>/((b-a)(b-c))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: q = 1 - p
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ let p0 = (c-a)/(b-a) the point of inflection on the cdf, then
+ given probability p and q = 1-p:
+ </p>
+ <p>
+ x = sqrt((b-a)(c-a)p) + a ; for p &lt; p0
+ </p>
+ <p>
+ x = c ; for p == p0
+ </p>
+ <p>
+ x = b - sqrt((b-a)(b-c)q) ; for p &gt; p0
+ </p>
+ <p>
+ (See /boost/math/distributions/triangular.hpp
+ for details.)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ As quantile (See /boost/math/distributions/triangular.hpp
+ for details.)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ (a + b + 3) / 3
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ variance
+ </p>
+ </td>
+<td>
+ <p>
+ (a<sup>2</sup>+b<sup>2</sup>+c<sup>2</sup> - ab - ac - bc)/18
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ c
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ (See /boost/math/distributions/triangular.hpp
+ for details).
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ 12/5
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ -3/5
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<p>
+ Some 'known good' test values were obtained from <a href="http://espse.ed.psu.edu/edpsych/faculty/rhale/hale/507Mat/statlets/free/pdist.htm" target="_top">Statlet:
+ Calculate and plot probability distributions</a>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.triangular_dist.references"></a><h5>
+<a name="id611693"></a>
+ References
+ </h5>
+<div class="itemizedlist"><ul type="disc">
+<li><a href="http://en.wikipedia.org/wiki/Triangular_distribution" target="_top">Wikpedia
+ triangular distribution</a></li>
+<li><a href="http://mathworld.wolfram.com/TriangularDistribution.html" target="_top">Weisstein,
+ Eric W. "Triangular Distribution." From MathWorld--A Wolfram
+ Web Resource.</a></li>
+<li>
+ Evans, M.; Hastings, N.; and Peacock, B. "Triangular Distribution."
+ Ch. 40 in Statistical Distributions, 3rd ed. New York: Wiley, pp. 187-188,
+ 2000, ISBN - 0471371246]
+ </li>
+<li><a href="http://www.brighton-webs.co.uk/distributions/triangular.asp" target="_top">Brighton
+ Webs Ltd. BW D-Calc 1.0 Distribution Calculator</a></li>
+<li><a href="http://www.worldscibooks.com/mathematics/etextbook/5720/5720_chap1.pdf" target="_top">The
+ Triangular Distribution including its history.</a></li>
+<li><a href="../../../../www.measurement.sk/2002/S1/Wimmer2.pdf" target="_top">Gejza Wimmer, Viktor
+ Witkovsky and Tomas Duby, Measurement Science Review, Volume 2, Section
+ 1, 2002, Proper Rounding Of The Measurement Results Under The Assumption
+ Of Triangular Distribution.</a></li>
+</ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="students_t_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="weibull.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/uniform_dist.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/uniform_dist.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,367 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Uniform Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="weibull.html" title="Weibull Distribution">
+<link rel="next" href="../dist_algorithms.html" title="Distribution Algorithms">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="weibull.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../dist_algorithms.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.uniform_dist"></a><a href="uniform_dist.html" title="Uniform Distribution"> Uniform
+ Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">uniform</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+ <span class="keyword">class</span> <span class="identifier">uniform_distribution</span><span class="special">;</span>
+
+ <span class="keyword">typedef</span> <span class="identifier">uniform_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">uniform</span><span class="special">;</span>
+
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+ <span class="keyword">class</span> <span class="identifier">uniform_distribution</span>
+ <span class="special">{</span>
+ <span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+
+ <span class="identifier">uniform_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">lower</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">upper</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// Constructor.
+</span> <span class="special">:</span> <span class="identifier">m_lower</span><span class="special">(</span><span class="identifier">lower</span><span class="special">),</span> <span class="identifier">m_upper</span><span class="special">(</span><span class="identifier">upper</span><span class="special">)</span> <span class="comment">// Default is standard uniform distribution.
+</span> <span class="comment">// Accessor functions.
+</span> <span class="identifier">RealType</span> <span class="identifier">lower</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">RealType</span> <span class="identifier">upper</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="special">};</span> <span class="comment">// class uniform_distribution
+</span>
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The uniform distribution, also known as a rectangular distribution, is
+ a probability distribution that has constant probability.
+ </p>
+<p>
+ The <a href="http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29" target="_top">continuous
+ uniform distribution</a> is a distribution with the <a href="http://en.wikipedia.org/wiki/Probability_density_function" target="_top">probability
+ density function</a>:
+ </p>
+<p>
+ f(x) =
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ 1 / (upper - lower) for lower &lt; x &lt; upper
+ </li>
+<li>
+ zero for x &lt; lower or x &gt; upper
+ </li>
+</ul></div>
+<p>
+ and in this implementation:
+ </p>
+<div class="itemizedlist"><ul type="disc"><li>
+ 1 / (upper - lower) for x = lower or x = upper
+ </li></ul></div>
+<p>
+ The choice of x = lower or x = upper is made because statistical use
+ of this distribution judged is most likely: the method of maximum likelihood
+ uses this definition.
+ </p>
+<p>
+ There is also a discrete uniform distribution.
+ </p>
+<p>
+ Parameters lower and upper can be any finite value.
+ </p>
+<p>
+ The random variate
+ x must also be finite, and is supported lower &lt;= x &lt;= upper.
+ </p>
+<p>
+ The lower parameter is also called the <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm" target="_top">location
+ parameter</a>, <a href="http://en.wikipedia.org/wiki/Location_parameter" target="_top">that
+ is where the origin of a plot will lie</a>, and (upper - lower) is
+ also called the <a href="http://en.wikipedia.org/wiki/Scale_parameter" target="_top">scale
+ parameter</a>.
+ </p>
+<p>
+ The following graph illustrates how the <a href="http://en.wikipedia.org/wiki/Probability_density_function" target="_top">probability
+ density function PDF</a> varies with the shape parameter:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/uniform_pdf.png" alt="uniform_pdf"></span>
+ </p>
+<p>
+ Likewise for the CDF:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/uniform_cdf.png" alt="uniform_cdf"></span>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.uniform_dist.member_functions"></a><h5>
+<a name="id614192"></a>
+ <a href="uniform_dist.html#math_toolkit.dist.dist_ref.dists.uniform_dist.member_functions">Member
+ Functions</a>
+ </h5>
+<pre class="programlisting">
+<span class="identifier">uniform_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">lower</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">upper</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs a <a href="http://en.wikipedia.org/wiki/uniform_distribution" target="_top">uniform
+ distribution</a> with lower <span class="emphasis"><em>lower</em></span> (a) and upper
+ <span class="emphasis"><em>upper</em></span> (b).
+ </p>
+<p>
+ Requires that the <span class="emphasis"><em>lower</em></span> and <span class="emphasis"><em>upper</em></span>
+ parameters are both finite; otherwise if infinity or NaN then calls
+ domain_error.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">lower</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the <span class="emphasis"><em>lower</em></span> parameter of this distribution.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">upper</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the <span class="emphasis"><em>upper</em></span> parameter of this distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.uniform_dist.non_member_accessors"></a><h5>
+<a name="id614428"></a>
+ <a href="uniform_dist.html#math_toolkit.dist.dist_ref.dists.uniform_dist.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The domain of the random variable is any finite value, but the supported
+ range is only <span class="emphasis"><em>lower</em></span> &lt;= x &lt;= <span class="emphasis"><em>upper</em></span>.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.uniform_dist.accuracy"></a><h5>
+<a name="id614606"></a>
+ Accuracy
+ </h5>
+<p>
+ The uniform distribution is implemented with simple arithmetic operators
+ and so should have errors within an epsilon or two.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.uniform_dist.implementation"></a><h5>
+<a name="id614637"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table a is the <span class="emphasis"><em>lower</em></span> parameter
+ of the distribution, b is the <span class="emphasis"><em>upper</em></span> parameter,
+ <span class="emphasis"><em>x</em></span> is the random variate, <span class="emphasis"><em>p</em></span>
+ is the probability and <span class="emphasis"><em>q = 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: pdf = 0 for x &lt; a, 1 / (b - a) for a &lt;=
+ x &lt;= b, 0 for x &gt; b
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: cdf = 0 for x &lt; a, (x - a) / (b - a) for
+ a &lt;= x &lt;= b, 1 for x &gt; b
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: q = 1 - p, (b - x) / (b - a)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = p * (b - a) + a;
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ x = -q * (b - a) + b
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ (a + b) / 2
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ variance
+ </p>
+ </td>
+<td>
+ <p>
+ (b - a) <sup>2</sup> / 12
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ any value in [a, b] but a is chosen. (Would NaN be better?)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ 0
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ -6/5 = -1.2 exactly. (kurtosis - 3)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ 9/5
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.dist.dist_ref.dists.uniform_dist.references"></a><h5>
+<a name="id614945"></a>
+ References
+ </h5>
+<div class="itemizedlist"><ul type="disc">
+<li><a href="http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29" target="_top">Wikpedia
+ continuous uniform distribution</a></li>
+<li><a href="http://mathworld.wolfram.com/UniformDistribution.html" target="_top">Weisstein,
+ Weisstein, Eric W. "Uniform Distribution." From MathWorld--A
+ Wolfram Web Resource.</a></li>
+<li>http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm</li>
+</ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="weibull.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../dist_algorithms.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/weibull.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/dists/weibull.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,365 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Weibull Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dists.html" title="Distributions">
+<link rel="prev" href="triangular_dist.html" title="Triangular Distribution">
+<link rel="next" href="uniform_dist.html" title="Uniform Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="triangular_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="uniform_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.dist_ref.dists.weibull"></a><a href="weibull.html" title="Weibull Distribution"> Weibull
+ Distribution</a>
+</h5></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">weibull</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
+ <span class="keyword">class</span> Policy <span class="special">=</span> policies::policy<> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">weibull_distribution</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">weibull_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">weibull</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">weibull_distribution</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span>
+ <span class="comment">// Construct:
+</span> <span class="identifier">weibull_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">shape</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">1</span><span class="special">)</span>
+ <span class="comment">// Accessors:
+</span> <span class="identifier">RealType</span> <span class="identifier">shape</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+<span class="special">};</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The <a href="http://en.wikipedia.org/wiki/Weibull_distribution" target="_top">Weibull
+ distribution</a> is a continuous distribution with the <a href="http://en.wikipedia.org/wiki/Probability_density_function" target="_top">probability
+ density function</a>:
+ </p>
+<p>
+ f(x; &#945;, &#946;) = (&#945;/&#946;) * (x / &#946;)<sup>&#945; - 1</sup> * e<sup>-(x/&#946;)<sup>&#945;</sup></sup>
+ </p>
+<p>
+ For shape parameter &#945; &gt; 0, and scale parameter &#946; &gt; 0, and x &gt; 0.
+ </p>
+<p>
+ The Weibull distribution is often used in the field of failure analysis;
+ in particular it can mimic distributions where the failure rate varies
+ over time. If the failure rate is:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ constant over time, then &#945; = 1, suggests that items are failing from
+ random events.
+ </li>
+<li>
+ decreases over time, then &#945; &lt; 1, suggesting "infant mortality".
+ </li>
+<li>
+ increases over time, then &#945; &gt; 1, suggesting "wear out" -
+ more likely to fail as time goes by.
+ </li>
+</ul></div>
+<p>
+ The following graph illustrates how the PDF varies with the shape parameter
+ &#945;:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/weibull.png" alt="weibull"></span>
+ </p>
+<p>
+ While this graph illustrates how the PDF varies with the scale parameter
+ &#946;:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../graphs/weibull2.png" alt="weibull2"></span>
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.weibull.related_distributions"></a><h5>
+<a name="id612455"></a>
+ <a href="weibull.html#math_toolkit.dist.dist_ref.dists.weibull.related_distributions">Related
+ distributions</a>
+ </h5>
+<p>
+ When &#945; = 3, the <a href="http://en.wikipedia.org/wiki/Weibull_distribution" target="_top">Weibull
+ distribution</a> appears similar to the <a href="http://en.wikipedia.org/wiki/Normal_distribution" target="_top">normal
+ distribution</a>. When &#945; = 1, the Weibull distribution reduces to the
+ <a href="http://en.wikipedia.org/wiki/Exponential_distribution" target="_top">exponential
+ distribution</a>.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.weibull.member_functions"></a><h5>
+<a name="id612511"></a>
+ <a href="weibull.html#math_toolkit.dist.dist_ref.dists.weibull.member_functions">Member
+ Functions</a>
+ </h5>
+<pre class="programlisting">
+<span class="identifier">weibull_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">shape</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+</pre>
+<p>
+ Constructs a <a href="http://en.wikipedia.org/wiki/Weibull_distribution" target="_top">Weibull
+ distribution</a> with shape <span class="emphasis"><em>shape</em></span> and scale
+ <span class="emphasis"><em>scale</em></span>.
+ </p>
+<p>
+ Requires that the <span class="emphasis"><em>shape</em></span> and <span class="emphasis"><em>scale</em></span>
+ parameters are both greater than zero, otherwise calls domain_error.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">shape</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the <span class="emphasis"><em>shape</em></span> parameter of this distribution.
+ </p>
+<pre class="programlisting">
+<span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+</pre>
+<p>
+ Returns the <span class="emphasis"><em>scale</em></span> parameter of this distribution.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.weibull.non_member_accessors"></a><h5>
+<a name="id612733"></a>
+ <a href="weibull.html#math_toolkit.dist.dist_ref.dists.weibull.non_member_accessors">Non-member
+ Accessors</a>
+ </h5>
+<p>
+ All the <a href="../nmp.html" title="Non-Member Properties">usual non-member
+ accessor functions</a> that are generic to all distributions are supported:
+ Cumulative Distribution Function,
+ Probability Density Function, Quantile, <a href="../nmp.html#math.dist.hazard">Hazard
+ Function</a>, Cumulative Hazard Function,
+ mean, median,
+ mode, variance,
+ standard deviation, skewness,
+ kurtosis, kurtosis_excess,
+ range and support.
+ </p>
+<p>
+ The domain of the random variable is [0, &#8734;].
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.weibull.accuracy"></a><h5>
+<a name="id612905"></a>
+ Accuracy
+ </h5>
+<p>
+ The Weibull distribution is implemented in terms of the standard library
+ <code class="computeroutput"><span class="identifier">log</span></code> and <code class="computeroutput"><span class="identifier">exp</span></code> functions plus expm1
+ and log1p and
+ as such should have very low error rates.
+ </p>
+<a name="math_toolkit.dist.dist_ref.dists.weibull.implementation"></a><h5>
+<a name="id612977"></a>
+ Implementation
+ </h5>
+<p>
+ In the following table &#945; is the shape parameter of the distribution, &#946; is
+ it's scale parameter, <span class="emphasis"><em>x</em></span> is the random variate,
+ <span class="emphasis"><em>p</em></span> is the probability and <span class="emphasis"><em>q = 1-p</em></span>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Implementation Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ pdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: pdf = &#945;&#946;<sup>-&#945; </sup>x<sup>&#945; - 1</sup> e<sup>-(x/beta)<sup>alpha</sup></sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: p = -expm1(-(x/&#946;)<sup>&#945;</sup>)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: q = e<sup>-(x/&#946;)<sup>&#945;</sup></sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = &#946; * (-log1p(-p))<sup>1/&#945;</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile from the complement
+ </p>
+ </td>
+<td>
+ <p>
+ Using the relation: x = &#946; * (-log(q))<sup>1/&#945;</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean
+ </p>
+ </td>
+<td>
+ <p>
+ &#946; * &#915;(1 + 1/&#945;)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ variance
+ </p>
+ </td>
+<td>
+ <p>
+ &#946;<sup>2</sup>(&#915;(1 + 2/&#945;) - &#915;<sup>2</sup>(1 + 1/&#945;))
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode
+ </p>
+ </td>
+<td>
+ <p>
+ &#946;((&#945; - 1) / &#945;)<sup>1/&#945;</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness
+ </p>
+ </td>
+<td>
+ <p>
+ Refer to <a href="http://mathworld.wolfram.com/WeibullDistribution.html" target="_top">Weisstein,
+ Eric W. "Weibull Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis
+ </p>
+ </td>
+<td>
+ <p>
+ Refer to <a href="http://mathworld.wolfram.com/WeibullDistribution.html" target="_top">Weisstein,
+ Eric W. "Weibull Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis excess
+ </p>
+ </td>
+<td>
+ <p>
+ Refer to <a href="http://mathworld.wolfram.com/WeibullDistribution.html" target="_top">Weisstein,
+ Eric W. "Weibull Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.dist.dist_ref.dists.weibull.references"></a><h5>
+<a name="id613363"></a>
+ References
+ </h5>
+<div class="itemizedlist"><ul type="disc">
+<li>http://en.wikipedia.org/wiki/Weibull_distribution</li>
+<li><a href="http://mathworld.wolfram.com/WeibullDistribution.html" target="_top">Weisstein,
+ Eric W. "Weibull Distribution." From MathWorld--A Wolfram
+ Web Resource.</a></li>
+<li><a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3668.htm" target="_top">Weibull
+ in NIST Exploratory Data Analysis</a></li>
+</ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="triangular_dist.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="uniform_dist.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/nmp.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/dist_ref/nmp.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,699 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Non-Member Properties</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../dist_ref.html" title="Statistical Distributions Reference">
+<link rel="prev" href="../dist_ref.html" title="Statistical Distributions Reference">
+<link rel="next" href="dists.html" title="Distributions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../dist_ref.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dist_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="dists.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.dist.dist_ref.nmp"></a> Non-Member Properties
+</h4></div></div></div>
+<p>
+ Properties that are common to all distributions are accessed via non-member
+ getter functions. This allows more of these functions to be added over
+ time as the need arises. Unfortunately the literature uses many different
+ and confusing names to refer to a rather small number of actual concepts;
+ refer to the concept index to find
+ the property you want by the name you are most familiar with. Or use the
+ function index to go straight to
+ the function you want if you already know its name.
+ </p>
+<a name="function_index"></a><a name="math_toolkit.dist.dist_ref.nmp.function_index"></a><h5>
+<a name="id570747"></a>
+ <a href="nmp.html#math_toolkit.dist.dist_ref.nmp.function_index">Function
+ Index</a>
+ </h5>
+<div class="itemizedlist"><ul type="disc">
+<li>
+cdf.
+ </li>
+<li>
+cdf complement.
+ </li>
+<li>
+chf.
+ </li>
+<li>
+hazard.
+ </li>
+<li>
+kurtosis.
+ </li>
+<li>kurtosis_excess</li>
+<li>
+mean.
+ </li>
+<li>
+median.
+ </li>
+<li>
+mode.
+ </li>
+<li>
+pdf.
+ </li>
+<li>
+range.
+ </li>
+<li>
+quantile.
+ </li>
+<li>
+quantile from the complement.
+ </li>
+<li>
+skewness.
+ </li>
+<li>
+standard_deviation.
+ </li>
+<li>
+support.
+ </li>
+<li>
+variance.
+ </li>
+</ul></div>
+<a name="concept_index"></a><a name="math_toolkit.dist.dist_ref.nmp.conceptual_index"></a><h5>
+<a name="id571003"></a>
+ <a href="nmp.html#math_toolkit.dist.dist_ref.nmp.conceptual_index">Conceptual
+ Index</a>
+ </h5>
+<div class="itemizedlist"><ul type="disc">
+<li>
+<a href="nmp.html#math.dist.ccdf">Complement of the Cumulative Distribution
+ Function</a>.
+ </li>
+<li>
+Cumulative Distribution Function.
+ </li>
+<li>
+Cumulative Hazard Function.
+ </li>
+<li>
+Inverse Cumulative Distribution Function.
+ </li>
+<li>
+Inverse Survival Function.
+ </li>
+<li>Hazard Function</li>
+<li>
+Lower Critical Value.
+ </li>
+<li>
+kurtosis.
+ </li>
+<li>kurtosis_excess</li>
+<li>
+mean.
+ </li>
+<li>
+median.
+ </li>
+<li>
+mode.
+ </li>
+<li>
+P.
+ </li>
+<li>
+Percent Point Function.
+ </li>
+<li>
+Probability Density Function.
+ </li>
+<li>
+Probability Mass Function.
+ </li>
+<li>
+range.
+ </li>
+<li>
+Q.
+ </li>
+<li>
+Quantile.
+ </li>
+<li>
+<a href="nmp.html#math.dist.quantile_c">Quantile from the complement of
+ the probability</a>.
+ </li>
+<li>
+skewness.
+ </li>
+<li>standard deviation</li>
+<li>
+Survival Function.
+ </li>
+<li>
+support.
+ </li>
+<li>
+Upper Critical Value.
+ </li>
+<li>
+variance.
+ </li>
+</ul></div>
+<a name="math.dist.cdf"></a><a name="math_toolkit.dist.dist_ref.nmp.cumulative_distribution_function"></a><h5>
+<a name="id571359"></a>
+ <a href="nmp.html#math_toolkit.dist.dist_ref.nmp.cumulative_distribution_function">Cumulative
+ Distribution Function</a>
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">cdf</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Distribution-Type</em></span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">RealType</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">);</span>
+</pre>
+<p>
+ The Cumulative Distribution Function
+ is the probability that the variable takes a value less than or equal to
+ x. It is equivalent to the integral from -infinity to x of the <a href="nmp.html#math.dist.pdf">Probability
+ Density Function</a>.
+ </p>
+<p>
+ This function may return a domain_error
+ if the random variable is outside the defined range for the distribution.
+ </p>
+<p>
+ For example the following graph shows the cdf for the normal distribution:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/cdf.png" alt="cdf"></span>
+ </p>
+<a name="math.dist.ccdf"></a><a name="math_toolkit.dist.dist_ref.nmp.complement_of_the_cumulative_distribution_function"></a><h5>
+<a name="id571606"></a>
+ <a href="nmp.html#math_toolkit.dist.dist_ref.nmp.complement_of_the_cumulative_distribution_function">Complement
+ of the Cumulative Distribution Function</a>
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Distribution</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">cdf</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Unspecified-Complement-Type</em></span><span class="special">&lt;</span><span class="identifier">Distribution</span><span class="special">,</span> <span class="identifier">RealType</span><span class="special">&gt;&amp;</span> <span class="identifier">comp</span><span class="special">);</span>
+</pre>
+<p>
+ The complement of the <a href="nmp.html#math.dist.cdf">Cumulative Distribution
+ Function</a> is the probability that the variable takes a value greater
+ than x. It is equivalent to the integral from x to infinity of the Probability Density Function, or 1 minus
+ the Cumulative Distribution Function
+ of x.
+ </p>
+<p>
+ This is also known as the survival function.
+ </p>
+<p>
+ This function may return a domain_error
+ if the random variable is outside the defined range for the distribution.
+ </p>
+<p>
+ In this library, it is obtained by wrapping the arguments to the <code class="computeroutput"><span class="identifier">cdf</span></code> function in a call to <code class="computeroutput"><span class="identifier">complement</span></code>, for example:
+ </p>
+<pre class="programlisting">
+<span class="comment">// standard normal distribution object:
+</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">normal</span> <span class="identifier">norm</span><span class="special">;</span>
+<span class="comment">// print survival function for x=2.0:
+</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">norm</span><span class="special">,</span> <span class="number">2.0</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+</pre>
+<p>
+ For example the following graph shows the __complement of the cdf for the
+ normal distribution:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/survival.png" alt="survival"></span>
+ </p>
+<p>
+ See why complements? for why the
+ complement is useful and when it should be used.
+ </p>
+<a name="math.dist.hazard"></a><a name="math_toolkit.dist.dist_ref.nmp.hazard_function"></a><h5>
+<a name="id572026"></a>
+ Hazard Function
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">hazard</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Distribution-Type</em></span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">RealType</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the Hazard Function of
+ <span class="emphasis"><em>x</em></span> and distibution <span class="emphasis"><em>dist</em></span>.
+ </p>
+<p>
+ This function may return a domain_error
+ if the random variable is outside the defined range for the distribution.
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/hazard.png"></span>
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ Some authors refer to this as the conditional failure density function
+ rather than the hazard function.
+ </p></td></tr>
+</table></div>
+<a name="math.dist.chf"></a><a name="math_toolkit.dist.dist_ref.nmp.cumulative_hazard_function"></a><h5>
+<a name="id572279"></a>
+ <a href="nmp.html#math_toolkit.dist.dist_ref.nmp.cumulative_hazard_function">Cumulative
+ Hazard Function</a>
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">chf</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Distribution-Type</em></span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">RealType</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the Cumulative Hazard Function
+ of <span class="emphasis"><em>x</em></span> and distibution <span class="emphasis"><em>dist</em></span>.
+ </p>
+<p>
+ This function may return a domain_error
+ if the random variable is outside the defined range for the distribution.
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/chf.png"></span>
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ Some authors refer to this as simply the "Hazard Function".
+ </p></td></tr>
+</table></div>
+<a name="math.dist.mean"></a><a name="math_toolkit.dist.dist_ref.nmp.mean"></a><h5>
+<a name="id572535"></a>
+ mean
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">mean</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Distribution-Type</em></span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the mean of the distribution <span class="emphasis"><em>dist</em></span>.
+ </p>
+<p>
+ This function may return a domain_error
+ if the distribution does not have a defined mean (for example the Cauchy
+ distribution).
+ </p>
+<a name="math.dist.median"></a><a name="math_toolkit.dist.dist_ref.nmp.median"></a><h5>
+<a name="id572708"></a>
+ median
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">median</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Distribution-Type</em></span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the median of the distribution <span class="emphasis"><em>dist</em></span>.
+ </p>
+<a name="math.dist.mode"></a><a name="math_toolkit.dist.dist_ref.nmp.mode"></a><h5>
+<a name="id572867"></a>
+ mode
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">mode</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Distribution-Type</em></span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the mode of the distribution <span class="emphasis"><em>dist</em></span>.
+ </p>
+<p>
+ This function may return a domain_error
+ if the distribution does not have a defined mode.
+ </p>
+<a name="math.dist.pdf"></a><a name="math_toolkit.dist.dist_ref.nmp.probability_density_function"></a><h5>
+<a name="id573033"></a>
+ <a href="nmp.html#math_toolkit.dist.dist_ref.nmp.probability_density_function">Probability
+ Density Function</a>
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">pdf</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Distribution-Type</em></span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">RealType</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">);</span>
+</pre>
+<p>
+ For a continuous function, the probability density function (pdf) returns
+ the probability that the variate has the value x. Since for continuous
+ distributions the probability at a single point is actually zero, the probability
+ is better expressed as the integral of the pdf between two points: see
+ the Cumulative Distribution Function.
+ </p>
+<p>
+ For a discrete distribution, the pdf is the probability that the variate
+ takes the value x.
+ </p>
+<p>
+ This function may return a domain_error
+ if the random variable is outside the defined range for the distribution.
+ </p>
+<p>
+ For example for a standard normal distribution the pdf looks like this:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/pdf.png" alt="pdf"></span>
+ </p>
+<a name="math.dist.range"></a><a name="math_toolkit.dist.dist_ref.nmp.range"></a><h5>
+<a name="id573278"></a>
+ range
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> <span class="identifier">RealType</span><span class="special">&gt;</span> <span class="identifier">range</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Distribution-Type</em></span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the valid range of the random variable over distribution <span class="emphasis"><em>dist</em></span>.
+ </p>
+<a name="math.dist.quantile"></a><a name="math_toolkit.dist.dist_ref.nmp.quantile"></a><h5>
+<a name="id573474"></a>
+ Quantile
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">quantile</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Distribution-Type</em></span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">RealType</span><span class="special">&amp;</span> <span class="identifier">p</span><span class="special">);</span>
+</pre>
+<p>
+ The quantile is best viewed as the inverse of the <a href="nmp.html#math.dist.cdf">Cumulative
+ Distribution Function</a>, it returns a value <span class="emphasis"><em>x</em></span>
+ such that <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">==</span>
+ <span class="identifier">p</span></code>.
+ </p>
+<p>
+ This is also known as the <span class="emphasis"><em>percent point function</em></span>,
+ or a <span class="emphasis"><em>percentile</em></span>, it is also the same as calculating
+ the <span class="emphasis"><em>lower critical value</em></span> of a distribution.
+ </p>
+<p>
+ This function returns a domain_error
+ if the probability lies outside [0,1]. The function may return an overflow_error if there is no finite value
+ that has the specified probability.
+ </p>
+<p>
+ The following graph shows the quantile function for a standard normal distribution:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/quantile.png" alt="quantile"></span>
+ </p>
+<a name="math.dist.quantile_c"></a><a name="math_toolkit.dist.dist_ref.nmp.quantile_from_the_complement_of_the_probability_"></a><h5>
+<a name="id573792"></a>
+ <a href="nmp.html#math_toolkit.dist.dist_ref.nmp.quantile_from_the_complement_of_the_probability_">Quantile
+ from the complement of the probability.</a>
+ </h5>
+<p>
+ complements
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Distribution</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">quantile</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Unspecified-Complement-Type</em></span><span class="special">&lt;</span><span class="identifier">Distribution</span><span class="special">,</span> <span class="identifier">RealType</span><span class="special">&gt;&amp;</span> <span class="identifier">comp</span><span class="special">);</span>
+</pre>
+<p>
+ This is the inverse of the <a href="nmp.html#math.dist.ccdf">Complement of
+ the Cumulative Distribution Function</a>. It is calculated by wrapping
+ the arguments in a call to the quantile function in a call to <span class="emphasis"><em>complement</em></span>.
+ For example:
+ </p>
+<pre class="programlisting">
+<span class="comment">// define a standard normal distribution:
+</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">normal</span> <span class="identifier">norm</span><span class="special">;</span>
+<span class="comment">// print the value of x for which the complement
+</span><span class="comment">// of the probability is 0.05:
+</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">norm</span><span class="special">,</span> <span class="number">0.05</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+</pre>
+<p>
+ The function computes a value <span class="emphasis"><em>x</em></span> such that <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">x</span><span class="special">))</span> <span class="special">==</span> <span class="identifier">q</span></code>
+ where <span class="emphasis"><em>q</em></span> is complement of the probability.
+ </p>
+<p>
+ Why complements?
+ </p>
+<p>
+ This function is also called the inverse survival function, and is the
+ same as calculating the <span class="emphasis"><em>upper critical value</em></span> of a
+ distribution.
+ </p>
+<p>
+ This function returns a domain_error
+ if the probablity lies outside [0,1]. The function may return an overflow_error if there is no finite value
+ that has the specified probability.
+ </p>
+<p>
+ The following graph show the inverse survival function for the normal distribution:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/survival_inv.png" alt="survival_inv"></span>
+ </p>
+<a name="math.dist.sd"></a><a name="math_toolkit.dist.dist_ref.nmp.standard_deviation"></a><h5>
+<a name="id574273"></a>
+ <a href="nmp.html#math_toolkit.dist.dist_ref.nmp.standard_deviation">Standard
+ Deviation</a>
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">standard_deviation</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Distribution-Type</em></span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the standard deviation of distribution <span class="emphasis"><em>dist</em></span>.
+ </p>
+<p>
+ This function may return a domain_error
+ if the distribution does not have a defined standard deviation.
+ </p>
+<a name="math.dist.support"></a><a name="math_toolkit.dist.dist_ref.nmp.support"></a><h5>
+<a name="id574450"></a>
+ support
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> <span class="identifier">RealType</span><span class="special">&gt;</span> <span class="identifier">support</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Distribution-Type</em></span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the supported range of random variable over the distribution <span class="emphasis"><em>dist</em></span>.
+ </p>
+<p>
+ The distribution is said to be 'supported' over a range that is <a href="http://en.wikipedia.org/wiki/Probability_distribution" target="_top">"the smallest
+ closed set whose complement has probability zero"</a>. Non-mathematicians
+ might say it means the 'interesting' smallest range of random variate x
+ that has the cdf going from zero to unity. Outside are uninteresting zones
+ where the pdf is zero, and the cdf zero or unity.
+ </p>
+<a name="math.dist.variance"></a><a name="math_toolkit.dist.dist_ref.nmp.variance"></a><h5>
+<a name="id574663"></a>
+ Variance
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">variance</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Distribution-Type</em></span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the variance of the distribution <span class="emphasis"><em>dist</em></span>.
+ </p>
+<p>
+ This function may return a domain_error
+ if the distribution does not have a defined variance.
+ </p>
+<a name="math.dist.skewness"></a><a name="math_toolkit.dist.dist_ref.nmp.skewness"></a><h5>
+<a name="id574838"></a>
+ Skewness
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">skewness</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Distribution-Type</em></span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the skewness of the distribution <span class="emphasis"><em>dist</em></span>.
+ </p>
+<p>
+ This function may return a domain_error
+ if the distribution does not have a defined skewness.
+ </p>
+<a name="math.dist.kurtosis"></a><a name="math_toolkit.dist.dist_ref.nmp.kurtosis"></a><h5>
+<a name="id575013"></a>
+ Kurtosis
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">kurtosis</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Distribution-Type</em></span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the 'proper' kurtosis (normalized fourth moment) of the distribution
+ <span class="emphasis"><em>dist</em></span>.
+ </p>
+<p>
+ kertosis = &#946;<sub>2</sub>= &#956;<sub>4</sub> / &#956;<sub>2</sub><sup>2</sup>
+ </p>
+<p>
+ Where &#956;<sub>i</sub> is the i'th central moment of the distribution, and in particular
+ &#956;<sub>2</sub> is the variance of the distribution.
+ </p>
+<p>
+ The kurtosis is a measure of the "peakedness" of a distribution.
+ </p>
+<p>
+ Note that the literature definition of kurtosis is confusing. The definition
+ used here is that used by for example <a href="http://mathworld.wolfram.com/Kurtosis.html" target="_top">Wolfram
+ MathWorld</a> (that includes a table of formulae for kurtosis excess
+ for various distributions) but NOT the definition of <a href="http://en.wikipedia.org/wiki/Kurtosis" target="_top">kurtosis
+ used by Wikipedia</a> which treats "kurtosis" and "kurtosis
+ excess" as the same quantity.
+ </p>
+<pre class="programlisting">
+<span class="identifier">kurtosis_excess</span> <span class="special">=</span> <span class="char">'proper'</span> <span class="identifier">kurtosis</span> <span class="special">-</span> <span class="number">3</span>
+</pre>
+<p>
+ This subtraction of 3 is convenient so that the <span class="emphasis"><em>kurtosis excess</em></span>
+ of a normal distribution is zero.
+ </p>
+<p>
+ This function may return a domain_error
+ if the distribution does not have a defined kurtosis.
+ </p>
+<p>
+ 'Proper' kurtosis can have a value from zero to + infinity.
+ </p>
+<a name="math.dist.kurtosis_excess"></a><a name="math_toolkit.dist.dist_ref.nmp.kurtosis_excess"></a><h5>
+<a name="id575313"></a>
+ <a href="nmp.html#math_toolkit.dist.dist_ref.nmp.kurtosis_excess">Kurtosis
+ excess</a>
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">kurtosis_excess</span><span class="special">(</span><span class="keyword">const</span> <span class="emphasis"><em>Distribution-Type</em></span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">,</span> Policy<span class="special">&gt;&amp;</span> <span class="identifier">dist</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the kurtosis excess of the distribution <span class="emphasis"><em>dist</em></span>.
+ </p>
+<p>
+ kurtosis excess = &#947;<sub>2</sub>= &#956;<sub>4</sub> / &#956;<sub>2</sub><sup>2</sup>- 3 = kurtosis - 3
+ </p>
+<p>
+ Where &#956;<sub>i</sub> is the i'th central moment of the distribution, and in particular
+ &#956;<sub>2</sub> is the variance of the distribution.
+ </p>
+<p>
+ The kurtosis excess is a measure of the "peakedness" of a distribution,
+ and is more widely used than the "kurtosis proper". It is defined
+ so that the kurtosis excess of a normal distribution is zero.
+ </p>
+<p>
+ This function may return a domain_error
+ if the distribution does not have a defined kurtosis excess.
+ </p>
+<p>
+ Kurtosis excess can have a value from -2 to + infinity.
+ </p>
+<pre class="programlisting">
+<span class="identifier">kurtosis</span> <span class="special">=</span> <span class="identifier">kurtosis_excess</span> <span class="special">+</span><span class="number">3</span><span class="special">;</span>
+</pre>
+<p>
+ The kurtosis excess of a normal distribution is zero.
+ </p>
+<a name="cdfPQ"></a><a name="math_toolkit.dist.dist_ref.nmp.p_and_q"></a><h5>
+<a name="id575576"></a>
+ P and Q
+ </h5>
+<p>
+ The terms P and Q are sometimes used to refer to the <a href="nmp.html#math.dist.cdf">Cumulative
+ Distribution Function</a> and its complement
+ respectively. Lowercase p and q are sometimes used to refer to the values
+ returned by these functions.
+ </p>
+<a name="percent"></a><a name="math_toolkit.dist.dist_ref.nmp.percent_point_function"></a><h5>
+<a name="id575631"></a>
+ <a href="nmp.html#math_toolkit.dist.dist_ref.nmp.percent_point_function">Percent
+ Point Function</a>
+ </h5>
+<p>
+ The percent point function, also known as the percentile, is the same as
+ the Quantile.
+ </p>
+<a name="cdf_inv"></a><a name="math_toolkit.dist.dist_ref.nmp.inverse_cdf_function_"></a><h5>
+<a name="id575675"></a>
+ <a href="nmp.html#math_toolkit.dist.dist_ref.nmp.inverse_cdf_function_">Inverse
+ CDF Function.</a>
+ </h5>
+<p>
+ The inverse of the cumulative distribution function, is the same as the
+ Quantile.
+ </p>
+<a name="survival_inv"></a><a name="math_toolkit.dist.dist_ref.nmp.inverse_survival_function_"></a><h5>
+<a name="id575719"></a>
+ <a href="nmp.html#math_toolkit.dist.dist_ref.nmp.inverse_survival_function_">Inverse
+ Survival Function.</a>
+ </h5>
+<p>
+ The inverse of the survival function, is the same as computing the quantile from the complement of the probability.
+ </p>
+<a name="pmf"></a><a name="math_toolkit.dist.dist_ref.nmp.probability_mass_function"></a><h5>
+<a name="id575765"></a>
+ <a href="nmp.html#math_toolkit.dist.dist_ref.nmp.probability_mass_function">Probability
+ Mass Function</a>
+ </h5>
+<p>
+ The Probability Mass Function is the same as the <a href="nmp.html#math.dist.pdf">Probability
+ Density Function</a>.
+ </p>
+<p>
+ The term Mass Function is usually applied to discrete distributions, while
+ the term Probability Density Function
+ applies to continuous distributions.
+ </p>
+<a name="lower_critical"></a><a name="math_toolkit.dist.dist_ref.nmp.lower_critical_value_"></a><h5>
+<a name="id575825"></a>
+ <a href="nmp.html#math_toolkit.dist.dist_ref.nmp.lower_critical_value_">Lower
+ Critical Value.</a>
+ </h5>
+<p>
+ The lower critical value calculates the value of the random variable given
+ the area under the left tail of the distribution. It is equivalent to calculating
+ the Quantile.
+ </p>
+<a name="upper_critical"></a><a name="math_toolkit.dist.dist_ref.nmp.upper_critical_value_"></a><h5>
+<a name="id575870"></a>
+ <a href="nmp.html#math_toolkit.dist.dist_ref.nmp.upper_critical_value_">Upper
+ Critical Value.</a>
+ </h5>
+<p>
+ The upper critical value calculates the value of the random variable given
+ the area under the right tail of the distribution. It is equivalent to
+ calculating the <a href="nmp.html#math.dist.quantile_c">quantile from the
+ complement of the probability</a>.
+ </p>
+<a name="survival"></a><a name="math_toolkit.dist.dist_ref.nmp.survival_function"></a><h5>
+<a name="id575917"></a>
+ <a href="nmp.html#math_toolkit.dist.dist_ref.nmp.survival_function">Survival
+ Function</a>
+ </h5>
+<p>
+ Refer to the <a href="nmp.html#math.dist.ccdf">Complement of the Cumulative
+ Distribution Function</a>.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../dist_ref.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dist_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="dists.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/future.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/future.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,141 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Extras/Future Directions</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../dist.html" title="Statistical Distributions and Functions">
+<link rel="prev" href="dist_ref/dist_algorithms.html" title="Distribution Algorithms">
+<link rel="next" href="../special.html" title="Special Functions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="dist_ref/dist_algorithms.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dist.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../special.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.dist.future"></a> Extras/Future Directions
+</h3></div></div></div>
+<a name="math_toolkit.dist.future.adding_additional_location_and_scale_parameters"></a><h5>
+<a name="id616507"></a>
+ <a href="future.html#math_toolkit.dist.future.adding_additional_location_and_scale_parameters">Adding
+ Additional Location and Scale Parameters</a>
+ </h5>
+<p>
+ In some modelling applications we require a distribution with a specific
+ location and scale: often this equates to a specific mean and standard deviation,
+ although for many distributions the relationship between these properties
+ and the location and scale parameters are non-trivial. See http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm
+ for more information.
+ </p>
+<p>
+ The obvious way to handle this is via an adapter template:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Dist</span><span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">scaled_distribution</span>
+<span class="special">{</span>
+ <span class="identifier">scaled_distribution</span><span class="special">(</span>
+ <span class="keyword">const</span> <span class="identifier">Dist</span> <span class="identifier">dist</span><span class="special">,</span>
+ <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">location</span><span class="special">,</span>
+ <span class="keyword">typename</span> <span class="identifier">Dist</span><span class="special">::</span><span class="identifier">value_type</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>
+<span class="special">};</span>
+</pre>
+<p>
+ Which would then have its own set of overloads for the non-member accessor
+ functions.
+ </p>
+<a name="math_toolkit.dist.future.an__quot_any_distribution_quot__class"></a><h5>
+<a name="id616738"></a>
+ <a href="future.html#math_toolkit.dist.future.an__quot_any_distribution_quot__class">An
+ "any_distribution" class</a>
+ </h5>
+<p>
+ It would be fairly trivial to add a distribution object that virtualises
+ the actual type of the distribution, and can therefore hold "any"
+ object that conforms to the conceptual requirements of a distribution:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">any_distribution</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Distribution</span><span class="special">&gt;</span>
+ <span class="identifier">any_distribution</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Distribution</span><span class="special">&amp;</span> <span class="identifier">d</span><span class="special">);</span>
+<span class="special">};</span>
+
+<span class="comment">// Get the cdf of the underlying distribution:
+</span><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">cdf</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">any_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;&amp;</span> <span class="identifier">d</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">x</span><span class="special">);</span>
+<span class="comment">// etc....
+</span></pre>
+<p>
+ Such a class would facilitate the writing of non-template code that can function
+ with any distribution type. It's not clear yet whether there is a compelling
+ use case though. Possibly tests for goodness of fit might provide such a
+ use case: this needs more investigation.
+ </p>
+<a name="math_toolkit.dist.future.higher_level_hypothesis_tests"></a><h5>
+<a name="id617036"></a>
+ <a href="future.html#math_toolkit.dist.future.higher_level_hypothesis_tests">Higher
+ Level Hypothesis Tests</a>
+ </h5>
+<p>
+ Higher-level tests roughly corresponding to the <a href="http://documents.wolfram.com/mathematica/Add-onsLinks/StandardPackages/Statistics/HypothesisTests.html" target="_top">Mathematica
+ Hypothesis Tests</a> package could be added reasonably easily, for example:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">InputIterator</span><span class="special">&gt;</span>
+<span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">InputIterator</span><span class="special">&gt;::</span><span class="identifier">value_type</span>
+ <span class="identifier">test_equal_mean</span><span class="special">(</span>
+ <span class="identifier">InputIterator</span> <span class="identifier">a</span><span class="special">,</span>
+ <span class="identifier">InputIterator</span> <span class="identifier">b</span><span class="special">,</span>
+ <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special">&lt;</span><span class="identifier">InputIterator</span><span class="special">&gt;::</span><span class="identifier">value_type</span> <span class="identifier">expected_mean</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the probability that the data in the sequence [a,b) has the mean
+ <span class="emphasis"><em>expected_mean</em></span>.
+ </p>
+<a name="math_toolkit.dist.future.integration_with_statistical_accumulators"></a><h5>
+<a name="id617269"></a>
+ <a href="future.html#math_toolkit.dist.future.integration_with_statistical_accumulators">Integration
+ With Statistical Accumulators</a>
+ </h5>
+<p>
+ <a href="http://boost-sandbox.sourceforge.net/libs/accumulators/doc/html/index.html" target="_top">Eric
+ Niebler's accumulator framework</a> - also work in progress - provides
+ the means to calculate various statistical properties from experimental data.
+ There is an opportunity to integrate the statistical tests with this framework
+ at some later date:
+ </p>
+<pre class="programlisting">
+<span class="comment">// Define an accumulator, all required statistics to calculate the test
+</span><span class="comment">// are calculated automatically:
+</span><span class="identifier">accumulator_set</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">features</span><span class="special">&lt;</span><span class="identifier">tag</span><span class="special">::</span><span class="identifier">test_expected_mean</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">acc</span><span class="special">(</span><span class="identifier">expected_mean</span><span class="special">=</span><span class="number">4</span><span class="special">);</span>
+<span class="comment">// Pass our data to the accumulator:
+</span><span class="identifier">acc</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">mydata</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">mydata</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">acc</span><span class="special">);</span>
+<span class="comment">// Extract the result:
+</span><span class="keyword">double</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">probability</span><span class="special">(</span><span class="identifier">acc</span><span class="special">);</span>
+</pre>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="dist_ref/dist_algorithms.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dist.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../special.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,130 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Statistical Distributions Tutorial</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../dist.html" title="Statistical Distributions and Functions">
+<link rel="prev" href="../dist.html" title="Statistical Distributions and Functions">
+<link rel="next" href="stat_tut/overview.html" title="Overview">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../dist.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dist.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="stat_tut/overview.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.dist.stat_tut"></a><a href="stat_tut.html" title="Statistical Distributions Tutorial"> Statistical Distributions
+ Tutorial</a>
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"> Overview</span></dt>
+<dt><span class="section"> Worked Examples</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="stat_tut/weg/dist_construct_eg.html">
+ Distribution Construction Example</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/st_eg.html"> Student's
+ t Distribution Examples</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="stat_tut/weg/st_eg/tut_mean_intervals.html">
+ Calculating confidence intervals on the mean with the Students-t distribution</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/st_eg/tut_mean_test.html">
+ Testing a sample mean for difference from a "true" mean</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/st_eg/tut_mean_size.html">
+ Estimating how large a sample size would have to become in order to give
+ a significant Students-t test result with a single sample test</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/st_eg/two_sample_students_t.html">
+ Comparing the means of two samples with the Students-t test</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/st_eg/paired_st.html">
+ Comparing two paired samples with the Student's t distribution</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="stat_tut/weg/cs_eg.html"> Chi Squared
+ Distribution Examples</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="stat_tut/weg/cs_eg/chi_sq_intervals.html">
+ Confidence Intervals on the Standard Deviation</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/cs_eg/chi_sq_test.html">
+ Chi-Square Test for the Standard Deviation</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/cs_eg/chi_sq_size.html">
+ Estimating the Required Sample Sizes for a Chi-Square Test for the Standard
+ Deviation</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="stat_tut/weg/f_eg.html"> F Distribution
+ Examples</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/binom_eg.html"> Binomial
+ Distribution Examples</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="stat_tut/weg/binom_eg/binomial_coinflip_example.html">
+ Binomial Coin-Flipping Example</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/binom_eg/binomial_quiz_example.html">
+ Binomial Quiz Example</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/binom_eg/binom_conf.html">
+ Calculating Confidence Limits on the Frequency of Occurrence for a Binomial
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/binom_eg/binom_size_eg.html">
+ Estimating Sample Sizes for a Binomial Distribution.</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="stat_tut/weg/neg_binom_eg.html"> Negative
+ Binomial Distribution Examples</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="stat_tut/weg/neg_binom_eg/neg_binom_conf.html">
+ Calculating Confidence Limits on the Frequency of Occurrence for the
+ Negative Binomial Distribution</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/neg_binom_eg/neg_binom_size_eg.html">
+ Estimating Sample Sizes for the Negative Binomial.</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/neg_binom_eg/negative_binomial_example1.html">
+ Negative Binomial Sales Quota Example.</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/neg_binom_eg/negative_binomial_example2.html">
+ Negative Binomial Table Printing Example.</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="stat_tut/weg/normal_example.html"> Normal
+ Distribution Examples</a></span></dt>
+<dd><dl><dt><span class="section"><a href="stat_tut/weg/normal_example/normal_misc.html">
+ Some Miscellaneous Examples of the Normal (Gaussian) Distribution</a></span></dt></dl></dd>
+<dt><span class="section"><a href="stat_tut/weg/error_eg.html"> Error Handling
+ Example</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/find_eg.html"> Find Location
+ and Scale Examples</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="stat_tut/weg/find_eg/find_location_eg.html">
+ Find Location (Mean) Example</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/find_eg/find_scale_eg.html">
+ Find Scale (Standard Deviation) Example</a></span></dt>
+<dt><span class="section"><a href="stat_tut/weg/find_eg/find_mean_and_sd_eg.html">
+ Find mean and standard deviation example</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="stat_tut/weg/nag_library.html"> Comparison
+ with C, R, FORTRAN-style Free Functions</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="stat_tut/variates.html"> Random Variates
+ and Distribution Parameters</a></span></dt>
+<dt><span class="section"><a href="stat_tut/dist_params.html"> Discrete Probability
+ Distributions</a></span></dt>
+</dl></div>
+<p>
+ This library is centred around statistical distributions, this tutorial will
+ give you an overview of what they are, how they can be used, and provides
+ a few worked examples of applying the library to statistical tests.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../dist.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dist.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="stat_tut/overview.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/dist_params.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/dist_params.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,94 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Discrete Probability Distributions</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../stat_tut.html" title="Statistical Distributions Tutorial">
+<link rel="prev" href="variates.html" title="Random Variates and Distribution Parameters">
+<link rel="next" href="../dist_ref.html" title="Statistical Distributions Reference">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="variates.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stat_tut.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../dist_ref.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.dist.stat_tut.dist_params"></a><a href="dist_params.html" title="Discrete Probability Distributions"> Discrete Probability
+ Distributions</a>
+</h4></div></div></div>
+<p>
+ Note that the <a href="http://en.wikipedia.org/wiki/Discrete_probability_distribution" target="_top">discrete
+ distributions</a>, including the binomial, negative binomial, Poisson
+ &amp; Bernoulli, are all mathematically defined as discrete functions:
+ only integral values of the random variate are envisaged and the functions
+ are only defined at these integral values. However because the method of
+ calculation often uses continuous functions, it is convenient to treat
+ them as if they were continuous functions, and permit non-integral values
+ of their parameters.
+ </p>
+<p>
+ To enforce a strict mathematical model, users may use floor or ceil functions
+ on the random variate, prior to calling the distribution function, to enforce
+ integral values.
+ </p>
+<p>
+ For similar reasons, in continuous distributions, parameters like degrees
+ of freedom that might appear to be integral, are treated as real values
+ (and are promoted from integer to floating-point if necessary). In this
+ case however, that there are a small number of situations where non-integral
+ degrees of freedom do have a genuine meaning.
+ </p>
+<p>
+ Generally speaking there is no loss of performance from allowing real-values
+ parameters: the underlying special functions contain optimizations for
+ integer-valued arguments when applicable.
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ The quantile function of a discrete distribution will by default return
+ an integer result that has been <span class="emphasis"><em>rounded outwards</em></span>.
+ 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 <span class="emphasis"><em>at least</em></span> the requested coverage
+ will be present in the central region, and <span class="emphasis"><em>no more than</em></span>
+ the requested coverage will be present in the tails.
+ </p>
+<p>
+ This behaviour can be changed so that the quantile functions are rounded
+ differently, or even return a real-valued result using Policies.
+ It is strongly recommended that you read the tutorial <a href="../../policy/pol_tutorial/understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">Understanding
+ Quantiles of Discrete Distributions</a> before using the quantile
+ function on a discrete distribution. The <a href="../../policy/pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">reference
+ docs</a> describe how to change the rounding policy for these distributions.
+ </p>
+</td></tr>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="variates.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stat_tut.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../dist_ref.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/overview.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/overview.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,527 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Overview</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../stat_tut.html" title="Statistical Distributions Tutorial">
+<link rel="prev" href="../stat_tut.html" title="Statistical Distributions Tutorial">
+<link rel="next" href="weg.html" title="Worked Examples">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../stat_tut.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stat_tut.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="weg.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.dist.stat_tut.overview"></a> Overview
+</h4></div></div></div>
+<a name="math_toolkit.dist.stat_tut.overview.headers_and_namespaces"></a><h5>
+<a name="id496174"></a>
+ <a href="overview.html#math_toolkit.dist.stat_tut.overview.headers_and_namespaces">Headers
+ and Namespaces</a>
+ </h5>
+<p>
+ All the code in this library is inside namespace boost::math.
+ </p>
+<p>
+ In order to use a distribution <span class="emphasis"><em>my_distribution</em></span> you
+ will need to include either the header &lt;boost/math/distributions/my_distribution.hpp&gt;
+ or the "include everything" header: &lt;boost/math/distributions.hpp&gt;.
+ </p>
+<p>
+ For example, to use the Students-t distribution include either &lt;boost/math/distributions/students_t.hpp&gt;
+ or &lt;boost/math/distributions.hpp&gt;
+ </p>
+<a name="math_toolkit.dist.stat_tut.overview.distributions_are_objects"></a><h5>
+<a name="id496227"></a>
+ <a href="overview.html#math_toolkit.dist.stat_tut.overview.distributions_are_objects">Distributions
+ are Objects</a>
+ </h5>
+<p>
+ Each kind of distribution in this library is a class type.
+ </p>
+<p>
+ Policies provide fine-grained
+ control of the behaviour of these classes, allowing the user to customise
+ behaviour such as how errors are handled, or how the quantiles of discrete
+ distribtions behave.
+ </p>
+<div class="tip"><table border="0" summary="Tip">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../../doc/html/images/tip.png"></td>
+<th align="left">Tip</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ If you are familiar with statistics libraries using functions, and 'Distributions
+ as Objects' seem alien, see <a href="weg/nag_library.html" title="Comparison with C, R, FORTRAN-style Free Functions">the
+ comparison to other statistics libraries.</a>
+ </p></td></tr>
+</table></div>
+<p>
+ Making distributions class types does two things:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ It encapsulates the kind of distribution in the C++ type system; so,
+ for example, Students-t distributions are always a different C++ type
+ from Chi-Squared distributions.
+ </li>
+<li>
+ The distribution objects store any parameters associated with the distribution:
+ for example, the Students-t distribution has a <span class="emphasis"><em>degrees of freedom</em></span>
+ parameter that controls the shape of the distribution. This <span class="emphasis"><em>degrees
+ of freedom</em></span> parameter has to be provided to the Students-t
+ object when it is constructed.
+ </li>
+</ul></div>
+<p>
+ Although the distribution classes in this library are templates, there
+ are typedefs on type <span class="emphasis"><em>double</em></span> that mostly take the usual
+ name of the distribution (except where there is a clash with a function
+ of the same name: beta and gamma, in which case using the default template
+ arguments - <code class="computeroutput"><span class="identifier">RealType</span> <span class="special">=</span>
+ <span class="keyword">double</span></code> - is nearly as convenient).
+ Probably 95% of uses are covered by these typedefs:
+ </p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+
+<span class="comment">// Construct a students_t distribution with 4 degrees of freedom:
+</span><span class="identifier">students_t</span> <span class="identifier">d1</span><span class="special">(</span><span class="number">4</span><span class="special">);</span>
+
+<span class="comment">// Construct a double-precision beta distribution
+</span><span class="comment">// with parameters a = 10, b = 20
+</span><span class="identifier">beta_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">d2</span><span class="special">(</span><span class="number">10</span><span class="special">,</span> <span class="number">20</span><span class="special">);</span> <span class="comment">// Note: _distribution&lt;&gt; suffix !
+</span></pre>
+<p>
+ If you need to use the distributions with a type other than <code class="computeroutput"><span class="keyword">double</span></code>, then you can instantiate the template
+ directly: the names of the templates are the same as the <code class="computeroutput"><span class="keyword">double</span></code> typedef but with <code class="computeroutput"><span class="identifier">_distribution</span></code>
+ appended, for example: <a href="../dist_ref/dists/students_t_dist.html" title="Students t Distribution">Students
+ t Distribution</a> or <a href="../dist_ref/dists/binomial_dist.html" title="Binomial Distribution">Binomial
+ Distribution</a>:
+ </p>
+<pre class="programlisting">
+<span class="comment">// Construct a students_t distribution, of float type,
+</span><span class="comment">// with 4 degrees of freedom:
+</span><span class="identifier">students_t_distribution</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;</span> <span class="identifier">d3</span><span class="special">(</span><span class="number">4</span><span class="special">);</span>
+
+<span class="comment">// Construct a binomial distribution, of long double type,
+</span><span class="comment">// with probability of success 0.3
+</span><span class="comment">// and 20 trials in total:
+</span><span class="identifier">binomial_distribution</span><span class="special">&lt;</span><span class="keyword">long</span> <span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">d4</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">);</span>
+</pre>
+<p>
+ The parameters passed to the distributions can be accessed via getter member
+ functions:
+ </p>
+<pre class="programlisting">
+<span class="identifier">d1</span><span class="special">.</span><span class="identifier">degrees_of_freedom</span><span class="special">();</span> <span class="comment">// returns 4.0
+</span></pre>
+<p>
+ This is all well and good, but not very useful so far. What we often want
+ is to be able to calculate the <span class="emphasis"><em>cumulative distribution functions</em></span>
+ and <span class="emphasis"><em>quantiles</em></span> etc for these distributions.
+ </p>
+<a name="math_toolkit.dist.stat_tut.overview.generic_operations_common_to_all_distributions_are_non_member_functions"></a><h5>
+<a name="id496764"></a>
+ <a href="overview.html#math_toolkit.dist.stat_tut.overview.generic_operations_common_to_all_distributions_are_non_member_functions">Generic
+ operations common to all distributions are non-member functions</a>
+ </h5>
+<p>
+ Want to calculate the PDF (Probability Density Function) of a distribution?
+ No problem, just use:
+ </p>
+<pre class="programlisting">
+<span class="identifier">pdf</span><span class="special">(</span><span class="identifier">my_dist</span><span class="special">,</span> <span class="identifier">x</span><span class="special">);</span> <span class="comment">// Returns PDF (density) at point x of distribution my_dist.
+</span></pre>
+<p>
+ Or how about the CDF (Cumulative Distribution Function):
+ </p>
+<pre class="programlisting">
+<span class="identifier">cdf</span><span class="special">(</span><span class="identifier">my_dist</span><span class="special">,</span> <span class="identifier">x</span><span class="special">);</span> <span class="comment">// Returns CDF (integral from -infinity to point x)
+</span> <span class="comment">// of distribution my_dist.
+</span></pre>
+<p>
+ And quantiles are just the same:
+ </p>
+<pre class="programlisting">
+<span class="identifier">quantile</span><span class="special">(</span><span class="identifier">my_dist</span><span class="special">,</span> <span class="identifier">p</span><span class="special">);</span> <span class="comment">// Returns the value of the random variable x
+</span> <span class="comment">// such that cdf(my_dist, x) == p.
+</span></pre>
+<p>
+ If you're wondering why these aren't member functions, it's to make the
+ library more easily extensible: if you want to add additional generic operations
+ - let's say the <span class="emphasis"><em>n'th moment</em></span> - then all you have to
+ do is add the appropriate non-member functions, overloaded for each implemented
+ distribution type.
+ </p>
+<div class="tip"><table border="0" summary="Tip">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../../doc/html/images/tip.png"></td>
+<th align="left">Tip</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ </p>
+<p>
+ <span class="bold"><strong>Random numbers that approximate Quantiles of Distributions</strong></span>
+ </p>
+<p>
+ If you want random numbers that are distributed in a specific way, for
+ example in a uniform, normal or triangular, see Boost.Random.
+ </p>
+<p>
+ Whilst in principal there's nothing to prevent you from using the quantile
+ function to convert a uniformly distributed random number to another
+ distribution, in practice there are much more efficient algorithms available
+ that are specific to random number generation.
+ </p>
+</td></tr>
+</table></div>
+<p>
+ For example, the binomial distribution has two parameters: n (the number
+ of trials) and p (the probability of success on one trial).
+ </p>
+<p>
+ The <code class="computeroutput"><span class="identifier">binomial_distribution</span></code>
+ constructor therefore has two parameters:
+ </p>
+<p>
+ <code class="computeroutput"><span class="identifier">binomial_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">RealType</span>
+ <span class="identifier">p</span><span class="special">);</span></code>
+ </p>
+<p>
+ For this distribution the random variate is k: the number of successes
+ observed. The probability density/mass function (pdf) is therefore written
+ as <span class="emphasis"><em>f(k; n, p)</em></span>.
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ </p>
+<p>
+ <span class="bold"><strong>Random Variates and Distribution Parameters</strong></span>
+ </p>
+<p>
+ Random variates
+ and <a href="http://en.wikipedia.org/wiki/Parameter" target="_top">distribution
+ parameters</a> are conventionally distinguished (for example in Wikipedia
+ and Wolfram MathWorld by placing a semi-colon (or sometimes vertical
+ bar) after the random variate (whose value you 'choose'), to separate
+ the variate from the parameter(s) that defines the shape of the distribution.
+ </p>
+</td></tr>
+</table></div>
+<p>
+ As noted above the non-member function <code class="computeroutput"><span class="identifier">pdf</span></code>
+ has one parameter for the distribution object, and a second for the random
+ variate. So taking our binomial distribution example, we would write:
+ </p>
+<p>
+ <code class="computeroutput"><span class="identifier">pdf</span><span class="special">(</span><span class="identifier">binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;(</span><span class="identifier">n</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">);</span></code>
+ </p>
+<p>
+ The distribution (effectively the random variate) is said to be 'supported'
+ over a range that is <a href="http://en.wikipedia.org/wiki/Probability_distribution" target="_top">"the
+ smallest closed set whose complement has probability zero"</a>.
+ MathWorld uses the word 'defined' for this range. Non-mathematicians might
+ say it means the 'interesting' smallest range of random variate x that
+ has the cdf going from zero to unity. Outside are uninteresting zones where
+ the pdf is zero, and the cdf zero or unity. Mathematically, the functions
+ may make sense with an (+ or -) infinite value, but except for a few special
+ cases (in the Normal and Cauchy distributions) this implementation limits
+ random variates to finite values from the <code class="computeroutput"><span class="identifier">max</span></code>
+ to <code class="computeroutput"><span class="identifier">min</span></code> for the <code class="computeroutput"><span class="identifier">RealType</span></code>. (See <a href="../../backgrounders/implementation.html#math_toolkit.backgrounders.implementation.handling_of_floating_point_infinity">Handling
+ of Floating-Point Infinity</a> for rationale).
+ </p>
+<p>
+ The range of random variate values that is permitted and supported can
+ be tested by using two functions <code class="computeroutput"><span class="identifier">range</span></code>
+ and <code class="computeroutput"><span class="identifier">support</span></code>.
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ </p>
+<p>
+ <span class="bold"><strong>Discrete Probability Distributions</strong></span>
+ </p>
+<p>
+ Note that the <a href="http://en.wikipedia.org/wiki/Discrete_probability_distribution" target="_top">discrete
+ distributions</a>, including the binomial, negative binomial, Poisson
+ &amp; Bernoulli, are all mathematically defined as discrete functions:
+ that is to say the functions <code class="computeroutput"><span class="identifier">cdf</span></code>
+ and <code class="computeroutput"><span class="identifier">pdf</span></code> are only defined
+ for integral values of the random variate.
+ </p>
+<p>
+ However, because the method of calculation often uses continuous functions
+ it is convenient to treat them as if they were continuous functions,
+ and permit non-integral values of their parameters.
+ </p>
+<p>
+ Users wanting to enforce a strict mathematical model may use <code class="computeroutput"><span class="identifier">floor</span></code> or <code class="computeroutput"><span class="identifier">ceil</span></code>
+ functions on the random variate prior to calling the distribution function.
+ </p>
+<p>
+ The quantile functions for these distributions are hard to specify in
+ a manner that will satisfy everyone all of the time. The default behaviour
+ is to return an integer result, that has been rounded <span class="emphasis"><em>outwards</em></span>:
+ that is to say, lower quantiles - where the probablity is less than 0.5
+ are rounded down, while upper quantiles - where the probability is greater
+ than 0.5 - are rounded up. This behaviour ensures that if an X% quantile
+ is requested, then <span class="emphasis"><em>at least</em></span> the requested coverage
+ will be present in the central region, and <span class="emphasis"><em>no more than</em></span>
+ the requested coverage will be present in the tails.
+ </p>
+<p>
+ This behaviour can be changed so that the quantile functions are rounded
+ differently, or return a real-valued result using Policies.
+ It is strongly recommended that you read the tutorial <a href="../../policy/pol_tutorial/understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">Understanding
+ Quantiles of Discrete Distributions</a> before using the quantile
+ function on a discrete distribtion. The <a href="../../policy/pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">reference
+ docs</a> describe how to change the rounding policy for these distributions.
+ </p>
+<p>
+ For similar reasons continuous distributions with parameters like "degrees
+ of freedom" that might appear to be integral, are treated as real
+ values (and are promoted from integer to floating-point if necessary).
+ In this case however, there are a small number of situations where non-integral
+ degrees of freedom do have a genuine meaning.
+ </p>
+</td></tr>
+</table></div>
+<a name="complements"></a><p>
+ </p>
+<a name="math_toolkit.dist.stat_tut.overview.complements_are_supported_too"></a><h5>
+<a name="id497493"></a>
+ <a href="overview.html#math_toolkit.dist.stat_tut.overview.complements_are_supported_too">Complements
+ are supported too</a>
+ </h5>
+<p>
+ Often you don't want the value of the CDF, but its complement, which is
+ to say <code class="computeroutput"><span class="number">1</span><span class="special">-</span><span class="identifier">p</span></code> rather than <code class="computeroutput"><span class="identifier">p</span></code>.
+ You could calculate the CDF and subtract it from <code class="computeroutput"><span class="number">1</span></code>,
+ but if <code class="computeroutput"><span class="identifier">p</span></code> is very close
+ to <code class="computeroutput"><span class="number">1</span></code> then cancellation error
+ will cause you to lose significant digits. In extreme cases, <code class="computeroutput"><span class="identifier">p</span></code> may actually be equal to <code class="computeroutput"><span class="number">1</span></code>, even though the true value of the complement
+ is non-zero.
+ </p>
+<p>
+ See also "Why complements?"
+ </p>
+<p>
+ In this library, whenever you want to receive a complement, just wrap all
+ the function arguments in a call to <code class="computeroutput"><span class="identifier">complement</span><span class="special">(...)</span></code>, for example:
+ </p>
+<pre class="programlisting">
+<span class="identifier">students_t</span> <span class="identifier">dist</span><span class="special">(</span><span class="number">5</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"CDF at t = 1 is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="number">1.0</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Complement of CDF at t = 1 is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="number">1.0</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+</pre>
+<p>
+ But wait, now that we have a complement, we have to be able to use it as
+ well. Any function that accepts a probability as an argument can also accept
+ a complement by wrapping all of its arguments in a call to <code class="computeroutput"><span class="identifier">complement</span><span class="special">(...)</span></code>,
+ for example:
+ </p>
+<pre class="programlisting">
+<span class="identifier">students_t</span> <span class="identifier">dist</span><span class="special">(</span><span class="number">5</span><span class="special">);</span>
+
+<span class="keyword">for</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">10</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="number">1e10</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">*=</span> <span class="number">10</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="comment">// Calculate the quantile for a 1 in i chance:
+</span> <span class="keyword">double</span> <span class="identifier">t</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="number">1</span><span class="special">/</span><span class="identifier">i</span><span class="special">));</span>
+ <span class="comment">// Print it out:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Quantile of students-t with 5 degrees of freedom\n"</span>
+ <span class="string">"for a 1 in "</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span> <span class="special">&lt;&lt;</span> <span class="string">" chance is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">t</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<div class="tip"><table border="0" summary="Tip">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../../doc/html/images/tip.png"></td>
+<th align="left">Tip</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ </p>
+<p>
+ <span class="bold"><strong>Critical values are just quantiles</strong></span>
+ </p>
+<p>
+ Some texts talk about quantiles, others about critical values, the basic
+ rule is:
+ </p>
+<p>
+ <span class="emphasis"><em>Lower critical values</em></span> are the same as the quantile.
+ </p>
+<p>
+ <span class="emphasis"><em>Upper critical values</em></span> are the same as the quantile
+ from the complement of the probability.
+ </p>
+<p>
+ For example, suppose we have a Bernoulli process, giving rise to a binomial
+ distribution with success ratio 0.1 and 100 trials in total. The <span class="emphasis"><em>lower
+ critical value</em></span> for a probability of 0.05 is given by:
+ </p>
+<p>
+ <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="number">100</span><span class="special">,</span> <span class="number">0.1</span><span class="special">),</span> <span class="number">0.05</span><span class="special">)</span></code>
+ </p>
+<p>
+ and the <span class="emphasis"><em>upper critical value</em></span> is given by:
+ </p>
+<p>
+ <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="number">100</span><span class="special">,</span> <span class="number">0.1</span><span class="special">),</span> <span class="number">0.05</span><span class="special">))</span></code>
+ </p>
+<p>
+ which return 4.82 and 14.63 respectively.
+ </p>
+</td></tr>
+</table></div>
+<a name="why_complements"></a><p>
+ </p>
+<div class="tip"><table border="0" summary="Tip">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../../doc/html/images/tip.png"></td>
+<th align="left">Tip</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ </p>
+<p>
+ <span class="bold"><strong>Why bother with complements anyway?</strong></span>
+ </p>
+<p>
+ It's very tempting to dispense with complements, and simply subtract
+ the probability from 1 when required. However, consider what happens
+ when the probability is very close to 1: let's say the probability expressed
+ at float precision is <code class="computeroutput"><span class="number">0.999999940f</span></code>,
+ then <code class="computeroutput"><span class="number">1</span> <span class="special">-</span>
+ <span class="number">0.999999940f</span> <span class="special">=</span>
+ <span class="number">5.96046448e-008</span></code>, but the result
+ is actually accurate to just <span class="emphasis"><em>one single bit</em></span>: the
+ only bit that didn't cancel out!
+ </p>
+<p>
+ Or to look at this another way: consider that we want the risk of falsely
+ rejecting the null-hypothesis in the Student's t test to be 1 in 1 billion,
+ for a sample size of 10,000. This gives a probability of 1 - 10<sup>-9</sup>, which
+ is exactly 1 when calculated at float precision. In this case calculating
+ the quantile from the complement neatly solves the problem, so for example:
+ </p>
+<p>
+ <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">students_t</span><span class="special">(</span><span class="number">10000</span><span class="special">),</span> <span class="number">1e-9</span><span class="special">))</span></code>
+ </p>
+<p>
+ returns the expected t-statistic <code class="computeroutput"><span class="number">6.00336</span></code>,
+ where as:
+ </p>
+<p>
+ <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">students_t</span><span class="special">(</span><span class="number">10000</span><span class="special">),</span> <span class="number">1</span><span class="special">-</span><span class="number">1e-9f</span><span class="special">)</span></code>
+ </p>
+<p>
+ raises an overflow error, since it is the same as:
+ </p>
+<p>
+ <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">students_t</span><span class="special">(</span><span class="number">10000</span><span class="special">),</span> <span class="number">1</span><span class="special">)</span></code>
+ </p>
+<p>
+ Which has no finite result.
+ </p>
+</td></tr>
+</table></div>
+<a name="math_toolkit.dist.stat_tut.overview.parameters_can_be_calculated"></a><h5>
+<a name="id498675"></a>
+ <a href="overview.html#math_toolkit.dist.stat_tut.overview.parameters_can_be_calculated">Parameters
+ can be calculated</a>
+ </h5>
+<p>
+ Sometimes it's the parameters that define the distribution that you need
+ to find. Suppose, for example, you have conducted a Students-t test for
+ equal means and the result is borderline. Maybe your two samples differ
+ from each other, or maybe they don't; based on the result of the test you
+ can't be sure. A legitimate question to ask then is "How many more
+ measurements would I have to take before I would get an X% probability
+ that the difference is real?" Parameter finders can answer questions
+ like this, and are necessarily different for each distribution. They are
+ implemented as static member functions of the distributions, for example:
+ </p>
+<pre class="programlisting">
+<span class="identifier">students_t</span><span class="special">::</span><span class="identifier">find_degrees_of_freedom</span><span class="special">(</span>
+ <span class="number">1.3</span><span class="special">,</span> <span class="comment">// difference from true mean to detect
+</span> <span class="number">0.05</span><span class="special">,</span> <span class="comment">// maximum risk of falsely rejecting the null-hypothesis.
+</span> <span class="number">0.1</span><span class="special">,</span> <span class="comment">// maximum risk of falsely failing to reject the null-hypothesis.
+</span> <span class="number">0.13</span><span class="special">);</span> <span class="comment">// sample standard deviation
+</span></pre>
+<p>
+ Returns the number of degrees of freedom required to obtain a 95% probability
+ that the observed differences in means is not down to chance alone. In
+ the case that a borderline Students-t test result was previously obtained,
+ this can be used to estimate how large the sample size would have to become
+ before the observed difference was considered significant. It assumes,
+ of course, that the sample mean and standard deviation are invariant with
+ sample size.
+ </p>
+<a name="math_toolkit.dist.stat_tut.overview.summary"></a><h5>
+<a name="id498829"></a>
+ Summary
+ </h5>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Distributions are objects, which are constructed from whatever parameters
+ the distribution may have.
+ </li>
+<li>
+ Member functions allow you to retrieve the parameters of a distribution.
+ </li>
+<li>
+ Generic non-member functions provide access to the properties that are
+ common to all the distributions (PDF, CDF, quantile etc).
+ </li>
+<li>
+ Complements of probabilities are calculated by wrapping the function's
+ arguments in a call to <code class="computeroutput"><span class="identifier">complement</span><span class="special">(...)</span></code>.
+ </li>
+<li>
+ Functions that accept a probability can accept a complement of the probability
+ as well, by wrapping the function's arguments in a call to <code class="computeroutput"><span class="identifier">complement</span><span class="special">(...)</span></code>.
+ </li>
+<li>
+ Static member functions allow the parameters of a distribution to be
+ found from other information.
+ </li>
+</ul></div>
+<p>
+ Now that you have the basics, the next section looks at some worked examples.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../stat_tut.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stat_tut.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="weg.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/variates.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/variates.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,72 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Random Variates and Distribution Parameters</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../stat_tut.html" title="Statistical Distributions Tutorial">
+<link rel="prev" href="weg/nag_library.html" title="Comparison with C, R, FORTRAN-style Free Functions">
+<link rel="next" href="dist_params.html" title="Discrete Probability Distributions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="weg/nag_library.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stat_tut.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="dist_params.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.dist.stat_tut.variates"></a><a href="variates.html" title="Random Variates and Distribution Parameters"> Random Variates
+ and Distribution Parameters</a>
+</h4></div></div></div>
+<p>
+ Random variates
+ and distribution parameters
+ are conventionally distinguished (for example in Wikipedia and Wolfram
+ MathWorld by placing a semi-colon after the random variate (whose value
+ you 'choose'), to separate the variate from the parameter(s) that defines
+ the shape of the distribution.
+ </p>
+<p>
+ For example, the binomial distribution has two parameters: n (the number
+ of trials) and p (the probability of success on one trial). It also has
+ the random variate <span class="emphasis"><em>k</em></span>: the number of successes observed.
+ This means the probability density/mass function (pdf) is written as <span class="emphasis"><em>f(k;
+ n, p)</em></span>.
+ </p>
+<p>
+ Translating this into code the <code class="computeroutput"><span class="identifier">binomial_distribution</span></code>
+ constructor therefore has two parameters:
+ </p>
+<pre class="programlisting">
+<span class="identifier">binomial_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">);</span>
+</pre>
+<p>
+ While the function <code class="computeroutput"><span class="identifier">pdf</span></code>
+ has one argument specifying the distribution type (which includes it's
+ parameters, if any), and a second argument for the random variate. So taking
+ our binomial distribution example, we would write:
+ </p>
+<pre class="programlisting">
+<span class="identifier">pdf</span><span class="special">(</span><span class="identifier">binomial_distribution</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;(</span><span class="identifier">n</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">);</span>
+</pre>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="weg/nag_library.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stat_tut.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="dist_params.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,120 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Worked Examples</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../stat_tut.html" title="Statistical Distributions Tutorial">
+<link rel="prev" href="overview.html" title="Overview">
+<link rel="next" href="weg/dist_construct_eg.html" title="Distribution Construction Example">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="overview.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stat_tut.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="weg/dist_construct_eg.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.dist.stat_tut.weg"></a> Worked Examples
+</h4></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="weg/dist_construct_eg.html">
+ Distribution Construction Example</a></span></dt>
+<dt><span class="section"><a href="weg/st_eg.html"> Student's
+ t Distribution Examples</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="weg/st_eg/tut_mean_intervals.html">
+ Calculating confidence intervals on the mean with the Students-t distribution</a></span></dt>
+<dt><span class="section"><a href="weg/st_eg/tut_mean_test.html">
+ Testing a sample mean for difference from a "true" mean</a></span></dt>
+<dt><span class="section"><a href="weg/st_eg/tut_mean_size.html">
+ Estimating how large a sample size would have to become in order to give
+ a significant Students-t test result with a single sample test</a></span></dt>
+<dt><span class="section"><a href="weg/st_eg/two_sample_students_t.html">
+ Comparing the means of two samples with the Students-t test</a></span></dt>
+<dt><span class="section"><a href="weg/st_eg/paired_st.html">
+ Comparing two paired samples with the Student's t distribution</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="weg/cs_eg.html"> Chi Squared
+ Distribution Examples</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="weg/cs_eg/chi_sq_intervals.html">
+ Confidence Intervals on the Standard Deviation</a></span></dt>
+<dt><span class="section"><a href="weg/cs_eg/chi_sq_test.html">
+ Chi-Square Test for the Standard Deviation</a></span></dt>
+<dt><span class="section"><a href="weg/cs_eg/chi_sq_size.html">
+ Estimating the Required Sample Sizes for a Chi-Square Test for the Standard
+ Deviation</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="weg/f_eg.html"> F Distribution
+ Examples</a></span></dt>
+<dt><span class="section"><a href="weg/binom_eg.html"> Binomial
+ Distribution Examples</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="weg/binom_eg/binomial_coinflip_example.html">
+ Binomial Coin-Flipping Example</a></span></dt>
+<dt><span class="section"><a href="weg/binom_eg/binomial_quiz_example.html">
+ Binomial Quiz Example</a></span></dt>
+<dt><span class="section"><a href="weg/binom_eg/binom_conf.html">
+ Calculating Confidence Limits on the Frequency of Occurrence for a Binomial
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="weg/binom_eg/binom_size_eg.html">
+ Estimating Sample Sizes for a Binomial Distribution.</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="weg/neg_binom_eg.html"> Negative
+ Binomial Distribution Examples</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="weg/neg_binom_eg/neg_binom_conf.html">
+ Calculating Confidence Limits on the Frequency of Occurrence for the
+ Negative Binomial Distribution</a></span></dt>
+<dt><span class="section"><a href="weg/neg_binom_eg/neg_binom_size_eg.html">
+ Estimating Sample Sizes for the Negative Binomial.</a></span></dt>
+<dt><span class="section"><a href="weg/neg_binom_eg/negative_binomial_example1.html">
+ Negative Binomial Sales Quota Example.</a></span></dt>
+<dt><span class="section"><a href="weg/neg_binom_eg/negative_binomial_example2.html">
+ Negative Binomial Table Printing Example.</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="weg/normal_example.html"> Normal
+ Distribution Examples</a></span></dt>
+<dd><dl><dt><span class="section"><a href="weg/normal_example/normal_misc.html">
+ Some Miscellaneous Examples of the Normal (Gaussian) Distribution</a></span></dt></dl></dd>
+<dt><span class="section"><a href="weg/error_eg.html"> Error Handling
+ Example</a></span></dt>
+<dt><span class="section"><a href="weg/find_eg.html"> Find Location
+ and Scale Examples</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="weg/find_eg/find_location_eg.html">
+ Find Location (Mean) Example</a></span></dt>
+<dt><span class="section"><a href="weg/find_eg/find_scale_eg.html">
+ Find Scale (Standard Deviation) Example</a></span></dt>
+<dt><span class="section"><a href="weg/find_eg/find_mean_and_sd_eg.html">
+ Find mean and standard deviation example</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="weg/nag_library.html"> Comparison
+ with C, R, FORTRAN-style Free Functions</a></span></dt>
+</dl></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="overview.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../stat_tut.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="weg/dist_construct_eg.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/binom_eg.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/binom_eg.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,56 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Binomial Distribution Examples</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../weg.html" title="Worked Examples">
+<link rel="prev" href="f_eg.html" title="F Distribution Examples">
+<link rel="next" href="binom_eg/binomial_coinflip_example.html" title="Binomial Coin-Flipping Example">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="f_eg.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="binom_eg/binomial_coinflip_example.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.binom_eg"></a><a href="binom_eg.html" title="Binomial Distribution Examples"> Binomial
+ Distribution Examples</a>
+</h5></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="binom_eg/binomial_coinflip_example.html">
+ Binomial Coin-Flipping Example</a></span></dt>
+<dt><span class="section"><a href="binom_eg/binomial_quiz_example.html">
+ Binomial Quiz Example</a></span></dt>
+<dt><span class="section"><a href="binom_eg/binom_conf.html">
+ Calculating Confidence Limits on the Frequency of Occurrence for a Binomial
+ Distribution</a></span></dt>
+<dt><span class="section"><a href="binom_eg/binom_size_eg.html">
+ Estimating Sample Sizes for a Binomial Distribution.</a></span></dt>
+</dl></div>
+<p>
+ See also the reference documentation for the <a href="../../dist_ref/dists/binomial_dist.html" title="Binomial Distribution">Binomial
+ Distribution</a>.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="f_eg.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="binom_eg/binomial_coinflip_example.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/binom_eg/binom_conf.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/binom_eg/binom_conf.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,242 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Calculating Confidence Limits on the Frequency of Occurrence for a Binomial Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../binom_eg.html" title="Binomial Distribution Examples">
+<link rel="prev" href="binomial_quiz_example.html" title="Binomial Quiz Example">
+<link rel="next" href="binom_size_eg.html" title="Estimating Sample Sizes for a Binomial Distribution.">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="binomial_quiz_example.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../binom_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="binom_size_eg.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.binom_eg.binom_conf"></a><a href="binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for a Binomial Distribution">
+ Calculating Confidence Limits on the Frequency of Occurrence for a Binomial
+ Distribution</a>
+</h6></div></div></div>
+<p>
+ Imagine you have a process that follows a binomial distribution: for
+ each trial conducted, an event either occurs or does it does not, referred
+ to as "successes" and "failures". If, by experiment,
+ you want to measure the frequency with which successes occur, the best
+ estimate is given simply by <span class="emphasis"><em>k</em></span> / <span class="emphasis"><em>N</em></span>,
+ for <span class="emphasis"><em>k</em></span> successes out of <span class="emphasis"><em>N</em></span>
+ trials. However our confidence in that estimate will be shaped by how
+ many trials were conducted, and how many successes were observed. The
+ static member functions <code class="computeroutput"><span class="identifier">binomial_distribution</span><span class="special">&lt;&gt;::</span><span class="identifier">find_lower_bound_on_p</span></code>
+ and <code class="computeroutput"><span class="identifier">binomial_distribution</span><span class="special">&lt;&gt;::</span><span class="identifier">find_upper_bound_on_p</span></code>
+ allow you to calculate the confidence intervals for your estimate of
+ the occurrence frequency.
+ </p>
+<p>
+ The sample program binomial_confidence_limits.cpp
+ illustrates their use. It begins by defining a procedure that will
+ print a table of confidence limits for various degrees of certainty:
+ </p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iomanip</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">void</span> <span class="identifier">confidence_limits_on_frequency</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">trials</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">successes</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="comment">//
+</span> <span class="comment">// trials = Total number of trials.
+</span> <span class="comment">// successes = Total number of observed successes.
+</span> <span class="comment">//
+</span> <span class="comment">// Calculate confidence limits for an observed
+</span> <span class="comment">// frequency of occurrence that follows a binomial
+</span> <span class="comment">// distribution.
+</span> <span class="comment">//
+</span> <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">std</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+
+ <span class="comment">// Print out general info:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span>
+ <span class="string">"___________________________________________\n"</span>
+ <span class="string">"2-Sided Confidence Limits For Success Ratio\n"</span>
+ <span class="string">"___________________________________________\n\n"</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">7</span><span class="special">);</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">40</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Number of Observations"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">trials</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">40</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Number of successes"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">successes</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">40</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Sample frequency of occurrence"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="keyword">double</span><span class="special">(</span><span class="identifier">successes</span><span class="special">)</span> <span class="special">/</span> <span class="identifier">trials</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+</pre>
+<p>
+ The procedure now defines a table of significance levels: these are
+ the probabilities that the true occurrence frequency lies outside the
+ calculated interval:
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">alpha</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">0.5</span><span class="special">,</span> <span class="number">0.25</span><span class="special">,</span> <span class="number">0.1</span><span class="special">,</span> <span class="number">0.05</span><span class="special">,</span> <span class="number">0.01</span><span class="special">,</span> <span class="number">0.001</span><span class="special">,</span> <span class="number">0.0001</span><span class="special">,</span> <span class="number">0.00001</span> <span class="special">};</span>
+</pre>
+<p>
+ Some pretty printing of the table header follows:
+ </p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n\n"</span>
+ <span class="string">"_______________________________________________________________________\n"</span>
+ <span class="string">"Confidence Lower CP Upper CP Lower JP Upper JP\n"</span>
+ <span class="string">" Value (%) Limit Limit Limit Limit\n"</span>
+ <span class="string">"_______________________________________________________________________\n"</span><span class="special">;</span>
+</pre>
+<p>
+ And now for the important part - the intervals themselves - for each
+ value of <span class="emphasis"><em>alpha</em></span>, we call <code class="computeroutput"><span class="identifier">find_lower_bound_on_p</span></code>
+ and <code class="computeroutput"><span class="identifier">find_lower_upper_on_p</span></code>
+ to obtain lower and upper bounds respectively. Note that since we are
+ calculating a two-sided interval, we must divide the value of alpha
+ in two.
+ </p>
+<p>
+ Please note that calculating two separate <span class="emphasis"><em>single sided bounds</em></span>,
+ each with risk level &#945;is not the same thing as calculating a two sided
+ interval. Had we calculate two single-sided intervals each with a risk
+ that the true value is outside the interval of &#945;, then:
+ </p>
+<div class="itemizedlist"><ul type="disc"><li>
+ The risk that it is less than the lower bound is &#945;.
+ </li></ul></div>
+<p>
+ and
+ </p>
+<div class="itemizedlist"><ul type="disc"><li>
+ The risk that it is greater than the upper bound is also &#945;.
+ </li></ul></div>
+<p>
+ So the risk it is outside <span class="bold"><strong>upper or lower bound</strong></span>,
+ is <span class="bold"><strong>twice</strong></span> alpha, and the probability
+ that it is inside the bounds is therefore not nearly as high as one
+ might have thought. This is why &#945;/2 must be used in the calculations
+ below.
+ </p>
+<p>
+ In contrast, had we been calculating a single-sided interval, for example:
+ <span class="emphasis"><em>"Calculate a lower bound so that we are P% sure that
+ the true occurrence frequency is greater than some value"</em></span>
+ then we would <span class="bold"><strong>not</strong></span> have divided by
+ two.
+ </p>
+<p>
+ Finally note that <code class="computeroutput"><span class="identifier">binomial_distribution</span></code>
+ provides a choice of two methods for the calculation, we print out
+ the results from both methods in this example:
+ </p>
+<pre class="programlisting">
+ <span class="keyword">for</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">)/</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">[</span><span class="number">0</span><span class="special">]);</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="comment">// Confidence value:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="number">100</span> <span class="special">*</span> <span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]);</span>
+ <span class="comment">// Calculate Clopper Pearson bounds:
+</span> <span class="keyword">double</span> <span class="identifier">l</span> <span class="special">=</span> <span class="identifier">binomial_distribution</span><span class="special">&lt;&gt;::</span><span class="identifier">find_lower_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">trials</span><span class="special">,</span> <span class="identifier">successes</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]/</span><span class="number">2</span><span class="special">);</span>
+ <span class="keyword">double</span> <span class="identifier">u</span> <span class="special">=</span> <span class="identifier">binomial_distribution</span><span class="special">&lt;&gt;::</span><span class="identifier">find_upper_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">trials</span><span class="special">,</span> <span class="identifier">successes</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]/</span><span class="number">2</span><span class="special">);</span>
+ <span class="comment">// Print Clopper Pearson Limits:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">5</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">15</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">l</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">5</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">15</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">u</span><span class="special">;</span>
+ <span class="comment">// Calculate Jeffreys Prior Bounds:
+</span> <span class="identifier">l</span> <span class="special">=</span> <span class="identifier">binomial_distribution</span><span class="special">&lt;&gt;::</span><span class="identifier">find_lower_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">trials</span><span class="special">,</span> <span class="identifier">successes</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]/</span><span class="number">2</span><span class="special">,</span>
+ <span class="identifier">binomial_distribution</span><span class="special">&lt;&gt;::</span><span class="identifier">jeffreys_prior_interval</span><span class="special">);</span>
+ <span class="identifier">u</span> <span class="special">=</span> <span class="identifier">binomial_distribution</span><span class="special">&lt;&gt;::</span><span class="identifier">find_upper_bound_on_p</span><span class="special">(</span>
+ <span class="identifier">trials</span><span class="special">,</span> <span class="identifier">successes</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]/</span><span class="number">2</span><span class="special">,</span>
+ <span class="identifier">binomial_distribution</span><span class="special">&lt;&gt;::</span><span class="identifier">jeffreys_prior_interval</span><span class="special">);</span>
+ <span class="comment">// Print Jeffreys Prior Limits:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">5</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">15</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">l</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">5</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">15</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">u</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ And that's all there is to it. Let's see some sample output for a 2
+ in 10 success ratio, first for 20 trials:
+ </p>
+<pre class="programlisting">___________________________________________
+2-Sided Confidence Limits For Success Ratio
+___________________________________________
+
+Number of Observations = 20
+Number of successes = 4
+Sample frequency of occurrence = 0.2
+
+
+_______________________________________________________________________
+Confidence Lower CP Upper CP Lower JP Upper JP
+ Value (%) Limit Limit Limit Limit
+_______________________________________________________________________
+ 50.000 0.12840 0.29588 0.14974 0.26916
+ 75.000 0.09775 0.34633 0.11653 0.31861
+ 90.000 0.07135 0.40103 0.08734 0.37274
+ 95.000 0.05733 0.43661 0.07152 0.40823
+ 99.000 0.03576 0.50661 0.04655 0.47859
+ 99.900 0.01905 0.58632 0.02634 0.55960
+ 99.990 0.01042 0.64997 0.01530 0.62495
+ 99.999 0.00577 0.70216 0.00901 0.67897
+</pre>
+<p>
+ As you can see, even at the 95% confidence level the bounds are really
+ quite wide (this example is chosen to be easily compared to the one
+ in the <a href="http://www.itl.nist.gov/div898/handbook/" target="_top">NIST/SEMATECH
+ e-Handbook of Statistical Methods.</a> here).
+ Note also that the Clopper-Pearson calculation method (CP above) produces
+ quite noticeably more pessimistic estimates than the Jeffreys Prior
+ method (JP above).
+ </p>
+<p>
+ Compare that with the program output for 2000 trials:
+ </p>
+<pre class="programlisting">___________________________________________
+2-Sided Confidence Limits For Success Ratio
+___________________________________________
+
+Number of Observations = 2000
+Number of successes = 400
+Sample frequency of occurrence = 0.2000000
+
+
+_______________________________________________________________________
+Confidence Lower CP Upper CP Lower JP Upper JP
+ Value (%) Limit Limit Limit Limit
+_______________________________________________________________________
+ 50.000 0.19382 0.20638 0.19406 0.20613
+ 75.000 0.18965 0.21072 0.18990 0.21047
+ 90.000 0.18537 0.21528 0.18561 0.21503
+ 95.000 0.18267 0.21821 0.18291 0.21796
+ 99.000 0.17745 0.22400 0.17769 0.22374
+ 99.900 0.17150 0.23079 0.17173 0.23053
+ 99.990 0.16658 0.23657 0.16681 0.23631
+ 99.999 0.16233 0.24169 0.16256 0.24143
+</pre>
+<p>
+ Now even when the confidence level is very high, the limits are really
+ quite close to the experimentally calculated value of 0.2. Furthermore
+ the difference between the two calculation methods is now really quite
+ small.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="binomial_quiz_example.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../binom_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="binom_size_eg.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/binom_eg/binom_size_eg.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/binom_eg/binom_size_eg.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,157 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Estimating Sample Sizes for a Binomial Distribution.</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../binom_eg.html" title="Binomial Distribution Examples">
+<link rel="prev" href="binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for a Binomial Distribution">
+<link rel="next" href="../neg_binom_eg.html" title="Negative Binomial Distribution Examples">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="binom_conf.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../binom_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../neg_binom_eg.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.binom_eg.binom_size_eg"></a><a href="binom_size_eg.html" title="Estimating Sample Sizes for a Binomial Distribution.">
+ Estimating Sample Sizes for a Binomial Distribution.</a>
+</h6></div></div></div>
+<p>
+ Imagine you have a critical component that you know will fail in 1
+ in N "uses" (for some suitable definition of "use").
+ You may want to schedule routine replacement of the component so that
+ its chance of failure between routine replacements is less than P%.
+ If the failures follow a binomial distribution (each time the component
+ is "used" it either fails or does not) then the static member
+ function <code class="computeroutput"><span class="identifier">binomial_distibution</span><span class="special">&lt;&gt;::</span><span class="identifier">find_maximum_number_of_trials</span></code>
+ can be used to estimate the maximum number of "uses" of that
+ component for some acceptable risk level <span class="emphasis"><em>alpha</em></span>.
+ </p>
+<p>
+ The example program binomial_sample_sizes.cpp
+ demonstrates its usage. It centres on a routine that prints out a table
+ of maximum sample sizes for various probability thresholds:
+ </p>
+<pre class="programlisting">
+<span class="keyword">void</span> <span class="identifier">find_max_sample_size</span><span class="special">(</span>
+ <span class="keyword">double</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// success ratio.
+</span> <span class="keyword">unsigned</span> <span class="identifier">successes</span><span class="special">)</span> <span class="comment">// Total number of observed successes permitted.
+</span><span class="special">{</span>
+</pre>
+<p>
+ The routine then declares a table of probability thresholds: these
+ are the maximum acceptable probability that <span class="emphasis"><em>successes</em></span>
+ or fewer events will be observed. In our example, <span class="emphasis"><em>successes</em></span>
+ will be always zero, since we want no component failures, but in other
+ situations non-zero values may well make sense.
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">alpha</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">0.5</span><span class="special">,</span> <span class="number">0.25</span><span class="special">,</span> <span class="number">0.1</span><span class="special">,</span> <span class="number">0.05</span><span class="special">,</span> <span class="number">0.01</span><span class="special">,</span> <span class="number">0.001</span><span class="special">,</span> <span class="number">0.0001</span><span class="special">,</span> <span class="number">0.00001</span> <span class="special">};</span>
+</pre>
+<p>
+ Much of the rest of the program is pretty-printing, the important part
+ is in the calculation of maximum number of permitted trials for each
+ value of alpha:
+ </p>
+<pre class="programlisting">
+<span class="keyword">for</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">)/</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">[</span><span class="number">0</span><span class="special">]);</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="comment">// Confidence value:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="number">100</span> <span class="special">*</span> <span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]);</span>
+ <span class="comment">// calculate trials:
+</span> <span class="keyword">double</span> <span class="identifier">t</span> <span class="special">=</span> <span class="identifier">binomial</span><span class="special">::</span><span class="identifier">find_maximum_number_of_trials</span><span class="special">(</span>
+ <span class="identifier">successes</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]);</span>
+ <span class="identifier">t</span> <span class="special">=</span> <span class="identifier">floor</span><span class="special">(</span><span class="identifier">t</span><span class="special">);</span>
+ <span class="comment">// Print Trials:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">5</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">15</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">t</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ Note that since we're calculating the maximum number of trials permitted,
+ we'll err on the safe side and take the floor of the result. Had we
+ been calculating the <span class="emphasis"><em>minimum</em></span> number of trials
+ required to observe a certain number of <span class="emphasis"><em>successes</em></span>
+ using <code class="computeroutput"><span class="identifier">find_minimum_number_of_trials</span></code>
+ we would have taken the ceiling instead.
+ </p>
+<p>
+ We'll finish off by looking at some sample output, firstly for a 1
+ in 1000 chance of component failure with each use:
+ </p>
+<pre class="programlisting">________________________
+Maximum Number of Trials
+________________________
+
+Success ratio = 0.001
+Maximum Number of "successes" permitted = 0
+
+
+____________________________
+Confidence Max Number
+ Value (%) Of Trials
+____________________________
+ 50.000 692
+ 75.000 287
+ 90.000 105
+ 95.000 51
+ 99.000 10
+ 99.900 0
+ 99.990 0
+ 99.999 0
+</pre>
+<p>
+ So 51 "uses" of the component would yield a 95% chance that
+ no component failures would be observed.
+ </p>
+<p>
+ Compare that with a 1 in 1 million chance of component failure:
+ </p>
+<pre class="programlisting">________________________
+Maximum Number of Trials
+________________________
+
+Success ratio = 0.0000010
+Maximum Number of "successes" permitted = 0
+
+
+____________________________
+Confidence Max Number
+ Value (%) Of Trials
+____________________________
+ 50.000 693146
+ 75.000 287681
+ 90.000 105360
+ 95.000 51293
+ 99.000 10050
+ 99.900 1000
+ 99.990 100
+ 99.999 10
+</pre>
+<p>
+ In this case, even 1000 uses of the component would still yield a less
+ than 1 in 1000 chance of observing a component failure (i.e. a 99.9%
+ chance of no failure).
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="binom_conf.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../binom_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../neg_binom_eg.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/binom_eg/binomial_coinflip_example.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/binom_eg/binomial_coinflip_example.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,430 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Binomial Coin-Flipping Example</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../binom_eg.html" title="Binomial Distribution Examples">
+<link rel="prev" href="../binom_eg.html" title="Binomial Distribution Examples">
+<link rel="next" href="binomial_quiz_example.html" title="Binomial Quiz Example">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../binom_eg.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../binom_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="binomial_quiz_example.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.binom_eg.binomial_coinflip_example"></a><a href="binomial_coinflip_example.html" title="Binomial Coin-Flipping Example">
+ Binomial Coin-Flipping Example</a>
+</h6></div></div></div>
+<p>
+ </p>
+<p>
+ An example of a <a href="http://en.wikipedia.org/wiki/Bernoulli_process" target="_top">Bernoulli
+ process</a> is coin flipping. A variable in such a sequence may
+ be called a Bernoulli variable.
+ </p>
+<p>
+ </p>
+<p>
+ This example shows using the Binomial distribution to predict the
+ probability of heads and tails when throwing a coin.
+ </p>
+<p>
+ </p>
+<p>
+ The number of correct answers (say heads), X, is distributed as a
+ binomial random variable with binomial distribution parameters number
+ of trials (flips) n = 10 and probability (success_fraction) of getting
+ a head p = 0.5 (a 'fair' coin).
+ </p>
+<p>
+ </p>
+<p>
+ (Our coin is assumed fair, but we could easily change the success_fraction
+ parameter p from 0.5 to some other value to simulate an unfair coin,
+ say 0.6 for one with chewing gum on the tail, so it is more likely
+ to fall tails down and heads up).
+ </p>
+<p>
+ </p>
+<p>
+ First we need some includes and using statements to be able to use
+ the binomial distribution, some std input and output, and get started:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">binomial</span><span class="special">;</span>
+
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">left</span><span class="special">;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iomanip</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">;</span>
+
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Using Binomial distribution to predict how many heads and tails."</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+ <span class="keyword">try</span>
+ <span class="special">{</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ See note with the catch block
+ about why a try and catch block is always a good idea.
+ </p>
+<p>
+ </p>
+<p>
+ First, construct a binomial distribution with parameters success_fraction
+ 1/2, and how many flips.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">const</span> <span class="keyword">double</span> <span class="identifier">success_fraction</span> <span class="special">=</span> <span class="number">0.5</span><span class="special">;</span> <span class="comment">// = 50% = 1/2 for a 'fair' coin.
+</span><span class="keyword">int</span> <span class="identifier">flips</span> <span class="special">=</span> <span class="number">10</span><span class="special">;</span>
+<span class="identifier">binomial</span> <span class="identifier">flip</span><span class="special">(</span><span class="identifier">flips</span><span class="special">,</span> <span class="identifier">success_fraction</span><span class="special">);</span>
+
+<span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="number">4</span><span class="special">);</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Then some examples of using Binomial moments (and echoing the parameters).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"From "</span> <span class="special">&lt;&lt;</span> <span class="identifier">flips</span> <span class="special">&lt;&lt;</span> <span class="string">" one can expect to get on average "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">mean</span><span class="special">(</span><span class="identifier">flip</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" heads (or tails)."</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Mode is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">mode</span><span class="special">(</span><span class="identifier">flip</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Standard deviation is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">standard_deviation</span><span class="special">(</span><span class="identifier">flip</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"So about 2/3 will lie within 1 standard deviation and get between "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">ceil</span><span class="special">(</span><span class="identifier">mean</span><span class="special">(</span><span class="identifier">flip</span><span class="special">)</span> <span class="special">-</span> <span class="identifier">standard_deviation</span><span class="special">(</span><span class="identifier">flip</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="string">" and "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">floor</span><span class="special">(</span><span class="identifier">mean</span><span class="special">(</span><span class="identifier">flip</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">standard_deviation</span><span class="special">(</span><span class="identifier">flip</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="string">" correct."</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Skewness is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">skewness</span><span class="special">(</span><span class="identifier">flip</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// Skewness of binomial distributions is only zero (symmetrical)
+</span><span class="comment">// if success_fraction is exactly one half,
+</span><span class="comment">// for example, when flipping 'fair' coins.
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Skewness if success_fraction is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">flip</span><span class="special">.</span><span class="identifier">success_fraction</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">skewness</span><span class="special">(</span><span class="identifier">flip</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// Expect zero for a 'fair' coin.</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Now we show a variety of predictions on the probability of heads:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"For "</span> <span class="special">&lt;&lt;</span> <span class="identifier">flip</span><span class="special">.</span><span class="identifier">trials</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">" coin flips: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting no heads is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">0</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting at least one head is "</span> <span class="special">&lt;&lt;</span> <span class="number">1.</span> <span class="special">-</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">0</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ When we want to calculate the probability for a range or values we
+ can sum the PDF's:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting 0 or 1 heads is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">0</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">1</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// sum of exactly == probabilities</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Or we can use the cdf.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting 0 or 1 (&lt;= 1) heads is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">1</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting 9 or 10 heads is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">9</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Note that using
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting 9 or 10 heads is "</span> <span class="special">&lt;&lt;</span> <span class="number">1.</span> <span class="special">-</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">8</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ is less accurate than using the complement
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting 9 or 10 heads is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">8</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Since the subtraction may involve <a href="http://docs.sun.com/source/806-3568/ncg_goldberg.html" target="_top">cancellation
+ error</a>, where as <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">8</span><span class="special">))</span></code> does not use such a subtraction
+ internally, and so does not exhibit the problem.
+ </p>
+<p>
+ </p>
+<p>
+ To get the probability for a range of heads, we can either add the
+ pdfs for each number of heads
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of between 4 and 6 heads (4 or 5 or 6) is "</span>
+ <span class="comment">// P(X == 4) + P(X == 5) + P(X == 6)
+</span> <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">4</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">5</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">6</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ But this is probably less efficient than using the cdf
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of between 4 and 6 heads (4 or 5 or 6) is "</span>
+ <span class="comment">// P(X &lt;= 6) - P(X &lt;= 3) == P(X &lt; 4)
+</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">6</span><span class="special">)</span> <span class="special">-</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Certainly for a bigger range like, 3 to 7
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of between 3 and 7 heads (3, 4, 5, 6 or 7) is "</span>
+ <span class="comment">// P(X &lt;= 7) - P(X &lt;= 2) == P(X &lt; 3)
+</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">7</span><span class="special">)</span> <span class="special">-</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="number">2</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Finally, print two tables of probability for the <span class="emphasis"><em>exactly</em></span>
+ and <span class="emphasis"><em>at least</em></span> a number of heads.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="comment">// Print a table of probability for the exactly a number of heads.
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting exactly (==) heads"</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">successes</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">successes</span> <span class="special">&lt;=</span> <span class="identifier">flips</span><span class="special">;</span> <span class="identifier">successes</span><span class="special">++)</span>
+<span class="special">{</span> <span class="comment">// Say success means getting a head (or equally success means getting a tail).
+</span> <span class="keyword">double</span> <span class="identifier">probability</span> <span class="special">=</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="identifier">successes</span><span class="special">);</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">2</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">successes</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">10</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">probability</span> <span class="special">&lt;&lt;</span> <span class="string">" or 1 in "</span> <span class="special">&lt;&lt;</span> <span class="number">1.</span> <span class="special">/</span> <span class="identifier">probability</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", or "</span> <span class="special">&lt;&lt;</span> <span class="identifier">probability</span> <span class="special">*</span> <span class="number">100.</span> <span class="special">&lt;&lt;</span> <span class="string">"%"</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span> <span class="comment">// for i
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+
+<span class="comment">// Tabulate the probability of getting between zero heads and 0 upto 10 heads.
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting upto (&lt;=) heads"</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">successes</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">successes</span> <span class="special">&lt;=</span> <span class="identifier">flips</span><span class="special">;</span> <span class="identifier">successes</span><span class="special">++)</span>
+<span class="special">{</span> <span class="comment">// Say success means getting a head
+</span> <span class="comment">// (equally success could mean getting a tail).
+</span> <span class="keyword">double</span> <span class="identifier">probability</span> <span class="special">=</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">flip</span><span class="special">,</span> <span class="identifier">successes</span><span class="special">);</span> <span class="comment">// P(X &lt;= heads)
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">2</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">successes</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">probability</span> <span class="special">&lt;&lt;</span> <span class="string">" or 1 in "</span> <span class="special">&lt;&lt;</span> <span class="number">1.</span> <span class="special">/</span> <span class="identifier">probability</span> <span class="special">&lt;&lt;</span> <span class="string">", or "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">probability</span> <span class="special">*</span> <span class="number">100.</span> <span class="special">&lt;&lt;</span> <span class="string">"%"</span><span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span> <span class="comment">// for i</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ The last (0 to 10 heads) must, of course, be 100% probability.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="special">}</span>
+<span class="keyword">catch</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span><span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="comment">//</span></pre>
+<p>
+ </p>
+<p>
+ <a name="coinflip_eg_catch"></a>
+ </p>
+<p>
+ It is always essential to include try &amp; catch blocks because
+ default policies are to throw exceptions on arguments that are out
+ of domain or cause errors like numeric-overflow.
+ </p>
+<p>
+ </p>
+<p>
+ Lacking try &amp; catch blocks, the program will abort, whereas the
+ message below from the thrown exception will give some helpful clues
+ as to the cause of the problem.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span>
+ <span class="string">"\n"</span><span class="string">"Message from thrown exception was:\n "</span> <span class="special">&lt;&lt;</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ See binomial_coinflip_example.cpp
+ for full source code, the program output looks like this:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Using Binomial distribution to predict how many heads and tails.
+From 10 one can expect to get on average 5 heads (or tails).
+Mode is 5
+Standard deviation is 1.581
+So about 2/3 will lie within 1 standard deviation and get between 4 and 6 correct.
+Skewness is 0
+Skewness if success_fraction is 0.5 is 0
+
+For 10 coin flips:
+Probability of getting no heads is 0.0009766
+Probability of getting at least one head is 0.999
+Probability of getting 0 or 1 heads is 0.01074
+Probability of getting 0 or 1 (&lt;= 1) heads is 0.01074
+Probability of getting 9 or 10 heads is 0.01074
+Probability of getting 9 or 10 heads is 0.01074
+Probability of getting 9 or 10 heads is 0.01074
+Probability of between 4 and 6 heads (4 or 5 or 6) is 0.6562
+Probability of between 4 and 6 heads (4 or 5 or 6) is 0.6563
+Probability of between 3 and 7 heads (3, 4, 5, 6 or 7) is 0.8906
+
+Probability of getting exactly (<code class="literal">=) heads
+0 0.0009766 or 1 in 1024, or 0.09766%
+1 0.009766 or 1 in 102.4, or 0.9766%
+2 0.04395 or 1 in 22.76, or 4.395%
+3 0.1172 or 1 in 8.533, or 11.72%
+4 0.2051 or 1 in 4.876, or 20.51%
+5 0.2461 or 1 in 4.063, or 24.61%
+6 0.2051 or 1 in 4.876, or 20.51%
+7 0.1172 or 1 in 8.533, or 11.72%
+8 0.04395 or 1 in 22.76, or 4.395%
+9 0.009766 or 1 in 102.4, or 0.9766%
+10 0.0009766 or 1 in 1024, or 0.09766%
+
+Probability of getting upto (&lt;</code>) heads
+0 0.0009766 or 1 in 1024, or 0.09766%
+1 0.01074 or 1 in 93.09, or 1.074%
+2 0.05469 or 1 in 18.29, or 5.469%
+3 0.1719 or 1 in 5.818, or 17.19%
+4 0.377 or 1 in 2.653, or 37.7%
+5 0.623 or 1 in 1.605, or 62.3%
+6 0.8281 or 1 in 1.208, or 82.81%
+7 0.9453 or 1 in 1.058, or 94.53%
+8 0.9893 or 1 in 1.011, or 98.93%
+9 0.999 or 1 in 1.001, or 99.9%
+10 1 or 1 in 1, or 100%
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../binom_eg.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../binom_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="binomial_quiz_example.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/binom_eg/binomial_quiz_example.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/binom_eg/binomial_quiz_example.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,787 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Binomial Quiz Example</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../binom_eg.html" title="Binomial Distribution Examples">
+<link rel="prev" href="binomial_coinflip_example.html" title="Binomial Coin-Flipping Example">
+<link rel="next" href="binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for a Binomial Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="binomial_coinflip_example.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../binom_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="binom_conf.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.binom_eg.binomial_quiz_example"></a><a href="binomial_quiz_example.html" title="Binomial Quiz Example">
+ Binomial Quiz Example</a>
+</h6></div></div></div>
+<p>
+ </p>
+<p>
+ A multiple choice test has four possible answers to each of 16 questions.
+ A student guesses the answer to each question, so the probability
+ of getting a correct answer on any given question is one in four,
+ a quarter, 1/4, 25% or fraction 0.25. The conditions of the binomial
+ experiment are assumed to be met: n = 16 questions constitute the
+ trials; each question results in one of two possible outcomes (correct
+ or incorrect); the probability of being correct is 0.25 and is constant
+ if no knowledge about the subject is assumed; the questions are answered
+ independently if the student's answer to a question in no way influences
+ his/her answer to another question.
+ </p>
+<p>
+ </p>
+<p>
+ First, we need to be able to use the binomial distribution constructor
+ (and some std input/output, of course).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">binomial</span><span class="special">;</span>
+
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ios</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">flush</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">left</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">fixed</span><span class="special">;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iomanip</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ The number of correct answers, X, is distributed as a binomial random
+ variable with binomial distribution parameters: questions n = 16
+ and success fraction probability p = 0.25. So we construct a binomial
+ distribution:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">int</span> <span class="identifier">questions</span> <span class="special">=</span> <span class="number">16</span><span class="special">;</span> <span class="comment">// All the questions in the quiz.
+</span><span class="keyword">int</span> <span class="identifier">answers</span> <span class="special">=</span> <span class="number">4</span><span class="special">;</span> <span class="comment">// Possible answers to each question.
+</span><span class="keyword">double</span> <span class="identifier">success_fraction</span> <span class="special">=</span> <span class="special">(</span><span class="keyword">double</span><span class="special">)</span><span class="identifier">answers</span> <span class="special">/</span> <span class="special">(</span><span class="keyword">double</span><span class="special">)</span><span class="identifier">questions</span><span class="special">;</span> <span class="comment">// If a random guess.
+</span><span class="comment">// Caution: = answers / questions would be zero (because they are integers)!
+</span><span class="identifier">binomial</span> <span class="identifier">quiz</span><span class="special">(</span><span class="identifier">questions</span><span class="special">,</span> <span class="identifier">success_fraction</span><span class="special">);</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ and display the distribution parameters we used thus:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"In a quiz with "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quiz</span><span class="special">.</span><span class="identifier">trials</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" questions and with a probability of guessing right of "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quiz</span><span class="special">.</span><span class="identifier">success_fraction</span><span class="special">()</span> <span class="special">*</span> <span class="number">100</span> <span class="special">&lt;&lt;</span> <span class="string">" %"</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" or 1 in "</span> <span class="special">&lt;&lt;</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="number">1.</span> <span class="special">/</span> <span class="identifier">quiz</span><span class="special">.</span><span class="identifier">success_fraction</span><span class="special">())</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Show a few probabilities of just guessing:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting none right is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 0.010023
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting exactly one right is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">1</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting exactly two right is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">2</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="keyword">int</span> <span class="identifier">pass_score</span> <span class="special">=</span> <span class="number">11</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting exactly "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pass_score</span> <span class="special">&lt;&lt;</span> <span class="string">" answers right by chance is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">questions</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability of getting none right is 0.0100226
+Probability of getting exactly one right is 0.0534538
+Probability of getting exactly two right is 0.133635
+Probability of getting exactly 11 answers right by chance is 2.32831e-010
+</pre>
+<p>
+ </p>
+<p>
+ These don't give any encouragement to guessers!
+ </p>
+<p>
+ </p>
+<p>
+ We can tabulate the 'getting exactly right' ( == ) probabilities
+ thus:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span> <span class="string">"Guessed Probability"</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">successes</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">successes</span> <span class="special">&lt;=</span> <span class="identifier">questions</span><span class="special">;</span> <span class="identifier">successes</span><span class="special">++)</span>
+<span class="special">{</span>
+ <span class="keyword">double</span> <span class="identifier">probability</span> <span class="special">=</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">successes</span><span class="special">);</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">2</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">successes</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span> <span class="special">&lt;&lt;</span> <span class="identifier">probability</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Guessed Probability
+ 0 0.0100226
+ 1 0.0534538
+ 2 0.133635
+ 3 0.207876
+ 4 0.225199
+ 5 0.180159
+ 6 0.110097
+ 7 0.0524273
+ 8 0.0196602
+ 9 0.00582526
+10 0.00135923
+11 0.000247132
+12 3.43239e-005
+13 3.5204e-006
+14 2.51457e-007
+15 1.11759e-008
+16 2.32831e-010
+</pre>
+<p>
+ </p>
+<p>
+ Then we can add the probabilities of some 'exactly right' like this:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting none or one right is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">1</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability of getting none or one right is 0.0634764
+</pre>
+<p>
+ </p>
+<p>
+ But if more than a couple of scores are involved, it is more convenient
+ (and may be more accurate) to use the Cumulative Distribution Function
+ (cdf) instead:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting none or one right is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">1</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability of getting none or one right is 0.0634764
+</pre>
+<p>
+ </p>
+<p>
+ Since the cdf is inclusive, we can get the probability of getting
+ up to 10 right ( &lt;= )
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting &lt;= 10 right (to fail) is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability of getting &lt;= 10 right (to fail) is 0.999715
+</pre>
+<p>
+ </p>
+<p>
+ To get the probability of getting 11 or more right (to pass), it
+ is tempting to use
+</p>
+<pre class="programlisting">
+<span class="number">1</span> <span class="special">-</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">10</span><span class="special">)</span></pre>
+<p>
+ to get the probability of &gt; 10
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting &gt; 10 right (to pass) is "</span> <span class="special">&lt;&lt;</span> <span class="number">1</span> <span class="special">-</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability of getting &gt; 10 right (to pass) is 0.000285239
+</pre>
+<p>
+ </p>
+<p>
+ But this should be resisted in favor of using the complement function.
+ Why complements?
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting &gt; 10 right (to pass) is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">10</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability of getting &gt; 10 right (to pass) is 0.000285239
+</pre>
+<p>
+ </p>
+<p>
+ And we can check that these two, &lt;= 10 and &gt; 10, add up to
+ unity.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">BOOST_ASSERT</span><span class="special">((</span><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">10</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">10</span><span class="special">)))</span> <span class="special">==</span> <span class="number">1.</span><span class="special">);</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ If we want a &lt; rather than a &lt;= test, because the CDF is inclusive,
+ we must subtract one from the score.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting less than "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pass_score</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" (&lt; "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pass_score</span> <span class="special">&lt;&lt;</span> <span class="string">") answers right by guessing is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">pass_score</span> <span class="special">-</span><span class="number">1</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability of getting less than 11 (&lt; 11) answers right by guessing is 0.999715
+</pre>
+<p>
+ </p>
+<p>
+ and similarly to get a &gt;= rather than a &gt; test we also need
+ to subtract one from the score (and can again check the sum is unity).
+ This is because if the cdf is <span class="emphasis"><em>inclusive</em></span>, then
+ its complement must be <span class="emphasis"><em>exclusive</em></span> otherwise there
+ would be one possible outcome counted twice!
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting at least "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pass_score</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"(&gt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pass_score</span> <span class="special">&lt;&lt;</span> <span class="string">") answers right by guessing is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">pass_score</span><span class="special">-</span><span class="number">1</span><span class="special">))</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", only 1 in "</span> <span class="special">&lt;&lt;</span> <span class="number">1</span><span class="special">/</span><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">pass_score</span><span class="special">-</span><span class="number">1</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+
+<span class="identifier">BOOST_ASSERT</span><span class="special">((</span><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">pass_score</span> <span class="special">-</span><span class="number">1</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">pass_score</span><span class="special">-</span><span class="number">1</span><span class="special">)))</span> <span class="special">==</span> <span class="number">1</span><span class="special">);</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability of getting at least 11 (&gt;= 11) answers right by guessing is 0.000285239, only 1 in 3505.83
+</pre>
+<p>
+ </p>
+<p>
+ Finally we can tabulate some probabilities:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span> <span class="string">"At most (&lt;=)"</span><span class="string">"\n"</span><span class="string">"Guessed OK Probability"</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">score</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">score</span> <span class="special">&lt;=</span> <span class="identifier">questions</span><span class="special">;</span> <span class="identifier">score</span><span class="special">++)</span>
+<span class="special">{</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">2</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">score</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">10</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">score</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">At most (&lt;=)
+Guessed OK Probability
+ 0 0.01002259576
+ 1 0.0634764398
+ 2 0.1971110499
+ 3 0.4049871101
+ 4 0.6301861752
+ 5 0.8103454274
+ 6 0.9204427481
+ 7 0.9728700437
+ 8 0.9925302796
+ 9 0.9983555346
+10 0.9997147608
+11 0.9999618928
+12 0.9999962167
+13 0.9999997371
+14 0.9999999886
+15 0.9999999998
+16 1
+</pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span> <span class="string">"At least (&gt;)"</span><span class="string">"\n"</span><span class="string">"Guessed OK Probability"</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">score</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">score</span> <span class="special">&lt;=</span> <span class="identifier">questions</span><span class="special">;</span> <span class="identifier">score</span><span class="special">++)</span>
+<span class="special">{</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">2</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">score</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">10</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">score</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">At least (&gt;)
+Guessed OK Probability
+ 0 0.9899774042
+ 1 0.9365235602
+ 2 0.8028889501
+ 3 0.5950128899
+ 4 0.3698138248
+ 5 0.1896545726
+ 6 0.07955725188
+ 7 0.02712995629
+ 8 0.00746972044
+ 9 0.001644465374
+10 0.0002852391917
+11 3.810715862e-005
+12 3.783265129e-006
+13 2.628657967e-007
+14 1.140870154e-008
+15 2.328306437e-010
+16 0
+</pre>
+<p>
+ </p>
+<p>
+ We now consider the probabilities of <span class="bold"><strong>ranges</strong></span>
+ of correct guesses.
+ </p>
+<p>
+ </p>
+<p>
+ First, calculate the probability of getting a range of guesses right,
+ by adding the exact probabilities of each from low ... high.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">int</span> <span class="identifier">low</span> <span class="special">=</span> <span class="number">3</span><span class="special">;</span> <span class="comment">// Getting at least 3 right.
+</span><span class="keyword">int</span> <span class="identifier">high</span> <span class="special">=</span> <span class="number">5</span><span class="special">;</span> <span class="comment">// Getting as most 5 right.
+</span><span class="keyword">double</span> <span class="identifier">sum</span> <span class="special">=</span> <span class="number">0.</span><span class="special">;</span>
+<span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="identifier">low</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;=</span> <span class="identifier">high</span><span class="special">;</span> <span class="identifier">i</span><span class="special">++)</span>
+<span class="special">{</span>
+ <span class="identifier">sum</span> <span class="special">+=</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">i</span><span class="special">);</span>
+<span class="special">}</span>
+<span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="number">4</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting between "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">low</span> <span class="special">&lt;&lt;</span> <span class="string">" and "</span> <span class="special">&lt;&lt;</span> <span class="identifier">high</span> <span class="special">&lt;&lt;</span> <span class="string">" answers right by guessing is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">sum</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 0.61323</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability of getting between 3 and 5 answers right by guessing is 0.6132
+</pre>
+<p>
+ </p>
+<p>
+ Or, usually better, we can use the difference of cdfs instead:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting between "</span> <span class="special">&lt;&lt;</span> <span class="identifier">low</span> <span class="special">&lt;&lt;</span> <span class="string">" and "</span> <span class="special">&lt;&lt;</span> <span class="identifier">high</span> <span class="special">&lt;&lt;</span> <span class="string">" answers right by guessing is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">high</span><span class="special">)</span> <span class="special">-</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">low</span> <span class="special">-</span> <span class="number">1</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 0.61323</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability of getting between 3 and 5 answers right by guessing is 0.6132
+</pre>
+<p>
+ </p>
+<p>
+ And we can also try a few more combinations of high and low choices:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">low</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> <span class="identifier">high</span> <span class="special">=</span> <span class="number">6</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting between "</span> <span class="special">&lt;&lt;</span> <span class="identifier">low</span> <span class="special">&lt;&lt;</span> <span class="string">" and "</span> <span class="special">&lt;&lt;</span> <span class="identifier">high</span> <span class="special">&lt;&lt;</span> <span class="string">" answers right by guessing is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">high</span><span class="special">)</span> <span class="special">-</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">low</span> <span class="special">-</span> <span class="number">1</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 1 and 6 P= 0.91042
+</span><span class="identifier">low</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> <span class="identifier">high</span> <span class="special">=</span> <span class="number">8</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting between "</span> <span class="special">&lt;&lt;</span> <span class="identifier">low</span> <span class="special">&lt;&lt;</span> <span class="string">" and "</span> <span class="special">&lt;&lt;</span> <span class="identifier">high</span> <span class="special">&lt;&lt;</span> <span class="string">" answers right by guessing is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">high</span><span class="special">)</span> <span class="special">-</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">low</span> <span class="special">-</span> <span class="number">1</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 1 &lt;= x 8 P = 0.9825
+</span><span class="identifier">low</span> <span class="special">=</span> <span class="number">4</span><span class="special">;</span> <span class="identifier">high</span> <span class="special">=</span> <span class="number">4</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of getting between "</span> <span class="special">&lt;&lt;</span> <span class="identifier">low</span> <span class="special">&lt;&lt;</span> <span class="string">" and "</span> <span class="special">&lt;&lt;</span> <span class="identifier">high</span> <span class="special">&lt;&lt;</span> <span class="string">" answers right by guessing is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">high</span><span class="special">)</span> <span class="special">-</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="identifier">low</span> <span class="special">-</span> <span class="number">1</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 4 &lt;= x 4 P = 0.22520</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability of getting between 1 and 6 answers right by guessing is 0.9104
+Probability of getting between 1 and 8 answers right by guessing is 0.9825
+Probability of getting between 4 and 4 answers right by guessing is 0.2252
+</pre>
+<p>
+ <a name="math_toolkit.dist.stat_tut.weg.binom_eg.binomial_quiz_example.using_binomial_distribution_moments"></a>
+ </p>
+<h5>
+<a name="id527185"></a>
+ <a href="binomial_quiz_example.html#math_toolkit.dist.stat_tut.weg.binom_eg.binomial_quiz_example.using_binomial_distribution_moments">Using
+ Binomial distribution moments</a>
+ </h5>
+<p>
+ </p>
+<p>
+ Using moments of the distribution, we can say more about the spread
+ of results from guessing.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"By guessing, on average, one can expect to get "</span> <span class="special">&lt;&lt;</span> <span class="identifier">mean</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" correct answers."</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Standard deviation is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">standard_deviation</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"So about 2/3 will lie within 1 standard deviation and get between "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">ceil</span><span class="special">(</span><span class="identifier">mean</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">)</span> <span class="special">-</span> <span class="identifier">standard_deviation</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="string">" and "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">floor</span><span class="special">(</span><span class="identifier">mean</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">standard_deviation</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="string">" correct."</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Mode (the most frequent) is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">mode</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Skewness is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">skewness</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">By guessing, on average, one can expect to get 4 correct answers.
+Standard deviation is 1.732
+So about 2/3 will lie within 1 standard deviation and get between 3 and 5 correct.
+Mode (the most frequent) is 4
+Skewness is 0.2887
+</pre>
+<p>
+ <a name="math_toolkit.dist.stat_tut.weg.binom_eg.binomial_quiz_example.quantiles"></a>
+ </p>
+<h5>
+<a name="id527704"></a>
+ Quantiles
+ </h5>
+<p>
+ </p>
+<p>
+ The quantiles (percentiles or percentage points) for a few probability
+ levels:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Quartiles "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0.25</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" to "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0.25</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// Quartiles
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"1 standard deviation "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0.33</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" to "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0.67</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 1 sd
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Deciles "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0.1</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" to "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0.1</span><span class="special">))&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// Deciles
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"5 to 95% "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0.05</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" to "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0.05</span><span class="special">))&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 5 to 95%
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"2.5 to 97.5% "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0.025</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" to "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0.025</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 2.5 to 97.5%
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"2 to 98% "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0.02</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" to "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0.02</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 2 to 98%
+</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"If guessing then percentiles 1 to 99% will get "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0.01</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" to "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0.01</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="string">" right."</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Notice that these output integral values because the default policy
+ is <code class="computeroutput"><span class="identifier">integer_round_outwards</span></code>.
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Quartiles 2 to 5
+1 standard deviation 2 to 5
+Deciles 1 to 6
+5 to 95% 0 to 7
+2.5 to 97.5% 0 to 8
+2 to 98% 0 to 8
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Quantiles values are controlled by the <a href="../../../../policy/pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">discrete
+ quantile policy</a> chosen. The default is <code class="computeroutput"><span class="identifier">integer_round_outwards</span></code>,
+ so the lower quantile is rounded down, and the upper quantile is
+ rounded up.
+ </p>
+<p>
+ </p>
+<p>
+ But we might believe that the real values tell us a little more -
+ see <a href="../../../../policy/pol_tutorial/understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">Understanding
+ Discrete Quantile Policy</a>.
+ </p>
+<p>
+ </p>
+<p>
+ We could control the policy for <span class="bold"><strong>all</strong></span>
+ distributions by
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DISCRETE_QUANTILE_POLICY</span> <span class="identifier">real</span>
+
+<span class="identifier">at</span> <span class="identifier">the</span> <span class="identifier">head</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">program</span> <span class="identifier">would</span> <span class="identifier">make</span> <span class="keyword">this</span> <span class="identifier">policy</span> <span class="identifier">apply</span>
+</pre>
+<p>
+ </p>
+<p>
+ #define BOOST_MATH_DISCRETE_QUANTILE_POLICY real
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">at</span> <span class="identifier">the</span> <span class="identifier">head</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">program</span> <span class="identifier">would</span> <span class="identifier">make</span> <span class="keyword">this</span> <span class="identifier">policy</span> <span class="identifier">apply</span>
+</pre>
+<p>
+ </p>
+<p>
+ at the head of the program would make this policy apply to this
+ <span class="bold"><strong>one, and only</strong></span>, translation unit.
+ </p>
+<p>
+ </p>
+<p>
+ Or we can now create a (typedef for) policy that has discrete quantiles
+ real (here avoiding any 'using namespaces ...' statements):
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">discrete_quantile</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">real</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">integer_round_outwards</span><span class="special">;</span> <span class="comment">// Default.
+</span><span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">discrete_quantile</span><span class="special">&lt;</span><span class="identifier">real</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">real_quantile_policy</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Add a custom binomial distribution called
+</p>
+<pre class="programlisting">
+<span class="identifier">real_quantile_binomial</span></pre>
+<p>
+ that uses
+</p>
+<pre class="programlisting">
+<span class="identifier">real_quantile_policy</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">binomial_distribution</span><span class="special">;</span>
+<span class="keyword">typedef</span> <span class="identifier">binomial_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">real_quantile_policy</span><span class="special">&gt;</span> <span class="identifier">real_quantile_binomial</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Construct an object of this custom distribution:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">real_quantile_binomial</span> <span class="identifier">quiz_real</span><span class="special">(</span><span class="identifier">questions</span><span class="special">,</span> <span class="identifier">success_fraction</span><span class="special">);</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ And use this to show some quantiles - that now have real rather than
+ integer values.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Quartiles "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">quiz</span><span class="special">,</span> <span class="number">0.25</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" to "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz_real</span><span class="special">,</span> <span class="number">0.25</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// Quartiles 2 to 4.6212
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"1 standard deviation "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">quiz_real</span><span class="special">,</span> <span class="number">0.33</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" to "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">quiz_real</span><span class="special">,</span> <span class="number">0.67</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 1 sd 2.6654 4.194
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Deciles "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">quiz_real</span><span class="special">,</span> <span class="number">0.1</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" to "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz_real</span><span class="special">,</span> <span class="number">0.1</span><span class="special">))&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// Deciles 1.3487 5.7583
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"5 to 95% "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">quiz_real</span><span class="special">,</span> <span class="number">0.05</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" to "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz_real</span><span class="special">,</span> <span class="number">0.05</span><span class="special">))&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 5 to 95% 0.83739 6.4559
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"2.5 to 97.5% "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">quiz_real</span><span class="special">,</span> <span class="number">0.025</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" to "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz_real</span><span class="special">,</span> <span class="number">0.025</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 2.5 to 97.5% 0.42806 7.0688
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"2 to 98% "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">quiz_real</span><span class="special">,</span> <span class="number">0.02</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" to "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz_real</span><span class="special">,</span> <span class="number">0.02</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 2 to 98% 0.31311 7.7880
+</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"If guessing, then percentiles 1 to 99% will get "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">quiz_real</span><span class="special">,</span> <span class="number">0.01</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" to "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">quiz_real</span><span class="special">,</span> <span class="number">0.01</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="string">" right."</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Real Quantiles
+Quartiles 2 to 4.621
+1 standard deviation 2.665 to 4.194
+Deciles 1.349 to 5.758
+5 to 95% 0.8374 to 6.456
+2.5 to 97.5% 0.4281 to 7.069
+2 to 98% 0.3131 to 7.252
+If guessing then percentiles 1 to 99% will get 0 to 7.788 right.
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ See binomial_quiz_example.cpp
+ for full source code and output.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="binomial_coinflip_example.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../binom_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="binom_conf.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/cs_eg.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/cs_eg.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,50 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Chi Squared Distribution Examples</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../weg.html" title="Worked Examples">
+<link rel="prev" href="st_eg/paired_st.html" title="Comparing two paired samples with the Student's t distribution">
+<link rel="next" href="cs_eg/chi_sq_intervals.html" title="Confidence Intervals on the Standard Deviation">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="st_eg/paired_st.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="cs_eg/chi_sq_intervals.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.cs_eg"></a><a href="cs_eg.html" title="Chi Squared Distribution Examples"> Chi Squared
+ Distribution Examples</a>
+</h5></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="cs_eg/chi_sq_intervals.html">
+ Confidence Intervals on the Standard Deviation</a></span></dt>
+<dt><span class="section"><a href="cs_eg/chi_sq_test.html">
+ Chi-Square Test for the Standard Deviation</a></span></dt>
+<dt><span class="section"><a href="cs_eg/chi_sq_size.html">
+ Estimating the Required Sample Sizes for a Chi-Square Test for the Standard
+ Deviation</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="st_eg/paired_st.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="cs_eg/chi_sq_intervals.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/cs_eg/chi_sq_intervals.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/cs_eg/chi_sq_intervals.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,237 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Confidence Intervals on the Standard Deviation</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../cs_eg.html" title="Chi Squared Distribution Examples">
+<link rel="prev" href="../cs_eg.html" title="Chi Squared Distribution Examples">
+<link rel="next" href="chi_sq_test.html" title="Chi-Square Test for the Standard Deviation">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../cs_eg.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cs_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="chi_sq_test.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.cs_eg.chi_sq_intervals"></a><a href="chi_sq_intervals.html" title="Confidence Intervals on the Standard Deviation">
+ Confidence Intervals on the Standard Deviation</a>
+</h6></div></div></div>
+<p>
+ Once you have calculated the standard deviation for your data, a legitimate
+ question to ask is "How reliable is the calculated standard deviation?".
+ For this situation the Chi Squared distribution can be used to calculate
+ confidence intervals for the standard deviation.
+ </p>
+<p>
+ The full example code &amp; sample output is in chi_square_std_deviation_test.cpp.
+ </p>
+<p>
+ We'll begin by defining the procedure that will calculate and print
+ out the confidence intervals:
+ </p>
+<pre class="programlisting">
+<span class="keyword">void</span> <span class="identifier">confidence_limits_on_std_deviation</span><span class="special">(</span>
+ <span class="keyword">double</span> <span class="identifier">Sd</span><span class="special">,</span> <span class="comment">// Sample Standard Deviation
+</span> <span class="keyword">unsigned</span> <span class="identifier">N</span><span class="special">)</span> <span class="comment">// Sample size
+</span><span class="special">{</span>
+</pre>
+<p>
+ We'll begin by printing out some general information:
+ </p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span>
+ <span class="string">"________________________________________________\n"</span>
+ <span class="string">"2-Sided Confidence Limits For Standard Deviation\n"</span>
+ <span class="string">"________________________________________________\n\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">7</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">40</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Number of Observations"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">N</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">40</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Standard Deviation"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">Sd</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+</pre>
+<p>
+ and then define a table of significance levels for which we'll calculate
+ intervals:
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">alpha</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">0.5</span><span class="special">,</span> <span class="number">0.25</span><span class="special">,</span> <span class="number">0.1</span><span class="special">,</span> <span class="number">0.05</span><span class="special">,</span> <span class="number">0.01</span><span class="special">,</span> <span class="number">0.001</span><span class="special">,</span> <span class="number">0.0001</span><span class="special">,</span> <span class="number">0.00001</span> <span class="special">};</span>
+</pre>
+<p>
+ The distribution we'll need to calculate the confidence intervals is
+ a Chi Squared distribution, with N-1 degrees of freedom:
+ </p>
+<pre class="programlisting">
+<span class="identifier">chi_squared</span> <span class="identifier">dist</span><span class="special">(</span><span class="identifier">N</span> <span class="special">-</span> <span class="number">1</span><span class="special">);</span>
+</pre>
+<p>
+ For each value of alpha, the formula for the confidence interval is
+ given by:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../../equations/chi_squ_tut1.png"></span>
+ </p>
+<p>
+ Where <span class="inlinemediaobject"><img src="../../../../../../equations/chi_squ_tut2.png"></span> is the upper critical value, and <span class="inlinemediaobject"><img src="../../../../../../equations/chi_squ_tut3.png"></span> is
+ the lower critical value of the Chi Squared distribution.
+ </p>
+<p>
+ In code we begin by printing out a table header:
+ </p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n\n"</span>
+ <span class="string">"_____________________________________________\n"</span>
+ <span class="string">"Confidence Lower Upper\n"</span>
+ <span class="string">" Value (%) Limit Limit\n"</span>
+ <span class="string">"_____________________________________________\n"</span><span class="special">;</span>
+</pre>
+<p>
+ and then loop over the values of alpha and calculate the intervals
+ for each: remember that the lower critical value is the same as the
+ quantile, and the upper critical value is the same as the quantile
+ from the complement of the probability:
+ </p>
+<pre class="programlisting">
+<span class="keyword">for</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">)/</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">[</span><span class="number">0</span><span class="special">]);</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="comment">// Confidence value:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="number">100</span> <span class="special">*</span> <span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]);</span>
+ <span class="comment">// Calculate limits:
+</span> <span class="keyword">double</span> <span class="identifier">lower_limit</span> <span class="special">=</span> <span class="identifier">sqrt</span><span class="special">((</span><span class="identifier">N</span> <span class="special">-</span> <span class="number">1</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">Sd</span> <span class="special">*</span> <span class="identifier">Sd</span> <span class="special">/</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> <span class="special">/</span> <span class="number">2</span><span class="special">)));</span>
+ <span class="keyword">double</span> <span class="identifier">upper_limit</span> <span class="special">=</span> <span class="identifier">sqrt</span><span class="special">((</span><span class="identifier">N</span> <span class="special">-</span> <span class="number">1</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">Sd</span> <span class="special">*</span> <span class="identifier">Sd</span> <span class="special">/</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> <span class="special">/</span> <span class="number">2</span><span class="special">));</span>
+ <span class="comment">// Print Limits:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">5</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">15</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">lower_limit</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">5</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">15</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">upper_limit</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+</pre>
+<p>
+ To see some example output we'll use the <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3581.htm" target="_top">gear
+ data</a> from the <a href="http://www.itl.nist.gov/div898/handbook/" target="_top">NIST/SEMATECH
+ e-Handbook of Statistical Methods.</a>. The data represents measurements
+ of gear diameter from a manufacturing process.
+ </p>
+<pre class="programlisting">________________________________________________
+2-Sided Confidence Limits For Standard Deviation
+________________________________________________
+
+Number of Observations = 100
+Standard Deviation = 0.006278908
+
+
+_____________________________________________
+Confidence Lower Upper
+ Value (%) Limit Limit
+_____________________________________________
+ 50.000 0.00601 0.00662
+ 75.000 0.00582 0.00685
+ 90.000 0.00563 0.00712
+ 95.000 0.00551 0.00729
+ 99.000 0.00530 0.00766
+ 99.900 0.00507 0.00812
+ 99.990 0.00489 0.00855
+ 99.999 0.00474 0.00895
+</pre>
+<p>
+ So at the 95% confidence level we conclude that the standard deviation
+ is between 0.00551 and 0.00729.
+ </p>
+<a name="math_toolkit.dist.stat_tut.weg.cs_eg.chi_sq_intervals.confidence_intervals_as_a_function_of_the_number_of_observations"></a><h5>
+<a name="id510742"></a>
+ <a href="chi_sq_intervals.html#math_toolkit.dist.stat_tut.weg.cs_eg.chi_sq_intervals.confidence_intervals_as_a_function_of_the_number_of_observations">Confidence
+ intervals as a function of the number of observations</a>
+ </h5>
+<p>
+ Similarly, we can also list the confidence intervals for the standard
+ deviation for the common confidence levels 95%, for increasing numbers
+ of observations.
+ </p>
+<p>
+ The standard deviation used to compute these values is unity, so the
+ limits listed are <span class="bold"><strong>multipliers</strong></span> for
+ any particular standard deviation. For example, given a standard deviation
+ of 0.0062789 as in the example above; for 100 observations the multiplier
+ is 0.8780 giving the lower confidence limit of 0.8780 * 0.006728 =
+ 0.00551.
+ </p>
+<pre class="programlisting">____________________________________________________
+Confidence level (two-sided) = 0.0500000
+Standard Deviation = 1.0000000
+________________________________________
+Observations Lower Upper
+ Limit Limit
+________________________________________
+ 2 0.4461 31.9102
+ 3 0.5207 6.2847
+ 4 0.5665 3.7285
+ 5 0.5991 2.8736
+ 6 0.6242 2.4526
+ 7 0.6444 2.2021
+ 8 0.6612 2.0353
+ 9 0.6755 1.9158
+ 10 0.6878 1.8256
+ 15 0.7321 1.5771
+ 20 0.7605 1.4606
+ 30 0.7964 1.3443
+ 40 0.8192 1.2840
+ 50 0.8353 1.2461
+ 60 0.8476 1.2197
+ 100 0.8780 1.1617
+ 120 0.8875 1.1454
+ 1000 0.9580 1.0459
+ 10000 0.9863 1.0141
+ 50000 0.9938 1.0062
+ 100000 0.9956 1.0044
+ 1000000 0.9986 1.0014
+</pre>
+<p>
+ With just 2 observations the limits are from <span class="bold"><strong>0.445</strong></span>
+ up to to <span class="bold"><strong>31.9</strong></span>, so the standard deviation
+ might be about <span class="bold"><strong>half</strong></span> the observed value
+ up to <span class="bold"><strong>30 times</strong></span> the observed value!
+ </p>
+<p>
+ Estimating a standard deviation with just a handful of values leaves
+ a very great uncertainty, especially the upper limit. Note especially
+ how far the upper limit is skewed from the most likely standard deviation.
+ </p>
+<p>
+ Even for 10 observations, normally considered a reasonable number,
+ the range is still from 0.69 to 1.8, about a range of 0.7 to 2, and
+ is still highly skewed with an upper limit <span class="bold"><strong>twice</strong></span>
+ the median.
+ </p>
+<p>
+ When we have 1000 observations, the estimate of the standard deviation
+ is starting to look convincing, with a range from 0.95 to 1.05 - now
+ near symmetrical, but still about + or - 5%.
+ </p>
+<p>
+ Only when we have 10000 or more repeated observations can we start
+ to be reasonably confident (provided we are sure that other factors
+ like drift are not creeping in).
+ </p>
+<p>
+ For 10000 observations, the interval is 0.99 to 1.1 - finally a really
+ convincing + or -1% confidence.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../cs_eg.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cs_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="chi_sq_test.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/cs_eg/chi_sq_size.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/cs_eg/chi_sq_size.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,181 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Estimating the Required Sample Sizes for a Chi-Square Test for the Standard Deviation</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../cs_eg.html" title="Chi Squared Distribution Examples">
+<link rel="prev" href="chi_sq_test.html" title="Chi-Square Test for the Standard Deviation">
+<link rel="next" href="../f_eg.html" title="F Distribution Examples">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="chi_sq_test.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cs_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../f_eg.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.cs_eg.chi_sq_size"></a><a href="chi_sq_size.html" title="Estimating the Required Sample Sizes for a Chi-Square Test for the Standard Deviation">
+ Estimating the Required Sample Sizes for a Chi-Square Test for the Standard
+ Deviation</a>
+</h6></div></div></div>
+<p>
+ Suppose we conduct a Chi Squared test for standard deviation and the
+ result is borderline, a legitimate question to ask is "How large
+ would the sample size have to be in order to produce a definitive result?"
+ </p>
+<p>
+ The class template chi_squared_distribution
+ has a static method <code class="computeroutput"><span class="identifier">find_degrees_of_freedom</span></code>
+ that will calculate this value for some acceptable risk of type I failure
+ <span class="emphasis"><em>alpha</em></span>, type II failure <span class="emphasis"><em>beta</em></span>,
+ and difference from the standard deviation <span class="emphasis"><em>diff</em></span>.
+ Please note that the method used works on variance, and not standard
+ deviation as is usual for the Chi Squared Test.
+ </p>
+<p>
+ The code for this example is located in chi_square_std_dev_test.cpp.
+ </p>
+<p>
+ We begin by defining a procedure to print out the sample sizes required
+ for various risk levels:
+ </p>
+<pre class="programlisting">
+<span class="keyword">void</span> <span class="identifier">chi_squared_sample_sized</span><span class="special">(</span>
+ <span class="keyword">double</span> <span class="identifier">diff</span><span class="special">,</span> <span class="comment">// difference from variance to detect
+</span> <span class="keyword">double</span> <span class="identifier">variance</span><span class="special">)</span> <span class="comment">// true variance
+</span><span class="special">{</span>
+</pre>
+<p>
+ The procedure begins by printing out the input data:
+ </p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">std</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+
+<span class="comment">// Print out general info:
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span>
+ <span class="string">"_____________________________________________________________\n"</span>
+ <span class="string">"Estimated sample sizes required for various confidence levels\n"</span>
+ <span class="string">"_____________________________________________________________\n\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">5</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">40</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"True Variance"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">variance</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">40</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Difference to detect"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">diff</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+</pre>
+<p>
+ And defines a table of significance levels for which we'll calculate
+ sample sizes:
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">alpha</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">0.5</span><span class="special">,</span> <span class="number">0.25</span><span class="special">,</span> <span class="number">0.1</span><span class="special">,</span> <span class="number">0.05</span><span class="special">,</span> <span class="number">0.01</span><span class="special">,</span> <span class="number">0.001</span><span class="special">,</span> <span class="number">0.0001</span><span class="special">,</span> <span class="number">0.00001</span> <span class="special">};</span>
+</pre>
+<p>
+ For each value of alpha we can calculate two sample sizes: one where
+ the sample variance is less than the true value by <span class="emphasis"><em>diff</em></span>
+ and one where it is greater than the true value by <span class="emphasis"><em>diff</em></span>.
+ Thanks to the asymmetric nature of the Chi Squared distribution these
+ two values will not be the same, the difference in their calculation
+ differs only in the sign of <span class="emphasis"><em>diff</em></span> that's passed
+ to <code class="computeroutput"><span class="identifier">find_degrees_of_freedom</span></code>.
+ Finally in this example we'll simply things, and let risk level <span class="emphasis"><em>beta</em></span>
+ be the same as <span class="emphasis"><em>alpha</em></span>:
+ </p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n\n"</span>
+ <span class="string">"_______________________________________________________________\n"</span>
+ <span class="string">"Confidence Estimated Estimated\n"</span>
+ <span class="string">" Value (%) Sample Size Sample Size\n"</span>
+ <span class="string">" (lower one (upper one\n"</span>
+ <span class="string">" sided test) sided test)\n"</span>
+ <span class="string">"_______________________________________________________________\n"</span><span class="special">;</span>
+<span class="comment">//
+</span><span class="comment">// Now print out the data for the table rows.
+</span><span class="comment">//
+</span><span class="keyword">for</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">)/</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">[</span><span class="number">0</span><span class="special">]);</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="comment">// Confidence value:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="number">100</span> <span class="special">*</span> <span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]);</span>
+ <span class="comment">// calculate df for a lower single sided test:
+</span> <span class="keyword">double</span> <span class="identifier">df</span> <span class="special">=</span> <span class="identifier">chi_squared</span><span class="special">::</span><span class="identifier">find_degrees_of_freedom</span><span class="special">(</span>
+ <span class="special">-</span><span class="identifier">diff</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">],</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">],</span> <span class="identifier">variance</span><span class="special">);</span>
+ <span class="comment">// convert to sample size:
+</span> <span class="keyword">double</span> <span class="identifier">size</span> <span class="special">=</span> <span class="identifier">ceil</span><span class="special">(</span><span class="identifier">df</span><span class="special">)</span> <span class="special">+</span> <span class="number">1</span><span class="special">;</span>
+ <span class="comment">// Print size:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">16</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">size</span><span class="special">;</span>
+ <span class="comment">// calculate df for an upper single sided test:
+</span> <span class="identifier">df</span> <span class="special">=</span> <span class="identifier">chi_squared</span><span class="special">::</span><span class="identifier">find_degrees_of_freedom</span><span class="special">(</span>
+ <span class="identifier">diff</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">],</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">],</span> <span class="identifier">variance</span><span class="special">);</span>
+ <span class="comment">// convert to sample size:
+</span> <span class="identifier">size</span> <span class="special">=</span> <span class="identifier">ceil</span><span class="special">(</span><span class="identifier">df</span><span class="special">)</span> <span class="special">+</span> <span class="number">1</span><span class="special">;</span>
+ <span class="comment">// Print size:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">16</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">size</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+</pre>
+<p>
+ For some example output, consider the <a href="http://www.itl.nist.gov/div898/handbook/prc/section2/prc23.htm" target="_top">silicon
+ wafer data</a> from the <a href="http://www.itl.nist.gov/div898/handbook/" target="_top">NIST/SEMATECH
+ e-Handbook of Statistical Methods.</a>. In this scenario a supplier
+ of 100 ohm.cm silicon wafers claims that his fabrication process can
+ produce wafers with sufficient consistency so that the standard deviation
+ of resistivity for the lot does not exceed 10 ohm.cm. A sample of N
+ = 10 wafers taken from the lot has a standard deviation of 13.97 ohm.cm,
+ and the question we ask ourselves is "How large would our sample
+ have to be to reliably detect this difference?".
+ </p>
+<p>
+ To use our procedure above, we have to convert the standard deviations
+ to variance (square them), after which the program output looks like
+ this:
+ </p>
+<pre class="programlisting">_____________________________________________________________
+Estimated sample sizes required for various confidence levels
+_____________________________________________________________
+
+True Variance = 100.00000
+Difference to detect = 95.16090
+
+
+_______________________________________________________________
+Confidence Estimated Estimated
+ Value (%) Sample Size Sample Size
+ (lower one (upper one
+ sided test) sided test)
+_______________________________________________________________
+ 50.000 2 2
+ 75.000 2 10
+ 90.000 4 32
+ 95.000 5 51
+ 99.000 7 99
+ 99.900 11 174
+ 99.990 15 251
+ 99.999 20 330
+</pre>
+<p>
+ In this case we are interested in a upper single sided test. So for
+ example, if the maximum acceptable risk of falsely rejecting the null-hypothesis
+ is 0.05 (Type I error), and the maximum acceptable risk of failing
+ to reject the null-hypothesis is also 0.05 (Type II error), we estimate
+ that we would need a sample size of 51.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="chi_sq_test.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cs_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../f_eg.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/cs_eg/chi_sq_test.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/cs_eg/chi_sq_test.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,297 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Chi-Square Test for the Standard Deviation</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../cs_eg.html" title="Chi Squared Distribution Examples">
+<link rel="prev" href="chi_sq_intervals.html" title="Confidence Intervals on the Standard Deviation">
+<link rel="next" href="chi_sq_size.html" title="Estimating the Required Sample Sizes for a Chi-Square Test for the Standard Deviation">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="chi_sq_intervals.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cs_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="chi_sq_size.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.cs_eg.chi_sq_test"></a><a href="chi_sq_test.html" title="Chi-Square Test for the Standard Deviation">
+ Chi-Square Test for the Standard Deviation</a>
+</h6></div></div></div>
+<p>
+ We use this test to determine whether the standard deviation of a sample
+ differs from a specified value. Typically this occurs in process change
+ situations where we wish to compare the standard deviation of a new
+ process to an established one.
+ </p>
+<p>
+ The code for this example is contained in chi_square_std_dev_test.cpp,
+ and we'll begin by defining the procedure that will print out the test
+ statistics:
+ </p>
+<pre class="programlisting">
+<span class="keyword">void</span> <span class="identifier">chi_squared_test</span><span class="special">(</span>
+ <span class="keyword">double</span> <span class="identifier">Sd</span><span class="special">,</span> <span class="comment">// Sample std deviation
+</span> <span class="keyword">double</span> <span class="identifier">D</span><span class="special">,</span> <span class="comment">// True std deviation
+</span> <span class="keyword">unsigned</span> <span class="identifier">N</span><span class="special">,</span> <span class="comment">// Sample size
+</span> <span class="keyword">double</span> <span class="identifier">alpha</span><span class="special">)</span> <span class="comment">// Significance level
+</span><span class="special">{</span>
+</pre>
+<p>
+ The procedure begins by printing a summary of the input data:
+ </p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">std</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+
+<span class="comment">// Print header:
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span>
+ <span class="string">"______________________________________________\n"</span>
+ <span class="string">"Chi Squared test for sample standard deviation\n"</span>
+ <span class="string">"______________________________________________\n\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">5</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Number of Observations"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">N</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Sample Standard Deviation"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">Sd</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Expected True Standard Deviation"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">D</span> <span class="special">&lt;&lt;</span> <span class="string">"\n\n"</span><span class="special">;</span>
+</pre>
+<p>
+ The test statistic (T) is simply the ratio of the sample and "true"
+ standard deviations squared, multiplied by the number of degrees of
+ freedom (the sample size less one):
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">t_stat</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">N</span> <span class="special">-</span> <span class="number">1</span><span class="special">)</span> <span class="special">*</span> <span class="special">(</span><span class="identifier">Sd</span> <span class="special">/</span> <span class="identifier">D</span><span class="special">)</span> <span class="special">*</span> <span class="special">(</span><span class="identifier">Sd</span> <span class="special">/</span> <span class="identifier">D</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Test Statistic"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">t_stat</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+</pre>
+<p>
+ The distribution we need to use, is a Chi Squared distribution with
+ N-1 degrees of freedom:
+ </p>
+<pre class="programlisting">
+<span class="identifier">chi_squared</span> <span class="identifier">dist</span><span class="special">(</span><span class="identifier">N</span> <span class="special">-</span> <span class="number">1</span><span class="special">);</span>
+</pre>
+<p>
+ The various hypothesis that can be tested are summarised in the following
+ table:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Hypothesis
+ </p>
+ </th>
+<th>
+ <p>
+ Test
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ The null-hypothesis: there is no difference in standard deviation
+ from the specified value
+ </p>
+ </td>
+<td>
+ <p>
+ Reject if T &lt; &#967;<sup>2</sup><sub>(1-alpha/2; N-1)</sub> or T &gt; &#967;<sup>2</sup><sub>(alpha/2; N-1)</sub>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ The alternative hypothesis: there is a difference in standard
+ deviation from the specified value
+ </p>
+ </td>
+<td>
+ <p>
+ Reject if &#967;<sup>2</sup><sub>(1-alpha/2; N-1)</sub> &gt;= T &gt;= &#967;<sup>2</sup><sub>(alpha/2; N-1)</sub>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ The alternative hypothesis: the standard deviation is less
+ than the specified value
+ </p>
+ </td>
+<td>
+ <p>
+ Reject if &#967;<sup>2</sup><sub>(1-alpha; N-1)</sub> &lt;= T
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ The alternative hypothesis: the standard deviation is greater
+ than the specified value
+ </p>
+ </td>
+<td>
+ <p>
+ Reject if &#967;<sup>2</sup><sub>(alpha; N-1)</sub> &gt;= T
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<p>
+ Where &#967;<sup>2</sup><sub>(alpha; N-1)</sub> is the upper critical value of the Chi Squared distribution,
+ and &#967;<sup>2</sup><sub>(1-alpha; N-1)</sub> is the lower critical value.
+ </p>
+<p>
+ Recall that the lower critical value is the same as the quantile, and
+ the upper critical value is the same as the quantile from the complement
+ of the probability, that gives us the following code to calculate the
+ critical values:
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">ucv</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">));</span>
+<span class="keyword">double</span> <span class="identifier">ucv2</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">alpha</span> <span class="special">/</span> <span class="number">2</span><span class="special">));</span>
+<span class="keyword">double</span> <span class="identifier">lcv</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">);</span>
+<span class="keyword">double</span> <span class="identifier">lcv2</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">alpha</span> <span class="special">/</span> <span class="number">2</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Upper Critical Value at alpha: "</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">scientific</span> <span class="special">&lt;&lt;</span> <span class="identifier">ucv</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Upper Critical Value at alpha/2: "</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">scientific</span> <span class="special">&lt;&lt;</span> <span class="identifier">ucv2</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Lower Critical Value at alpha: "</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">scientific</span> <span class="special">&lt;&lt;</span> <span class="identifier">lcv</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Lower Critical Value at alpha/2: "</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">scientific</span> <span class="special">&lt;&lt;</span> <span class="identifier">lcv2</span> <span class="special">&lt;&lt;</span> <span class="string">"\n\n"</span><span class="special">;</span>
+</pre>
+<p>
+ Now that we have the critical values, we can compare these to our test
+ statistic, and print out the result of each hypothesis and test:
+ </p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span>
+ <span class="string">"Results for Alternative Hypothesis and alpha"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">4</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">alpha</span> <span class="special">&lt;&lt;</span> <span class="string">"\n\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Alternative Hypothesis Conclusion\n"</span><span class="special">;</span>
+
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Standard Deviation != "</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">D</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span><span class="special">;</span>
+<span class="keyword">if</span><span class="special">((</span><span class="identifier">ucv2</span> <span class="special">&lt;</span> <span class="identifier">t_stat</span><span class="special">)</span> <span class="special">||</span> <span class="special">(</span><span class="identifier">lcv2</span> <span class="special">&gt;</span> <span class="identifier">t_stat</span><span class="special">))</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"ACCEPTED\n"</span><span class="special">;</span>
+<span class="keyword">else</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"REJECTED\n"</span><span class="special">;</span>
+
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Standard Deviation &lt; "</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">D</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span><span class="special">;</span>
+<span class="keyword">if</span><span class="special">(</span><span class="identifier">lcv</span> <span class="special">&gt;</span> <span class="identifier">t_stat</span><span class="special">)</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"ACCEPTED\n"</span><span class="special">;</span>
+<span class="keyword">else</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"REJECTED\n"</span><span class="special">;</span>
+
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Standard Deviation &gt; "</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">D</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span><span class="special">;</span>
+<span class="keyword">if</span><span class="special">(</span><span class="identifier">ucv</span> <span class="special">&lt;</span> <span class="identifier">t_stat</span><span class="special">)</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"ACCEPTED\n"</span><span class="special">;</span>
+<span class="keyword">else</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"REJECTED\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+</pre>
+<p>
+ To see some example output we'll use the <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3581.htm" target="_top">gear
+ data</a> from the <a href="http://www.itl.nist.gov/div898/handbook/" target="_top">NIST/SEMATECH
+ e-Handbook of Statistical Methods.</a>. The data represents measurements
+ of gear diameter from a manufacturing process. The program output is
+ deliberately designed to mirror the DATAPLOT output shown in the <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda358.htm" target="_top">NIST
+ Handbook Example</a>.
+ </p>
+<pre class="programlisting">______________________________________________
+Chi Squared test for sample standard deviation
+______________________________________________
+
+Number of Observations = 100
+Sample Standard Deviation = 0.00628
+Expected True Standard Deviation = 0.10000
+
+Test Statistic = 0.39030
+CDF of test statistic: = 1.438e-099
+Upper Critical Value at alpha: = 1.232e+002
+Upper Critical Value at alpha/2: = 1.284e+002
+Lower Critical Value at alpha: = 7.705e+001
+Lower Critical Value at alpha/2: = 7.336e+001
+
+Results for Alternative Hypothesis and alpha = 0.0500
+
+Alternative Hypothesis Conclusion
+Standard Deviation != 0.100 ACCEPTED
+Standard Deviation &lt; 0.100 ACCEPTED
+Standard Deviation &gt; 0.100 REJECTED
+</pre>
+<p>
+ In this case we are testing whether the sample standard deviation is
+ 0.1, and the null-hypothesis is rejected, so we conclude that the standard
+ deviation <span class="emphasis"><em>is not</em></span> 0.1.
+ </p>
+<p>
+ For an alternative example, consider the <a href="http://www.itl.nist.gov/div898/handbook/prc/section2/prc23.htm" target="_top">silicon
+ wafer data</a> again from the <a href="http://www.itl.nist.gov/div898/handbook/" target="_top">NIST/SEMATECH
+ e-Handbook of Statistical Methods.</a>. In this scenario a supplier
+ of 100 ohm.cm silicon wafers claims that his fabrication process can
+ produce wafers with sufficient consistency so that the standard deviation
+ of resistivity for the lot does not exceed 10 ohm.cm. A sample of N
+ = 10 wafers taken from the lot has a standard deviation of 13.97 ohm.cm,
+ and the question we ask ourselves is "Is the suppliers claim correct?".
+ </p>
+<p>
+ The program output now looks like this:
+ </p>
+<pre class="programlisting">______________________________________________
+Chi Squared test for sample standard deviation
+______________________________________________
+
+Number of Observations = 10
+Sample Standard Deviation = 13.97000
+Expected True Standard Deviation = 10.00000
+
+Test Statistic = 17.56448
+CDF of test statistic: = 9.594e-001
+Upper Critical Value at alpha: = 1.692e+001
+Upper Critical Value at alpha/2: = 1.902e+001
+Lower Critical Value at alpha: = 3.325e+000
+Lower Critical Value at alpha/2: = 2.700e+000
+
+Results for Alternative Hypothesis and alpha = 0.0500
+
+Alternative Hypothesis Conclusion
+Standard Deviation != 10.000 REJECTED
+Standard Deviation &lt; 10.000 REJECTED
+Standard Deviation &gt; 10.000 ACCEPTED
+</pre>
+<p>
+ In this case, our null-hypothesis is that the standard deviation of
+ the sample is less than 10: this hypothesis is rejected in the analysis
+ above, and so we reject the manufacturers claim.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="chi_sq_intervals.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../cs_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="chi_sq_size.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/dist_construct_eg.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/dist_construct_eg.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,431 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Distribution Construction Example</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../weg.html" title="Worked Examples">
+<link rel="prev" href="../weg.html" title="Worked Examples">
+<link rel="next" href="st_eg.html" title="Student's t Distribution Examples">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../weg.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="st_eg.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.dist_construct_eg"></a><a href="dist_construct_eg.html" title="Distribution Construction Example">
+ Distribution Construction Example</a>
+</h5></div></div></div>
+<p>
+ See distribution_construction.cpp
+ for full source code.
+ </p>
+<p>
+ </p>
+<p>
+ The structure of distributions is rather different from some other
+ statistical libraries, for example in less object-oriented language
+ like FORTRAN and C, that provide a few arguments to each free function.
+ This library provides each distribution as a template C++ class. A
+ distribution is constructed with a few arguments, and then member and
+ non-member functions are used to find values of the distribution, often
+ a function of a random variate.
+ </p>
+<p>
+ </p>
+<p>
+ First we need some includes to access the negative binomial distribution
+ (and the binomial, beta and gamma too).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">negative_binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// for negative_binomial_distribution
+</span> <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">negative_binomial_distribution</span><span class="special">;</span> <span class="comment">// default type is double.
+</span> <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">negative_binomial</span><span class="special">;</span> <span class="comment">// typedef provides default type is double.
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// for binomial_distribution.
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">beta</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// for beta_distribution.
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// for gamma_distribution.
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">normal</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// for normal_distribution.</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Several examples of constructing distributions follow: </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ First, a negative binomial distribution with 8 successes and a success
+ fraction 0.25, 25% or 1 in 4, is constructed like this:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">mydist0</span><span class="special">(</span><span class="number">8.</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ But this is inconveniently long, so by writing
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ or
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">negative_binomial_distribution</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ we can reduce typing.
+ </p>
+<p>
+ </p>
+<p>
+ Since the vast majority of applications use will be using double precision,
+ the template argument to the distribution (RealType) defaults to type
+ double, so we can also write:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">negative_binomial_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">mydist9</span><span class="special">(</span><span class="number">8.</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span> <span class="comment">// Uses default RealType = double.</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ But the name "negative_binomial_distribution" is still inconveniently
+ long, so for most distributions, a convenience typedef is provided,
+ for example:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">typedef</span> <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">negative_binomial</span><span class="special">;</span> <span class="comment">// Reserved name of type double.
+</span></pre>
+<p>
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ This convenience typedef is <span class="emphasis"><em>not</em></span> provided if
+ a clash would occur with the name of a function: currently only "beta"
+ and "gamma" fall into this category.
+ </p></td></tr>
+</table></div>
+<p>
+ </p>
+<p>
+ So, after a using statement,
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">negative_binomial</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ we have a convenient typedef to <code class="computeroutput"><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span></code>:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">negative_binomial</span> <span class="identifier">mydist</span><span class="special">(</span><span class="number">8.</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Some more examples using the convenience typedef:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">negative_binomial</span> <span class="identifier">mydist10</span><span class="special">(</span><span class="number">5.</span><span class="special">,</span> <span class="number">0.4</span><span class="special">);</span> <span class="comment">// Both arguments double.</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ And automatic conversion takes place, so you can use integers and floats:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">negative_binomial</span> <span class="identifier">mydist11</span><span class="special">(</span><span class="number">5</span><span class="special">,</span> <span class="number">0.4</span><span class="special">);</span> <span class="comment">// Using provided typedef double, int and double arguments.</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ This is probably the most common usage.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">negative_binomial</span> <span class="identifier">mydist12</span><span class="special">(</span><span class="number">5.</span><span class="special">,</span> <span class="number">0.4F</span><span class="special">);</span> <span class="comment">// Double and float arguments.
+</span><span class="identifier">negative_binomial</span> <span class="identifier">mydist13</span><span class="special">(</span><span class="number">5</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// Both arguments integer.</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Similarly for most other distributions like the binomial.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">binomial</span> <span class="identifier">mybinomial</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">0.5</span><span class="special">);</span> <span class="comment">// is more concise than
+</span><span class="identifier">binomial_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">mybinomd1</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">0.5</span><span class="special">);</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ For cases when the typdef distribution name would clash with a math
+ special function (currently only beta and gamma) the typedef is deliberately
+ not provided, and the longer version of the name must be used. For
+ example do not use:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">beta</span><span class="special">;</span>
+<span class="identifier">beta</span> <span class="identifier">mybetad0</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">0.5</span><span class="special">);</span> <span class="comment">// Error beta is a math FUNCTION!
+</span></pre>
+<p>
+ </p>
+<p>
+ Which produces the error messages:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">error C2146: syntax error : missing ';' before identifier 'mybetad0'
+warning C4551: function call missing argument list
+error C3861: 'mybetad0': identifier not found
+</pre>
+<p>
+ </p>
+<p>
+ Instead you should use:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">beta_distribution</span><span class="special">;</span>
+<span class="identifier">beta_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">mybetad1</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">0.5</span><span class="special">);</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ or for the gamma distribution:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">gamma_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">mygammad1</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">0.5</span><span class="special">);</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ We can, of course, still provide the type explicitly thus:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="comment">// Explicit double precision:
+</span><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">mydist1</span><span class="special">(</span><span class="number">8.</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span>
+
+<span class="comment">// Explicit float precision, double arguments are truncated to float:
+</span><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;</span> <span class="identifier">mydist2</span><span class="special">(</span><span class="number">8.</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span>
+
+<span class="comment">// Explicit float precision, integer &amp; double arguments converted to float.
+</span><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;</span> <span class="identifier">mydist3</span><span class="special">(</span><span class="number">8</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span>
+
+<span class="comment">// Explicit float precision, float arguments, so no conversion:
+</span><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;</span> <span class="identifier">mydist4</span><span class="special">(</span><span class="number">8.F</span><span class="special">,</span> <span class="number">0.25F</span><span class="special">);</span>
+
+<span class="comment">// Explicit float precision, integer arguments promoted to float.
+</span><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;</span> <span class="identifier">mydist5</span><span class="special">(</span><span class="number">8</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span>
+
+<span class="comment">// Explicit double precision:
+</span><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">mydist6</span><span class="special">(</span><span class="number">8.</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span>
+
+<span class="comment">// Explicit long double precision:
+</span><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">long</span> <span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">mydist7</span><span class="special">(</span><span class="number">8.</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ And if you have your own RealType called MyFPType, for example NTL
+ RR (an arbitrary precision type), then we can write:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="identifier">MyFPType</span><span class="special">&gt;</span> <span class="identifier">mydist6</span><span class="special">(</span><span class="number">8</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// Integer arguments -&gt; MyFPType.
+</span></pre>
+<p>
+ <a name="math_toolkit.dist.stat_tut.weg.dist_construct_eg.default_arguments_to_distribution_constructors_"></a>
+ </p>
+<h6>
+<a name="id501028"></a>
+ <a href="dist_construct_eg.html#math_toolkit.dist.stat_tut.weg.dist_construct_eg.default_arguments_to_distribution_constructors_">Default
+ arguments to distribution constructors.</a>
+ </h6>
+<p>
+ </p>
+<p>
+ Note that default constructor arguments are only provided for some
+ distributions. So if you wrongly assume a default argument you will
+ get an error message, for example:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">negative_binomial_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">mydist8</span><span class="special">;</span>
+</pre>
+<p>
+
+</p>
+<pre class="programlisting">error C2512 no appropriate default constructor available.</pre>
+<p>
+ </p>
+<p>
+ No default constructors are provided for the negative binomial, because
+ it is difficult to chose any sensible default values for this distribution.
+ For other distributions, like the normal distribution, it is obviously
+ very useful to provide 'standard' defaults for the mean and standard
+ deviation thus:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">normal_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">mean</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">sd</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
+</pre>
+<p>
+ </p>
+<p>
+ So in this case we can write:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">normal</span><span class="special">;</span>
+
+ <span class="identifier">normal</span> <span class="identifier">norm1</span><span class="special">;</span> <span class="comment">// Standard normal distribution.
+</span> <span class="identifier">normal</span> <span class="identifier">norm2</span><span class="special">(</span><span class="number">2</span><span class="special">);</span> <span class="comment">// Mean = 2, std deviation = 1.
+</span> <span class="identifier">normal</span> <span class="identifier">norm3</span><span class="special">(</span><span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">);</span> <span class="comment">// Mean = 2, std deviation = 3.
+</span>
+ <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
+<span class="special">}</span> <span class="comment">// int main()</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ There is no useful output from this program, of course. </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../weg.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="st_eg.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/error_eg.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/error_eg.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,274 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Error Handling Example</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../weg.html" title="Worked Examples">
+<link rel="prev" href="normal_example/normal_misc.html" title="Some Miscellaneous Examples of the Normal (Gaussian) Distribution">
+<link rel="next" href="find_eg.html" title="Find Location and Scale Examples">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="normal_example/normal_misc.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="find_eg.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.error_eg"></a><a href="error_eg.html" title="Error Handling Example"> Error Handling
+ Example</a>
+</h5></div></div></div>
+<p>
+ See <a href="../../../main_overview/error_handling.html" title="Error Handling">error handling
+ documentation</a> for a detailed explanation of the mechanism of handling
+ errors, including the common "bad" arguments to distributions
+ and functions, and how to use Policies
+ to control it.
+ </p>
+<p>
+ But, by default, <span class="bold"><strong>exceptions will be raised</strong></span>,
+ for domain errors, pole errors, numeric overflow, and internal evaluation
+ errors. To avoid the exceptions from getting thrown and instead get an
+ appropriate value returned, usually a NaN (domain errors pole errors
+ or internal errors), or infinity (from overflow), you need to change
+ the policy.
+ </p>
+<p>
+ </p>
+<p>
+ The following example demonstrates the effect of setting the macro
+ BOOST_MATH_DOMAIN_ERROR_POLICY when an invalid argument is encountered.
+ For the purposes of this example, we'll pass a negative degrees of
+ freedom parameter to the student's t distribution.
+ </p>
+<p>
+ </p>
+<p>
+ Since we know that this is a single file program we could just add:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">ignore_error</span>
+</pre>
+<p>
+ </p>
+<p>
+ to the top of the source file to change the default policy to one that
+ simply returns a NaN when a domain error occurs. Alternatively we could
+ use:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">errno_on_error</span>
+</pre>
+<p>
+ </p>
+<p>
+ To ensure the <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
+ is set when a domain error occurs as well as returning a NaN.
+ </p>
+<p>
+ </p>
+<p>
+ This is safe provided the program consists of a single translation
+ unit <span class="emphasis"><em>and</em></span> we place the define <span class="emphasis"><em>before</em></span>
+ any #includes. Note that should we add the define after the includes
+ then it will have no effect! A warning such as:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">warning C4005: 'BOOST_MATH_OVERFLOW_ERROR_POLICY' : macro redefinition</pre>
+<p>
+ </p>
+<p>
+ is a certain sign that it will <span class="emphasis"><em>not</em></span> have the desired
+ effect.
+ </p>
+<p>
+ </p>
+<p>
+ We'll begin our sample program with the needed includes:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="comment">// Boost
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">students_t</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">students_t</span><span class="special">;</span> <span class="comment">// Probability of students_t(df, t).
+</span>
+<span class="comment">// std
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">stdexcept</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Next we'll define the program's main() to call the student's t distribution
+ with an invalid degrees of freedom parameter, the program is set up
+ to handle either an exception or a NaN:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Example error handling using Student's t function. "</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"BOOST_MATH_DOMAIN_ERROR_POLICY is set to: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">BOOST_STRINGIZE</span><span class="special">(</span><span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+
+ <span class="keyword">double</span> <span class="identifier">degrees_of_freedom</span> <span class="special">=</span> <span class="special">-</span><span class="number">1</span><span class="special">;</span> <span class="comment">// A bad argument!
+</span> <span class="keyword">double</span> <span class="identifier">t</span> <span class="special">=</span> <span class="number">10</span><span class="special">;</span>
+
+ <span class="keyword">try</span>
+ <span class="special">{</span>
+ <span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
+ <span class="identifier">students_t</span> <span class="identifier">dist</span><span class="special">(</span><span class="identifier">degrees_of_freedom</span><span class="special">);</span> <span class="comment">// exception is thrown here if enabled
+</span> <span class="keyword">double</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">t</span><span class="special">);</span>
+ <span class="comment">// test for error reported by other means:
+</span> <span class="keyword">if</span><span class="special">((</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">isnan</span><span class="special">)(</span><span class="identifier">p</span><span class="special">))</span>
+ <span class="special">{</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"cdf returned a NaN!"</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"errno is set to: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">errno</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="keyword">else</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of Student's t is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">p</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="keyword">catch</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span><span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span>
+ <span class="string">"\n"</span><span class="string">"Message from thrown exception was:\n "</span> <span class="special">&lt;&lt;</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="special">}</span>
+
+ <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
+<span class="special">}</span> <span class="comment">// int main()</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Here's what the program output looks like with a default build (one
+ that does throw exceptions):
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Example error handling using Student's t function.
+BOOST_MATH_DOMAIN_ERROR_POLICY is set to: throw_on_error
+
+Message from thrown exception was:
+ Error in function boost::math::students_t_distribution&lt;double&gt;::students_t_distribution:
+ Degrees of freedom argument is -1, but must be &gt; 0 !
+</pre>
+<p>
+ </p>
+<p>
+ Alternatively let's build with:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">ignore_error</span>
+</pre>
+<p>
+ </p>
+<p>
+ Now the program output is:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Example error handling using Student's t function.
+BOOST_MATH_DOMAIN_ERROR_POLICY is set to: ignore_error
+cdf returned a NaN!
+errno is set to: 0
+</pre>
+<p>
+ </p>
+<p>
+ And finally let's build with:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">errno_on_error</span>
+</pre>
+<p>
+ </p>
+<p>
+ Which gives the output:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Example error handling using Student's t function.
+BOOST_MATH_DOMAIN_ERROR_POLICY is set to: errno_on_error
+cdf returned a NaN!
+errno is set to: 33
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ If throwing of exceptions is enabled (the default) but you do <span class="bold"><strong>not</strong></span> have try &amp; catch block, then the program
+ will terminate with an uncaught exception and probably abort.
+ </p>
+<p>
+ Therefore to get the benefit of helpful error messages, enabling <span class="bold"><strong>all exceptions and using try &amp; catch</strong></span> is
+ recommended for most applications.
+ </p>
+<p>
+ However, for simplicity, the is not done for most examples.
+ </p>
+</td></tr>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="normal_example/normal_misc.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="find_eg.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/f_eg.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/f_eg.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,331 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>F Distribution Examples</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../weg.html" title="Worked Examples">
+<link rel="prev" href="cs_eg/chi_sq_size.html" title="Estimating the Required Sample Sizes for a Chi-Square Test for the Standard Deviation">
+<link rel="next" href="binom_eg.html" title="Binomial Distribution Examples">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="cs_eg/chi_sq_size.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="binom_eg.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.f_eg"></a><a href="f_eg.html" title="F Distribution Examples"> F Distribution
+ Examples</a>
+</h5></div></div></div>
+<p>
+ Imagine that you want to compare the standard deviations of two sample
+ to determine if they differ in any significant way, in this situation
+ you use the F distribution and perform an F-test. This situation commonly
+ occurs when conducting a process change comparison: "is a new process
+ more consistent that the old one?".
+ </p>
+<p>
+ In this example we'll be using the data for ceramic strength from http://www.itl.nist.gov/div898/handbook/eda/section4/eda42a1.htm.
+ The data for this case study were collected by Said Jahanmir of the NIST
+ Ceramics Division in 1996 in connection with a NIST/industry ceramics
+ consortium for strength optimization of ceramic strength.
+ </p>
+<p>
+ The example program is f_test.cpp,
+ program output has been deliberately made as similar as possible to the
+ DATAPLOT output in the corresponding <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda359.htm" target="_top">NIST
+ EngineeringStatistics Handbook example</a>.
+ </p>
+<p>
+ We'll begin by defining the procedure to conduct the test:
+ </p>
+<pre class="programlisting">
+<span class="keyword">void</span> <span class="identifier">f_test</span><span class="special">(</span>
+ <span class="keyword">double</span> <span class="identifier">sd1</span><span class="special">,</span> <span class="comment">// Sample 1 std deviation
+</span> <span class="keyword">double</span> <span class="identifier">sd2</span><span class="special">,</span> <span class="comment">// Sample 2 std deviation
+</span> <span class="keyword">double</span> <span class="identifier">N1</span><span class="special">,</span> <span class="comment">// Sample 1 size
+</span> <span class="keyword">double</span> <span class="identifier">N2</span><span class="special">,</span> <span class="comment">// Sample 2 size
+</span> <span class="keyword">double</span> <span class="identifier">alpha</span><span class="special">)</span> <span class="comment">// Significance level
+</span><span class="special">{</span>
+</pre>
+<p>
+ The procedure begins by printing out a summary of our input data:
+ </p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">std</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+
+<span class="comment">// Print header:
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span>
+ <span class="string">"____________________________________\n"</span>
+ <span class="string">"F test for equal standard deviations\n"</span>
+ <span class="string">"____________________________________\n\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">5</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Sample 1:\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Number of Observations"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">N1</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Sample Standard Deviation"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">sd1</span> <span class="special">&lt;&lt;</span> <span class="string">"\n\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Sample 2:\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Number of Observations"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">N2</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Sample Standard Deviation"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">sd2</span> <span class="special">&lt;&lt;</span> <span class="string">"\n\n"</span><span class="special">;</span>
+</pre>
+<p>
+ The test statistic for an F-test is simply the ratio of the square of
+ the two standard deviations:
+ </p>
+<p>
+ F = s<sub>1</sub><sup>2</sup> / s<sub>2</sub><sup>2</sup>
+ </p>
+<p>
+ where s<sub>1</sub> is the standard deviation of the first sample and s<sub>2</sub>
+is the standard
+ deviation of the second sample. Or in code:
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">F</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">sd1</span> <span class="special">/</span> <span class="identifier">sd2</span><span class="special">);</span>
+<span class="identifier">F</span> <span class="special">*=</span> <span class="identifier">F</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Test Statistic"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">F</span> <span class="special">&lt;&lt;</span> <span class="string">"\n\n"</span><span class="special">;</span>
+</pre>
+<p>
+ At this point a word of caution: the F distribution is asymmetric, so
+ we have to be careful how we compute the tests, the following table summarises
+ the options available:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Hypothesis
+ </p>
+ </th>
+<th>
+ <p>
+ Test
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ The null-hypothesis: there is no difference in standard deviations
+ (two sided test)
+ </p>
+ </td>
+<td>
+ <p>
+ Reject if F &lt;= F<sub>(1-alpha/2; N1-1, N2-1)</sub> or F &gt;= F<sub>(alpha/2;
+ N1-1, N2-1)</sub>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ The alternative hypothesis: there is a difference in means (two
+ sided test)
+ </p>
+ </td>
+<td>
+ <p>
+ Reject if F<sub>(1-alpha/2; N1-1, N2-1)</sub> &lt;= F &lt;= F<sub>(alpha/2; N1-1,
+ N2-1)</sub>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ The alternative hypothesis: Standard deviation of sample 1 is
+ greater than that of sample 2
+ </p>
+ </td>
+<td>
+ <p>
+ Reject if F &lt; F<sub>(alpha; N1-1, N2-1)</sub>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ The alternative hypothesis: Standard deviation of sample 1 is
+ less than that of sample 2
+ </p>
+ </td>
+<td>
+ <p>
+ Reject if F &gt; F<sub>(1-alpha; N1-1, N2-1)</sub>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<p>
+ Where F<sub>(1-alpha; N1-1, N2-1)</sub> is the lower critical value of the F distribution
+ with degrees of freedom N1-1 and N2-1, and F<sub>(alpha; N1-1, N2-1)</sub> is the
+ upper critical value of the F distribution with degrees of freedom N1-1
+ and N2-1.
+ </p>
+<p>
+ The upper and lower critical values can be computed using the quantile
+ function:
+ </p>
+<p>
+ F<sub>(1-alpha; N1-1, N2-1)</sub> = <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">fisher_f</span><span class="special">(</span><span class="identifier">N1</span><span class="special">-</span><span class="number">1</span><span class="special">,</span>
+ <span class="identifier">N2</span><span class="special">-</span><span class="number">1</span><span class="special">),</span> <span class="identifier">alpha</span><span class="special">)</span></code>
+ </p>
+<p>
+ F<sub>(alpha; N1-1, N2-1)</sub> = <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">fisher_f</span><span class="special">(</span><span class="identifier">N1</span><span class="special">-</span><span class="number">1</span><span class="special">,</span>
+ <span class="identifier">N2</span><span class="special">-</span><span class="number">1</span><span class="special">),</span> <span class="identifier">alpha</span><span class="special">))</span></code>
+ </p>
+<p>
+ In our example program we need both upper and lower critical values for
+ alpha and for alpha/2:
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">ucv</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">));</span>
+<span class="keyword">double</span> <span class="identifier">ucv2</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">alpha</span> <span class="special">/</span> <span class="number">2</span><span class="special">));</span>
+<span class="keyword">double</span> <span class="identifier">lcv</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">);</span>
+<span class="keyword">double</span> <span class="identifier">lcv2</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">alpha</span> <span class="special">/</span> <span class="number">2</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Upper Critical Value at alpha: "</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">scientific</span> <span class="special">&lt;&lt;</span> <span class="identifier">ucv</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Upper Critical Value at alpha/2: "</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">scientific</span> <span class="special">&lt;&lt;</span> <span class="identifier">ucv2</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Lower Critical Value at alpha: "</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">scientific</span> <span class="special">&lt;&lt;</span> <span class="identifier">lcv</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Lower Critical Value at alpha/2: "</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">scientific</span> <span class="special">&lt;&lt;</span> <span class="identifier">lcv2</span> <span class="special">&lt;&lt;</span> <span class="string">"\n\n"</span><span class="special">;</span>
+</pre>
+<p>
+ The final step is to perform the comparisons given above, and print out
+ whether the hypothesis is rejected or not:
+ </p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span>
+ <span class="string">"Results for Alternative Hypothesis and alpha"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">4</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">alpha</span> <span class="special">&lt;&lt;</span> <span class="string">"\n\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Alternative Hypothesis Conclusion\n"</span><span class="special">;</span>
+
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Standard deviations are unequal (two sided test) "</span><span class="special">;</span>
+<span class="keyword">if</span><span class="special">((</span><span class="identifier">ucv2</span> <span class="special">&lt;</span> <span class="identifier">F</span><span class="special">)</span> <span class="special">||</span> <span class="special">(</span><span class="identifier">lcv2</span> <span class="special">&gt;</span> <span class="identifier">F</span><span class="special">))</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"ACCEPTED\n"</span><span class="special">;</span>
+<span class="keyword">else</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"REJECTED\n"</span><span class="special">;</span>
+
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Standard deviation 1 is less than standard deviation 2 "</span><span class="special">;</span>
+<span class="keyword">if</span><span class="special">(</span><span class="identifier">lcv</span> <span class="special">&gt;</span> <span class="identifier">F</span><span class="special">)</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"ACCEPTED\n"</span><span class="special">;</span>
+<span class="keyword">else</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"REJECTED\n"</span><span class="special">;</span>
+
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Standard deviation 1 is greater than standard deviation 2 "</span><span class="special">;</span>
+<span class="keyword">if</span><span class="special">(</span><span class="identifier">ucv</span> <span class="special">&lt;</span> <span class="identifier">F</span><span class="special">)</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"ACCEPTED\n"</span><span class="special">;</span>
+<span class="keyword">else</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"REJECTED\n"</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+</pre>
+<p>
+ Using the ceramic strength data as an example we get the following output:
+ </p>
+<pre class="programlisting">F test for equal standard deviations
+____________________________________
+
+Sample 1:
+Number of Observations = 240
+Sample Standard Deviation = 65.549
+
+Sample 2:
+Number of Observations = 240
+Sample Standard Deviation = 61.854
+
+Test Statistic = 1.123
+
+CDF of test statistic: = 8.148e-001
+Upper Critical Value at alpha: = 1.238e+000
+Upper Critical Value at alpha/2: = 1.289e+000
+Lower Critical Value at alpha: = 8.080e-001
+Lower Critical Value at alpha/2: = 7.756e-001
+
+Results for Alternative Hypothesis and alpha = 0.0500
+
+Alternative Hypothesis Conclusion
+Standard deviations are unequal (two sided test) REJECTED
+Standard deviation 1 is less than standard deviation 2 REJECTED
+Standard deviation 1 is greater than standard deviation 2 REJECTED
+</pre>
+<p>
+ In this case we are unable to reject the null-hypothesis, and must instead
+ reject the alternative hypothesis.
+ </p>
+<p>
+ By contrast let's see what happens when we use some different <a href="http://www.itl.nist.gov/div898/handbook/prc/section3/prc32.htm" target="_top">sample
+ data</a>:, once again from the NIST Engineering Statistics Handbook:
+ A new procedure to assemble a device is introduced and tested for possible
+ improvement in time of assembly. The question being addressed is whether
+ the standard deviation of the new assembly process (sample 2) is better
+ (i.e., smaller) than the standard deviation for the old assembly process
+ (sample 1).
+ </p>
+<pre class="programlisting">____________________________________
+F test for equal standard deviations
+____________________________________
+
+Sample 1:
+Number of Observations = 11.00000
+Sample Standard Deviation = 4.90820
+
+Sample 2:
+Number of Observations = 9.00000
+Sample Standard Deviation = 2.58740
+
+Test Statistic = 3.59847
+
+CDF of test statistic: = 9.589e-001
+Upper Critical Value at alpha: = 3.347e+000
+Upper Critical Value at alpha/2: = 4.295e+000
+Lower Critical Value at alpha: = 3.256e-001
+Lower Critical Value at alpha/2: = 2.594e-001
+
+Results for Alternative Hypothesis and alpha = 0.0500
+
+Alternative Hypothesis Conclusion
+Standard deviations are unequal (two sided test) REJECTED
+Standard deviation 1 is less than standard deviation 2 REJECTED
+Standard deviation 1 is greater than standard deviation 2 ACCEPTED
+</pre>
+<p>
+ In this case we take our null hypothesis as "standard deviation
+ 1 is less than or equal to standard deviation 2", since this represents
+ the "no change" situation. So we want to compare the upper
+ critical value at <span class="emphasis"><em>alpha</em></span> (a one sided test) with
+ the test statistic, and since 3.35 &lt; 3.6 this hypothesis must be rejected.
+ We therefore conclude that there is a change for the better in our standard
+ deviation.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="cs_eg/chi_sq_size.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="binom_eg.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/find_eg.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/find_eg.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,49 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Find Location and Scale Examples</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../weg.html" title="Worked Examples">
+<link rel="prev" href="error_eg.html" title="Error Handling Example">
+<link rel="next" href="find_eg/find_location_eg.html" title="Find Location (Mean) Example">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="error_eg.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="find_eg/find_location_eg.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.find_eg"></a><a href="find_eg.html" title="Find Location and Scale Examples"> Find Location
+ and Scale Examples</a>
+</h5></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="find_eg/find_location_eg.html">
+ Find Location (Mean) Example</a></span></dt>
+<dt><span class="section"><a href="find_eg/find_scale_eg.html">
+ Find Scale (Standard Deviation) Example</a></span></dt>
+<dt><span class="section"><a href="find_eg/find_mean_and_sd_eg.html">
+ Find mean and standard deviation example</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="error_eg.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="find_eg/find_location_eg.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/find_eg/find_location_eg.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/find_eg/find_location_eg.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,307 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Find Location (Mean) Example</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../find_eg.html" title="Find Location and Scale Examples">
+<link rel="prev" href="../find_eg.html" title="Find Location and Scale Examples">
+<link rel="next" href="find_scale_eg.html" title="Find Scale (Standard Deviation) Example">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../find_eg.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../find_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="find_scale_eg.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.find_eg.find_location_eg"></a><a href="find_location_eg.html" title="Find Location (Mean) Example">
+ Find Location (Mean) Example</a>
+</h6></div></div></div>
+<p>
+ </p>
+<p>
+ First we need some includes to access the normal distribution, the
+ algorithms to find location (and some std output of course).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">normal</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// for normal_distribution
+</span> <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">normal</span><span class="special">;</span> <span class="comment">// typedef provides default type is double.
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">cauchy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// for cauchy_distribution
+</span> <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">cauchy</span><span class="special">;</span> <span class="comment">// typedef provides default type is double.
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">find_location</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">find_location</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">complement</span><span class="special">;</span> <span class="comment">// Needed if you want to use the complement version.
+</span> <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">;</span>
+
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iomanip</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">limits</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ For this example, we will use the standard normal distribution, with
+ mean (location) zero and standard deviation (scale) unity. This is
+ also the default for this implementation.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">normal</span> <span class="identifier">N01</span><span class="special">;</span> <span class="comment">// Default 'standard' normal distribution with zero mean and
+</span><span class="keyword">double</span> <span class="identifier">sd</span> <span class="special">=</span> <span class="number">1.</span><span class="special">;</span> <span class="comment">// normal default standard deviation is 1.</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Suppose we want to find a different normal distribution whose mean
+ is shifted so that only fraction p (here 0.001 or 0.1%) are below
+ a certain chosen limit (here -2, two standard deviations).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">z</span> <span class="special">=</span> <span class="special">-</span><span class="number">2.</span><span class="special">;</span> <span class="comment">// z to give prob p
+</span><span class="keyword">double</span> <span class="identifier">p</span> <span class="special">=</span> <span class="number">0.001</span><span class="special">;</span> <span class="comment">// only 0.1% below z
+</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Normal distribution with mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">N01</span><span class="special">.</span><span class="identifier">location</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", standard deviation "</span> <span class="special">&lt;&lt;</span> <span class="identifier">N01</span><span class="special">.</span><span class="identifier">scale</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", has "</span> <span class="special">&lt;&lt;</span> <span class="string">"fraction &lt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", p = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">N01</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Normal distribution with mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">N01</span><span class="special">.</span><span class="identifier">location</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", standard deviation "</span> <span class="special">&lt;&lt;</span> <span class="identifier">N01</span><span class="special">.</span><span class="identifier">scale</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", has "</span> <span class="special">&lt;&lt;</span> <span class="string">"fraction &gt; "</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", p = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">N01</span><span class="special">,</span> <span class="identifier">z</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// Note: uses complement.</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Normal distribution with mean = 0, standard deviation 1, has fraction &lt;= -2, p = 0.0227501
+Normal distribution with mean = 0, standard deviation 1, has fraction &gt; -2, p = 0.97725
+</pre>
+<p>
+ </p>
+<p>
+ We can now use ''find_location'' to give a new offset mean.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">l</span> <span class="special">=</span> <span class="identifier">find_location</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">sd</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"offset location (mean) = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">l</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ that outputs:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">offset location (mean) = 1.09023
+</pre>
+<p>
+ </p>
+<p>
+ showing that we need to shift the mean just over one standard deviation
+ from its previous value of zero.
+ </p>
+<p>
+ </p>
+<p>
+ Then we can check that we have achieved our objective by constructing
+ a new distribution with the offset mean (but same standard deviation):
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">normal</span> <span class="identifier">np001pc</span><span class="special">(</span><span class="identifier">l</span><span class="special">,</span> <span class="identifier">sd</span><span class="special">);</span> <span class="comment">// Same standard_deviation (scale) but with mean (location) shifted.</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ And re-calculating the fraction below our chosen limit.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Normal distribution with mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">l</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" has "</span> <span class="special">&lt;&lt;</span> <span class="string">"fraction &lt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", p = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">np001pc</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Normal distribution with mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">l</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" has "</span> <span class="special">&lt;&lt;</span> <span class="string">"fraction &gt; "</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", p = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">np001pc</span><span class="special">,</span> <span class="identifier">z</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Normal distribution with mean = 1.09023 has fraction &lt;= -2, p = 0.001
+Normal distribution with mean = 1.09023 has fraction &gt; -2, p = 0.999
+</pre>
+<p>
+ <a name="math_toolkit.dist.stat_tut.weg.find_eg.find_location_eg.controlling_error_handling_from_find_location"></a>
+ </p>
+<h5>
+<a name="id558798"></a>
+ <a href="find_location_eg.html#math_toolkit.dist.stat_tut.weg.find_eg.find_location_eg.controlling_error_handling_from_find_location">Controlling
+ Error Handling from find_location</a>
+ </h5>
+<p>
+ </p>
+<p>
+ We can also control the policy for handling various errors. For example,
+ we can define a new (possibly unwise) policy to ignore domain errors
+ ('bad' arguments).
+ </p>
+<p>
+ </p>
+<p>
+ Unless we are using the boost::math namespace, we will need:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">domain_error</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">ignore_error</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Using a typedef is often convenient, especially if it is re-used,
+ although it is not required, as the various examples below show.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">ignore_error</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">ignore_domain_policy</span><span class="special">;</span>
+<span class="comment">// find_location with new policy, using typedef.
+</span><span class="identifier">l</span> <span class="special">=</span> <span class="identifier">find_location</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">sd</span><span class="special">,</span> <span class="identifier">ignore_domain_policy</span><span class="special">());</span>
+<span class="comment">// Default policy policy&lt;&gt;, needs "using boost::math::policies::policy;"
+</span><span class="identifier">l</span> <span class="special">=</span> <span class="identifier">find_location</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">sd</span><span class="special">,</span> <span class="identifier">policy</span><span class="special">&lt;&gt;());</span>
+<span class="comment">// Default policy, fully specified.
+</span><span class="identifier">l</span> <span class="special">=</span> <span class="identifier">find_location</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">sd</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">&lt;&gt;());</span>
+<span class="comment">// A new policy, ignoring domain errors, without using a typedef.
+</span><span class="identifier">l</span> <span class="special">=</span> <span class="identifier">find_location</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">sd</span><span class="special">,</span> <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">ignore_error</span><span class="special">&gt;</span> <span class="special">&gt;());</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ If we want to use a probability that is the <a href="../../overview.html#complements">complement
+ of our probability</a>, we should not even think of writing <code class="computeroutput"><span class="identifier">find_location</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">z</span><span class="special">,</span> <span class="number">1</span> <span class="special">-</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">sd</span><span class="special">)</span></code>,
+ but, to avoid loss of accuracy,
+ use the complement version.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">z</span> <span class="special">=</span> <span class="number">2.</span><span class="special">;</span>
+<span class="keyword">double</span> <span class="identifier">q</span> <span class="special">=</span> <span class="number">0.95</span><span class="special">;</span> <span class="comment">// = 1 - p; // complement.
+</span><span class="identifier">l</span> <span class="special">=</span> <span class="identifier">find_location</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">q</span><span class="special">,</span> <span class="identifier">sd</span><span class="special">));</span>
+
+<span class="identifier">normal</span> <span class="identifier">np95pc</span><span class="special">(</span><span class="identifier">l</span><span class="special">,</span> <span class="identifier">sd</span><span class="special">);</span> <span class="comment">// Same standard_deviation (scale) but with mean(location) shifted
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Normal distribution with mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">l</span> <span class="special">&lt;&lt;</span> <span class="string">" has "</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"fraction &lt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span> <span class="special">&lt;&lt;</span> <span class="string">" = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">np95pc</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Normal distribution with mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">l</span> <span class="special">&lt;&lt;</span> <span class="string">" has "</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"fraction &gt; "</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span> <span class="special">&lt;&lt;</span> <span class="string">" = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">np95pc</span><span class="special">,</span> <span class="identifier">z</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ See find_location_example.cpp
+ for full source code: the program output looks like this:
+</p>
+<pre class="programlisting">Example: Find location (mean).
+Normal distribution with mean = 0, standard deviation 1, has fraction &lt;= -2, p = 0.0227501
+Normal distribution with mean = 0, standard deviation 1, has fraction &gt; -2, p = 0.97725
+offset location (mean) = 1.09023
+Normal distribution with mean = 1.09023 has fraction &lt;= -2, p = 0.001
+Normal distribution with mean = 1.09023 has fraction &gt; -2, p = 0.999
+Normal distribution with mean = 0.355146 has fraction &lt;= 2 = 0.95
+Normal distribution with mean = 0.355146 has fraction &gt; 2 = 0.05
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../find_eg.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../find_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="find_scale_eg.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/find_eg/find_mean_and_sd_eg.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/find_eg/find_mean_and_sd_eg.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,756 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Find mean and standard deviation example</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../find_eg.html" title="Find Location and Scale Examples">
+<link rel="prev" href="find_scale_eg.html" title="Find Scale (Standard Deviation) Example">
+<link rel="next" href="../nag_library.html" title="Comparison with C, R, FORTRAN-style Free Functions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="find_scale_eg.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../find_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../nag_library.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.find_eg.find_mean_and_sd_eg"></a><a href="find_mean_and_sd_eg.html" title="Find mean and standard deviation example">
+ Find mean and standard deviation example</a>
+</h6></div></div></div>
+<p>
+ </p>
+<p>
+ First we need some includes to access the normal distribution, the
+ algorithms to find location and scale (and some std output of course).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">normal</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// for normal_distribution
+</span> <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">normal</span><span class="special">;</span> <span class="comment">// typedef provides default type is double.
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">cauchy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// for cauchy_distribution
+</span> <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">cauchy</span><span class="special">;</span> <span class="comment">// typedef provides default type is double.
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">find_location</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">find_location</span><span class="special">;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">find_scale</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">find_scale</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">complement</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">;</span>
+
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">left</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">showpoint</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">noshowpoint</span><span class="special">;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iomanip</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">limits</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ <a name="math_toolkit.dist.stat_tut.weg.find_eg.find_mean_and_sd_eg.using_find_location_and_find_scale_to_meet_dispensing_and_measurement_specifications"></a>
+ </p>
+<h5>
+<a name="id564016"></a>
+ <a href="find_mean_and_sd_eg.html#math_toolkit.dist.stat_tut.weg.find_eg.find_mean_and_sd_eg.using_find_location_and_find_scale_to_meet_dispensing_and_measurement_specifications">Using
+ find_location and find_scale to meet dispensing and measurement specifications</a>
+ </h5>
+<p>
+ </p>
+<p>
+ Consider an example from K Krishnamoorthy, Handbook of Statistical
+ Distributions with Applications, ISBN 1-58488-635-8, (2006) p 126,
+ example 10.3.7.
+ </p>
+<p>
+ </p>
+<p>
+ "A machine is set to pack 3 kg of ground beef per pack. Over
+ a long period of time it is found that the average packed was 3 kg
+ with a standard deviation of 0.1 kg. Assume the packing is normally
+ distributed."
+ </p>
+<p>
+ </p>
+<p>
+ We start by constructing a normal distribution with the given parameters:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">mean</span> <span class="special">=</span> <span class="number">3.</span><span class="special">;</span> <span class="comment">// kg
+</span><span class="keyword">double</span> <span class="identifier">standard_deviation</span> <span class="special">=</span> <span class="number">0.1</span><span class="special">;</span> <span class="comment">// kg
+</span><span class="identifier">normal</span> <span class="identifier">packs</span><span class="special">(</span><span class="identifier">mean</span><span class="special">,</span> <span class="identifier">standard_deviation</span><span class="special">);</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ We can then find the fraction (or %) of packages that weigh more
+ than 3.1 kg.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">max_weight</span> <span class="special">=</span> <span class="number">3.1</span><span class="special">;</span> <span class="comment">// kg
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Percentage of packs &gt; "</span> <span class="special">&lt;&lt;</span> <span class="identifier">max_weight</span> <span class="special">&lt;&lt;</span> <span class="string">" is "</span>
+<span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">packs</span><span class="special">,</span> <span class="identifier">max_weight</span><span class="special">))</span> <span class="special">*</span> <span class="number">100.</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// P(X &gt; 3.1)</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ We might want to ensure that 95% of packs are over a minimum weight
+ specification, then we want the value of the mean such that P(X &lt;
+ 2.9) = 0.05.
+ </p>
+<p>
+ </p>
+<p>
+ Using the mean of 3 kg, we can estimate the fraction of packs that
+ fail to meet the specification of 2.9 kg.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">minimum_weight</span> <span class="special">=</span> <span class="number">2.9</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span><span class="string">"Fraction of packs &lt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">minimum_weight</span> <span class="special">&lt;&lt;</span> <span class="string">" with a mean of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">mean</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">packs</span><span class="special">,</span> <span class="identifier">minimum_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// fraction of packs &lt;= 2.9 with a mean of 3 is 0.841345</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ This is 0.84 - more than the target fraction of 0.95. If we want
+ 95% to be over the minimum weight, what should we set the mean weight
+ to be?
+ </p>
+<p>
+ </p>
+<p>
+ Using the KK StatCalc program supplied with the book and the method
+ given on page 126 gives 3.06449.
+ </p>
+<p>
+ </p>
+<p>
+ We can confirm this by constructing a new distribution which we call
+ 'xpacks' with a safety margin mean of 3.06449 thus:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">over_mean</span> <span class="special">=</span> <span class="number">3.06449</span><span class="special">;</span>
+<span class="identifier">normal</span> <span class="identifier">xpacks</span><span class="special">(</span><span class="identifier">over_mean</span><span class="special">,</span> <span class="identifier">standard_deviation</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Fraction of packs &gt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">minimum_weight</span>
+<span class="special">&lt;&lt;</span> <span class="string">" with a mean of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">xpacks</span><span class="special">.</span><span class="identifier">mean</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">xpacks</span><span class="special">,</span> <span class="identifier">minimum_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// fraction of packs &gt;= 2.9 with a mean of 3.06449 is 0.950005</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Using this Math Toolkit, we can calculate the required mean directly
+ thus:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">under_fraction</span> <span class="special">=</span> <span class="number">0.05</span><span class="special">;</span> <span class="comment">// so 95% are above the minimum weight mean - sd = 2.9
+</span><span class="keyword">double</span> <span class="identifier">low_limit</span> <span class="special">=</span> <span class="identifier">standard_deviation</span><span class="special">;</span>
+<span class="keyword">double</span> <span class="identifier">offset</span> <span class="special">=</span> <span class="identifier">mean</span> <span class="special">-</span> <span class="identifier">low_limit</span> <span class="special">-</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">packs</span><span class="special">,</span> <span class="identifier">under_fraction</span><span class="special">);</span>
+<span class="keyword">double</span> <span class="identifier">nominal_mean</span> <span class="special">=</span> <span class="identifier">mean</span> <span class="special">+</span> <span class="identifier">offset</span><span class="special">;</span>
+<span class="comment">// mean + (mean - low_limit - quantile(packs, under_fraction));
+</span>
+<span class="identifier">normal</span> <span class="identifier">nominal_packs</span><span class="special">(</span><span class="identifier">nominal_mean</span><span class="special">,</span> <span class="identifier">standard_deviation</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Setting the packer to "</span> <span class="special">&lt;&lt;</span> <span class="identifier">nominal_mean</span> <span class="special">&lt;&lt;</span> <span class="string">" will mean that "</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"fraction of packs &gt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">minimum_weight</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">nominal_packs</span><span class="special">,</span> <span class="identifier">minimum_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// Setting the packer to 3.06449 will mean that fraction of packs &gt;= 2.9 is 0.95</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ This calculation is generalized as the free function called find_location.
+ </p>
+<p>
+ </p>
+<p>
+ To use this we will need to
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">find_location</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">find_location</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ and then use find_location function to find safe_mean, &amp; construct
+ a new normal distribution called 'goodpacks'.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">safe_mean</span> <span class="special">=</span> <span class="identifier">find_location</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">minimum_weight</span><span class="special">,</span> <span class="identifier">under_fraction</span><span class="special">,</span> <span class="identifier">standard_deviation</span><span class="special">);</span>
+<span class="identifier">normal</span> <span class="identifier">good_packs</span><span class="special">(</span><span class="identifier">safe_mean</span><span class="special">,</span> <span class="identifier">standard_deviation</span><span class="special">);</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ with the same confirmation as before:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Setting the packer to "</span> <span class="special">&lt;&lt;</span> <span class="identifier">nominal_mean</span> <span class="special">&lt;&lt;</span> <span class="string">" will mean that "</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"fraction of packs &gt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">minimum_weight</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">good_packs</span><span class="special">,</span> <span class="identifier">minimum_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// Setting the packer to 3.06449 will mean that fraction of packs &gt;= 2.9 is 0.95</span></pre>
+<p>
+ </p>
+<p>
+ <a name="math_toolkit.dist.stat_tut.weg.find_eg.find_mean_and_sd_eg.using_cauchy_lorentz_instead_of_normal_distribution"></a>
+ </p>
+<h5>
+<a name="id565674"></a>
+ <a href="find_mean_and_sd_eg.html#math_toolkit.dist.stat_tut.weg.find_eg.find_mean_and_sd_eg.using_cauchy_lorentz_instead_of_normal_distribution">Using
+ Cauchy-Lorentz instead of normal distribution</a>
+ </h5>
+<p>
+ </p>
+<p>
+ After examining the weight distribution of a large number of packs,
+ we might decide that, after all, the assumption of a normal distribution
+ is not really justified. We might find that the fit is better to
+ a <a href="../../../dist_ref/dists/cauchy_dist.html" title="Cauchy-Lorentz Distribution">Cauchy
+ Distribution</a>. This distribution has wider 'wings', so that
+ whereas most of the values are closer to the mean than the normal,
+ there are also more values than 'normal' that lie further from the
+ mean than the normal.
+ </p>
+<p>
+ </p>
+<p>
+ This might happen because a larger than normal lump of meat is either
+ included or excluded.
+ </p>
+<p>
+ </p>
+<p>
+ We first create a <a href="../../../dist_ref/dists/cauchy_dist.html" title="Cauchy-Lorentz Distribution">Cauchy
+ Distribution</a> with the original mean and standard deviation,
+ and estimate the fraction that lie below our minimum weight specification.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cauchy</span> <span class="identifier">cpacks</span><span class="special">(</span><span class="identifier">mean</span><span class="special">,</span> <span class="identifier">standard_deviation</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Cauchy Setting the packer to "</span> <span class="special">&lt;&lt;</span> <span class="identifier">mean</span> <span class="special">&lt;&lt;</span> <span class="string">" will mean that "</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"fraction of packs &gt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">minimum_weight</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">cpacks</span><span class="special">,</span> <span class="identifier">minimum_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// Cauchy Setting the packer to 3 will mean that fraction of packs &gt;= 2.9 is 0.75</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Note that far fewer of the packs meet the specification, only 75%
+ instead of 95%. Now we can repeat the find_location, using the cauchy
+ distribution as template parameter, in place of the normal used above.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">lc</span> <span class="special">=</span> <span class="identifier">find_location</span><span class="special">&lt;</span><span class="identifier">cauchy</span><span class="special">&gt;(</span><span class="identifier">minimum_weight</span><span class="special">,</span> <span class="identifier">under_fraction</span><span class="special">,</span> <span class="identifier">standard_deviation</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"find_location&lt;cauchy&gt;(minimum_weight, over fraction, standard_deviation); "</span> <span class="special">&lt;&lt;</span> <span class="identifier">lc</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// find_location&lt;cauchy&gt;(minimum_weight, over fraction, packs.standard_deviation()); 3.53138</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Note that the safe_mean setting needs to be much higher, 3.53138
+ instead of 3.06449, so we will make rather less profit.
+ </p>
+<p>
+ </p>
+<p>
+ And again confirm that the fraction meeting specification is as expected.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cauchy</span> <span class="identifier">goodcpacks</span><span class="special">(</span><span class="identifier">lc</span><span class="special">,</span> <span class="identifier">standard_deviation</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Cauchy Setting the packer to "</span> <span class="special">&lt;&lt;</span> <span class="identifier">lc</span> <span class="special">&lt;&lt;</span> <span class="string">" will mean that "</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"fraction of packs &gt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">minimum_weight</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">goodcpacks</span><span class="special">,</span> <span class="identifier">minimum_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// Cauchy Setting the packer to 3.53138 will mean that fraction of packs &gt;= 2.9 is 0.95</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Finally we could estimate the effect of a much tighter specification,
+ that 99% of packs met the specification.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Cauchy Setting the packer to "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">find_location</span><span class="special">&lt;</span><span class="identifier">cauchy</span><span class="special">&gt;(</span><span class="identifier">minimum_weight</span><span class="special">,</span> <span class="number">0.99</span><span class="special">,</span> <span class="identifier">standard_deviation</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" will mean that "</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"fraction of packs &gt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">minimum_weight</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">goodcpacks</span><span class="special">,</span> <span class="identifier">minimum_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Setting the packer to 3.13263 will mean that fraction of packs &gt;=
+ 2.9 is 0.99, but will more than double the mean loss from 0.0644
+ to 0.133 kg per pack.
+ </p>
+<p>
+ </p>
+<p>
+ Of course, this calculation is not limited to packs of meat, it applies
+ to dispensing anything, and it also applies to a 'virtual' material
+ like any measurement.
+ </p>
+<p>
+ </p>
+<p>
+ The only caveat is that the calculation assumes that the standard
+ deviation (scale) is known with a reasonably low uncertainty, something
+ that is not so easy to ensure in practice. And that the distribution
+ is well defined, <a href="../../../dist_ref/dists/normal_dist.html" title="Normal (Gaussian) Distribution">Normal
+ Distribution</a> or <a href="../../../dist_ref/dists/cauchy_dist.html" title="Cauchy-Lorentz Distribution">Cauchy
+ Distribution</a>, or some other.
+ </p>
+<p>
+ </p>
+<p>
+ If one is simply dispensing a very large number of packs, then it
+ may be feasible to measure the weight of hundreds or thousands of
+ packs. With a healthy 'degrees of freedom', the confidence intervals
+ for the standard deviation are not too wide, typically about + and
+ - 10% for hundreds of observations.
+ </p>
+<p>
+ </p>
+<p>
+ For other applications, where it is more difficult or expensive to
+ make many observations, the confidence intervals are depressingly
+ wide.
+ </p>
+<p>
+ </p>
+<p>
+ See <a href="../cs_eg/chi_sq_intervals.html" title="Confidence Intervals on the Standard Deviation">Confidence
+ Intervals on the standard deviation</a> for a worked example
+ chi_square_std_dev_test.cpp
+ of estimating these intervals.
+ </p>
+<p>
+ <a name="math_toolkit.dist.stat_tut.weg.find_eg.find_mean_and_sd_eg.changing_the_scale_or_standard_deviation"></a>
+ </p>
+<h5>
+<a name="id566630"></a>
+ <a href="find_mean_and_sd_eg.html#math_toolkit.dist.stat_tut.weg.find_eg.find_mean_and_sd_eg.changing_the_scale_or_standard_deviation">Changing
+ the scale or standard deviation</a>
+ </h5>
+<p>
+ </p>
+<p>
+ Alternatively, we could invest in a better (more precise) packer
+ (or measuring device) with a lower standard deviation, or scale.
+ </p>
+<p>
+ </p>
+<p>
+ This might cost more, but would reduce the amount we have to 'give
+ away' in order to meet the specification.
+ </p>
+<p>
+ </p>
+<p>
+ To estimate how much better (how much smaller standard deviation)
+ it would have to be, we need to get the 5% quantile to be located
+ at the under_weight limit, 2.9
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">p</span> <span class="special">=</span> <span class="number">0.05</span><span class="special">;</span> <span class="comment">// wanted p th quantile.
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Quantile of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">p</span> <span class="special">&lt;&lt;</span> <span class="string">" = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">packs</span><span class="special">,</span> <span class="identifier">p</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">packs</span><span class="special">.</span><span class="identifier">mean</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">", sd = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">packs</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Quantile of 0.05 = 2.83551, mean = 3, sd = 0.1
+ </p>
+<p>
+ </p>
+<p>
+ With the current packer (mean = 3, sd = 0.1), the 5% quantile is
+ at 2.8551 kg, a little below our target of 2.9 kg. So we know that
+ the standard deviation is going to have to be smaller.
+ </p>
+<p>
+ </p>
+<p>
+ Let's start by guessing that it (now 0.1) needs to be halved, to
+ a standard deviation of 0.05 kg.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">normal</span> <span class="identifier">pack05</span><span class="special">(</span><span class="identifier">mean</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Quantile of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">p</span> <span class="special">&lt;&lt;</span> <span class="string">" = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">pack05</span><span class="special">,</span> <span class="identifier">p</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pack05</span><span class="special">.</span><span class="identifier">mean</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">", sd = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pack05</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// Quantile of 0.05 = 2.91776, mean = 3, sd = 0.05
+</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span><span class="string">"Fraction of packs &gt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">minimum_weight</span> <span class="special">&lt;&lt;</span> <span class="string">" with a mean of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">mean</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" and standard deviation of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pack05</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">pack05</span><span class="special">,</span> <span class="identifier">minimum_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// Fraction of packs &gt;= 2.9 with a mean of 3 and standard deviation of 0.05 is 0.97725</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ So 0.05 was quite a good guess, but we are a little over the 2.9
+ target, so the standard deviation could be a tiny bit more. So we
+ could do some more guessing to get closer, say by increasing standard
+ deviation to 0.06 kg, constructing another new distribution called
+ pack06.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">normal</span> <span class="identifier">pack06</span><span class="special">(</span><span class="identifier">mean</span><span class="special">,</span> <span class="number">0.06</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Quantile of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">p</span> <span class="special">&lt;&lt;</span> <span class="string">" = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">pack06</span><span class="special">,</span> <span class="identifier">p</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pack06</span><span class="special">.</span><span class="identifier">mean</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">", sd = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pack06</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// Quantile of 0.05 = 2.90131, mean = 3, sd = 0.06
+</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span><span class="string">"Fraction of packs &gt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">minimum_weight</span> <span class="special">&lt;&lt;</span> <span class="string">" with a mean of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">mean</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" and standard deviation of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pack06</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">pack06</span><span class="special">,</span> <span class="identifier">minimum_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// Fraction of packs &gt;= 2.9 with a mean of 3 and standard deviation of 0.06 is 0.95221</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Now we are getting really close, but to do the job properly, we might
+ need to use root finding method, for example the tools provided,
+ and used elsewhere, in the Math Toolkit, see <a href="../../../../toolkit/internals1/roots2.html" title="Root Finding Without Derivatives">Root
+ Finding Without Derivatives</a>.
+ </p>
+<p>
+ </p>
+<p>
+ But in this (normal) distribution case, we can and should be even
+ smarter and make a direct calculation.
+ </p>
+<p>
+ </p>
+<p>
+ Our required limit is minimum_weight = 2.9 kg, often called the random
+ variate z. For a standard normal distribution, then probability p
+ = N((minimum_weight - mean) / sd).
+ </p>
+<p>
+ </p>
+<p>
+ We want to find the standard deviation that would be required to
+ meet this limit, so that the p th quantile is located at z (minimum_weight).
+ In this case, the 0.05 (5%) quantile is at 2.9 kg pack weight, when
+ the mean is 3 kg, ensuring that 0.95 (95%) of packs are above the
+ minimum weight.
+ </p>
+<p>
+ </p>
+<p>
+ Rearranging, we can directly calculate the required standard deviation:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">normal</span> <span class="identifier">N01</span><span class="special">;</span> <span class="comment">// standard normal distribution with meamn zero and unit standard deviation.
+</span><span class="identifier">p</span> <span class="special">=</span> <span class="number">0.05</span><span class="special">;</span>
+<span class="keyword">double</span> <span class="identifier">qp</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">N01</span><span class="special">,</span> <span class="identifier">p</span><span class="special">);</span>
+<span class="keyword">double</span> <span class="identifier">sd95</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">minimum_weight</span> <span class="special">-</span> <span class="identifier">mean</span><span class="special">)</span> <span class="special">/</span> <span class="identifier">qp</span><span class="special">;</span>
+
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"For the "</span><span class="special">&lt;&lt;</span> <span class="identifier">p</span> <span class="special">&lt;&lt;</span> <span class="string">"th quantile to be located at "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">minimum_weight</span> <span class="special">&lt;&lt;</span> <span class="string">", would need a standard deviation of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">sd95</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// For the 0.05th quantile to be located at 2.9, would need a standard deviation of 0.0607957</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ We can now construct a new (normal) distribution pack95 for the 'better'
+ packer, and check that our distribution will meet the specification.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">normal</span> <span class="identifier">pack95</span><span class="special">(</span><span class="identifier">mean</span><span class="special">,</span> <span class="identifier">sd95</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span><span class="string">"Fraction of packs &gt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">minimum_weight</span> <span class="special">&lt;&lt;</span> <span class="string">" with a mean of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">mean</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" and standard deviation of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pack95</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">pack95</span><span class="special">,</span> <span class="identifier">minimum_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// Fraction of packs &gt;= 2.9 with a mean of 3 and standard deviation of 0.0607957 is 0.95</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ This calculation is generalized in the free function find_scale,
+ as shown below, giving the same standard deviation.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">ss</span> <span class="special">=</span> <span class="identifier">find_scale</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">minimum_weight</span><span class="special">,</span> <span class="identifier">under_fraction</span><span class="special">,</span> <span class="identifier">packs</span><span class="special">.</span><span class="identifier">mean</span><span class="special">());</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"find_scale&lt;normal&gt;(minimum_weight, under_fraction, packs.mean()); "</span> <span class="special">&lt;&lt;</span> <span class="identifier">ss</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// find_scale&lt;normal&gt;(minimum_weight, under_fraction, packs.mean()); 0.0607957</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ If we had defined an over_fraction, or percentage that must pass
+ specification
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">over_fraction</span> <span class="special">=</span> <span class="number">0.95</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ And (wrongly) written
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">sso</span> <span class="special">=</span> <span class="identifier">find_scale</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">minimum_weight</span><span class="special">,</span> <span class="identifier">over_fraction</span><span class="special">,</span> <span class="identifier">packs</span><span class="special">.</span><span class="identifier">mean</span><span class="special">());</span>
+</pre>
+<p>
+ </p>
+<p>
+ With the default policy, we would get a message like
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Message from thrown exception was:
+ Error in function boost::math::find_scale&lt;Dist, Policy&gt;(double, double, double, Policy):
+ Computed scale (-0.060795683191176959) is &lt;= 0! Was the complement intended?
+</pre>
+<p>
+ </p>
+<p>
+ But this would return a <span class="bold"><strong>negative</strong></span>
+ standard deviation - obviously impossible. The probability should
+ be 1 - over_fraction, not over_fraction, thus:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">ss1o</span> <span class="special">=</span> <span class="identifier">find_scale</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">minimum_weight</span><span class="special">,</span> <span class="number">1</span> <span class="special">-</span> <span class="identifier">over_fraction</span><span class="special">,</span> <span class="identifier">packs</span><span class="special">.</span><span class="identifier">mean</span><span class="special">());</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"find_scale&lt;normal&gt;(minimum_weight, under_fraction, packs.mean()); "</span> <span class="special">&lt;&lt;</span> <span class="identifier">ss1o</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// find_scale&lt;normal&gt;(minimum_weight, under_fraction, packs.mean()); 0.0607957</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ But notice that using '1 - over_fraction' - will lead to a <a href="../../overview.html#why_complements">loss of accuracy, especially if over_fraction
+ was close to unity.</a> In this (very common) case, we should
+ instead use the complements, giving
+ the most accurate result.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">ssc</span> <span class="special">=</span> <span class="identifier">find_scale</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">minimum_weight</span><span class="special">,</span> <span class="identifier">over_fraction</span><span class="special">,</span> <span class="identifier">packs</span><span class="special">.</span><span class="identifier">mean</span><span class="special">()));</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"find_scale&lt;normal&gt;(complement(minimum_weight, over_fraction, packs.mean())); "</span> <span class="special">&lt;&lt;</span> <span class="identifier">ssc</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// find_scale&lt;normal&gt;(complement(minimum_weight, over_fraction, packs.mean())); 0.0607957</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Note that our guess of 0.06 was close to the accurate value of 0.060795683191176959.
+ </p>
+<p>
+ </p>
+<p>
+ We can again confirm our prediction thus:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">normal</span> <span class="identifier">pack95c</span><span class="special">(</span><span class="identifier">mean</span><span class="special">,</span> <span class="identifier">ssc</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span><span class="string">"Fraction of packs &gt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">minimum_weight</span> <span class="special">&lt;&lt;</span> <span class="string">" with a mean of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">mean</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" and standard deviation of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pack95c</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">pack95c</span><span class="special">,</span> <span class="identifier">minimum_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// Fraction of packs &gt;= 2.9 with a mean of 3 and standard deviation of 0.0607957 is 0.95</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Notice that these two deceptively simple questions:
+ </p>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc"><li>
+ Do we over-fill to make sure we meet a minimum specification (or
+ under-fill to avoid an overdose)?
+ </li></ul></div>
+<p>
+ </p>
+<p>
+ and/or
+ </p>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc"><li>
+ Do we measure better?
+ </li></ul></div>
+<p>
+ </p>
+<p>
+ are actually extremely common.
+ </p>
+<p>
+ </p>
+<p>
+ The weight of beef might be replaced by a measurement of more or
+ less anything, from drug tablet content, Apollo landing rocket firing,
+ X-ray treatment doses...
+ </p>
+<p>
+ </p>
+<p>
+ The scale can be variation in dispensing or uncertainty in measurement.
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ See find_mean_and_sd_normal.cpp
+ for full source code &amp; appended program output.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="find_scale_eg.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../find_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../nag_library.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/find_eg/find_scale_eg.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/find_eg/find_scale_eg.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,327 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Find Scale (Standard Deviation) Example</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../find_eg.html" title="Find Location and Scale Examples">
+<link rel="prev" href="find_location_eg.html" title="Find Location (Mean) Example">
+<link rel="next" href="find_mean_and_sd_eg.html" title="Find mean and standard deviation example">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="find_location_eg.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../find_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="find_mean_and_sd_eg.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.find_eg.find_scale_eg"></a><a href="find_scale_eg.html" title="Find Scale (Standard Deviation) Example">
+ Find Scale (Standard Deviation) Example</a>
+</h6></div></div></div>
+<p>
+ </p>
+<p>
+ First we need some includes to access the <a href="../../../dist_ref/dists/normal_dist.html" title="Normal (Gaussian) Distribution">Normal
+ Distribution</a>, the algorithms to find scale (and some std output
+ of course).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">normal</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// for normal_distribution
+</span> <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">normal</span><span class="special">;</span> <span class="comment">// typedef provides default type is double.
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">find_scale</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">find_scale</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">complement</span><span class="special">;</span> <span class="comment">// Needed if you want to use the complement version.
+</span> <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">;</span> <span class="comment">// Needed to specify the error handling policy.
+</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iomanip</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">limits</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ For this example, we will use the standard <a href="../../../dist_ref/dists/normal_dist.html" title="Normal (Gaussian) Distribution">Normal
+ Distribution</a>, with location (mean) zero and standard deviation
+ (scale) unity. Conveniently, this is also the default for this implementation's
+ constructor.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">normal</span> <span class="identifier">N01</span><span class="special">;</span> <span class="comment">// Default 'standard' normal distribution with zero mean
+</span><span class="keyword">double</span> <span class="identifier">sd</span> <span class="special">=</span> <span class="number">1.</span><span class="special">;</span> <span class="comment">// and standard deviation is 1.</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Suppose we want to find a different normal distribution with standard
+ deviation so that only fraction p (here 0.001 or 0.1%) are below
+ a certain chosen limit (here -2. standard deviations).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">z</span> <span class="special">=</span> <span class="special">-</span><span class="number">2.</span><span class="special">;</span> <span class="comment">// z to give prob p
+</span><span class="keyword">double</span> <span class="identifier">p</span> <span class="special">=</span> <span class="number">0.001</span><span class="special">;</span> <span class="comment">// only 0.1% below z = -2
+</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Normal distribution with mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">N01</span><span class="special">.</span><span class="identifier">location</span><span class="special">()</span> <span class="comment">// aka N01.mean()
+</span> <span class="special">&lt;&lt;</span> <span class="string">", standard deviation "</span> <span class="special">&lt;&lt;</span> <span class="identifier">N01</span><span class="special">.</span><span class="identifier">scale</span><span class="special">()</span> <span class="comment">// aka N01.standard_deviation()
+</span> <span class="special">&lt;&lt;</span> <span class="string">", has "</span> <span class="special">&lt;&lt;</span> <span class="string">"fraction &lt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", p = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">N01</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Normal distribution with mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">N01</span><span class="special">.</span><span class="identifier">location</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", standard deviation "</span> <span class="special">&lt;&lt;</span> <span class="identifier">N01</span><span class="special">.</span><span class="identifier">scale</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", has "</span> <span class="special">&lt;&lt;</span> <span class="string">"fraction &gt; "</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", p = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">N01</span><span class="special">,</span> <span class="identifier">z</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// Note: uses complement.</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Normal distribution with mean = 0 has fraction &lt;= -2, p = 0.0227501
+Normal distribution with mean = 0 has fraction &gt; -2, p = 0.97725
+</pre>
+<p>
+ </p>
+<p>
+ Noting that p = 0.02 instead of our target of 0.001, we can now use
+ <code class="computeroutput"><span class="identifier">find_scale</span></code> to give
+ a new standard deviation.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">l</span> <span class="special">=</span> <span class="identifier">N01</span><span class="special">.</span><span class="identifier">location</span><span class="special">();</span>
+<span class="keyword">double</span> <span class="identifier">s</span> <span class="special">=</span> <span class="identifier">find_scale</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">l</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"scale (standard deviation) = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">s</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ that outputs:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">scale (standard deviation) = 0.647201
+</pre>
+<p>
+ </p>
+<p>
+ showing that we need to reduce the standard deviation from 1. to
+ 0.65.
+ </p>
+<p>
+ </p>
+<p>
+ Then we can check that we have achieved our objective by constructing
+ a new distribution with the new standard deviation (but same zero
+ mean):
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">normal</span> <span class="identifier">np001pc</span><span class="special">(</span><span class="identifier">N01</span><span class="special">.</span><span class="identifier">location</span><span class="special">(),</span> <span class="identifier">s</span><span class="special">);</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ And re-calculating the fraction below (and above) our chosen limit.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Normal distribution with mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">l</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" has "</span> <span class="special">&lt;&lt;</span> <span class="string">"fraction &lt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", p = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">np001pc</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Normal distribution with mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">l</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" has "</span> <span class="special">&lt;&lt;</span> <span class="string">"fraction &gt; "</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", p = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">np001pc</span><span class="special">,</span> <span class="identifier">z</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Normal distribution with mean = 0 has fraction &lt;= -2, p = 0.001
+Normal distribution with mean = 0 has fraction &gt; -2, p = 0.999
+</pre>
+<p>
+ <a name="math_toolkit.dist.stat_tut.weg.find_eg.find_scale_eg.controlling_how_errors_from_find_scale_are_handled"></a>
+ </p>
+<h5>
+<a name="id561842"></a>
+ <a href="find_scale_eg.html#math_toolkit.dist.stat_tut.weg.find_eg.find_scale_eg.controlling_how_errors_from_find_scale_are_handled">Controlling
+ how Errors from find_scale are handled</a>
+ </h5>
+<p>
+ </p>
+<p>
+ We can also control the policy for handling various errors. For example,
+ we can define a new (possibly unwise) policy to ignore domain errors
+ ('bad' arguments).
+ </p>
+<p>
+ </p>
+<p>
+ Unless we are using the boost::math namespace, we will need:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">domain_error</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">ignore_error</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Using a typedef is convenient, especially if it is re-used, although
+ it is not required, as the various examples below show.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">ignore_error</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">ignore_domain_policy</span><span class="special">;</span>
+<span class="comment">// find_scale with new policy, using typedef.
+</span><span class="identifier">l</span> <span class="special">=</span> <span class="identifier">find_scale</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">l</span><span class="special">,</span> <span class="identifier">ignore_domain_policy</span><span class="special">());</span>
+<span class="comment">// Default policy policy&lt;&gt;, needs using boost::math::policies::policy;
+</span>
+<span class="identifier">l</span> <span class="special">=</span> <span class="identifier">find_scale</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">l</span><span class="special">,</span> <span class="identifier">policy</span><span class="special">&lt;&gt;());</span>
+<span class="comment">// Default policy, fully specified.
+</span><span class="identifier">l</span> <span class="special">=</span> <span class="identifier">find_scale</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">l</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">&lt;&gt;());</span>
+<span class="comment">// New policy, without typedef.
+</span><span class="identifier">l</span> <span class="special">=</span> <span class="identifier">find_scale</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">l</span><span class="special">,</span> <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">ignore_error</span><span class="special">&gt;</span> <span class="special">&gt;());</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ If we want to express a probability, say 0.999, that is a complement,
+ <code class="computeroutput"><span class="number">1</span> <span class="special">-</span>
+ <span class="identifier">p</span></code> we should not even think
+ of writing <code class="computeroutput"><span class="identifier">find_scale</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">z</span><span class="special">,</span> <span class="number">1</span> <span class="special">-</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">l</span><span class="special">)</span></code>, but instead,
+ use the complements version.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">z</span> <span class="special">=</span> <span class="special">-</span><span class="number">2.</span><span class="special">;</span>
+<span class="keyword">double</span> <span class="identifier">q</span> <span class="special">=</span> <span class="number">0.999</span><span class="special">;</span> <span class="comment">// = 1 - p; // complement of 0.001.
+</span><span class="identifier">sd</span> <span class="special">=</span> <span class="identifier">find_scale</span><span class="special">&lt;</span><span class="identifier">normal</span><span class="special">&gt;(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">q</span><span class="special">,</span> <span class="identifier">l</span><span class="special">));</span>
+
+<span class="identifier">normal</span> <span class="identifier">np95pc</span><span class="special">(</span><span class="identifier">l</span><span class="special">,</span> <span class="identifier">sd</span><span class="special">);</span> <span class="comment">// Same standard_deviation (scale) but with mean(scale) shifted
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Normal distribution with mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">l</span> <span class="special">&lt;&lt;</span> <span class="string">" has "</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"fraction &lt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span> <span class="special">&lt;&lt;</span> <span class="string">" = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">np95pc</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Normal distribution with mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">l</span> <span class="special">&lt;&lt;</span> <span class="string">" has "</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"fraction &gt; "</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span> <span class="special">&lt;&lt;</span> <span class="string">" = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">np95pc</span><span class="special">,</span> <span class="identifier">z</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Sadly, it is all too easy to get probabilities the wrong way round,
+ when you may get a warning like this:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Message from thrown exception was:
+ Error in function boost::math::find_scale&lt;Dist, Policy&gt;(complement(double, double, double, Policy)):
+ Computed scale (-0.48043523852179076) is &lt;= 0! Was the complement intended?
+</pre>
+<p>
+ </p>
+<p>
+ The default error handling policy is to throw an exception with this
+ message, but if you chose a policy to ignore the error, the (impossible)
+ negative scale is quietly returned. </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ See find_scale_example.cpp
+ for full source code: the program output looks like this:
+</p>
+<pre class="programlisting">Example: Find scale (standard deviation).
+Normal distribution with mean = 0, standard deviation 1, has fraction &lt;= -2, p = 0.0227501
+Normal distribution with mean = 0, standard deviation 1, has fraction &gt; -2, p = 0.97725
+scale (standard deviation) = 0.647201
+Normal distribution with mean = 0 has fraction &lt;= -2, p = 0.001
+Normal distribution with mean = 0 has fraction &gt; -2, p = 0.999
+Normal distribution with mean = 0.946339 has fraction &lt;= -2 = 0.001
+Normal distribution with mean = 0.946339 has fraction &gt; -2 = 0.999
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="find_location_eg.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../find_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="find_mean_and_sd_eg.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/nag_library.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/nag_library.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,114 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Comparison with C, R, FORTRAN-style Free Functions</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../weg.html" title="Worked Examples">
+<link rel="prev" href="find_eg/find_mean_and_sd_eg.html" title="Find mean and standard deviation example">
+<link rel="next" href="../variates.html" title="Random Variates and Distribution Parameters">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="find_eg/find_mean_and_sd_eg.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../variates.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.nag_library"></a><a href="nag_library.html" title="Comparison with C, R, FORTRAN-style Free Functions"> Comparison
+ with C, R, FORTRAN-style Free Functions</a>
+</h5></div></div></div>
+<p>
+ You are probably familiar with a statistics library that has free functions,
+ for example the classic <a href="http://nag.com/numeric/CL/CLdescription.asp" target="_top">NAG
+ C library</a> and matching <a href="http://nag.com/numeric/FL/FLdescription.asp" target="_top">NAG
+ FORTRAN Library</a>, <a href="http://office.microsoft.com/en-us/excel/HP052090051033.aspx" target="_top">Microsoft
+ Excel BINOMDIST(number_s,trials,probability_s,cumulative)</a>, R, <a href="http://www.ptc.com/products/mathcad/mathcad14/mathcad_func_chart.htm" target="_top">MathCAD
+ pbinom</a> and many others.
+ </p>
+<p>
+ If so, you may find 'Distributions as Objects' unfamiliar, if not alien.
+ </p>
+<p>
+ However, <span class="bold"><strong>do not panic</strong></span>, both definition
+ and usage are not really very different.
+ </p>
+<p>
+ A very simple example of generating the same values as the <a href="http://nag.com/numeric/CL/CLdescription.asp" target="_top">NAG
+ C library</a> for the binomial distribution follows. (If you find
+ slightly different values, the Boost C++ version, using double or better,
+ is very likely to be the more accurate. Of course, accuracy is not usually
+ a concern for most applications of this function).
+ </p>
+<p>
+ The <a href="http://www.nag.co.uk/numeric/cl/manual/pdf/G01/g01bjc.pdf" target="_top">NAG
+ function specification</a> is
+ </p>
+<pre class="programlisting">
+<span class="keyword">void</span> <span class="identifier">nag_binomial_dist</span><span class="special">(</span><span class="identifier">Integer</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">Integer</span> <span class="identifier">k</span><span class="special">,</span>
+<span class="keyword">double</span> <span class="special">*</span><span class="identifier">plek</span><span class="special">,</span> <span class="keyword">double</span> <span class="special">*</span><span class="identifier">pgtk</span><span class="special">,</span> <span class="keyword">double</span> <span class="special">*</span><span class="identifier">peqk</span><span class="special">,</span> <span class="identifier">NagError</span> <span class="special">*</span><span class="identifier">fail</span><span class="special">)</span>
+</pre>
+<p>
+ and is called
+ </p>
+<pre class="programlisting">
+<span class="identifier">g01bjc</span><span class="special">(</span><span class="identifier">n</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">k</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">plek</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">pgtk</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">peqk</span><span class="special">,</span> <span class="identifier">NAGERR_DEFAULT</span><span class="special">);</span>
+</pre>
+<p>
+ The equivalent using this Boost C++ library is:
+ </p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span> <span class="comment">// Using declaration avoids very long names.
+</span><span class="identifier">binomial</span> <span class="identifier">my_dist</span><span class="special">(</span><span class="number">4</span><span class="special">,</span> <span class="number">0.5</span><span class="special">);</span> <span class="comment">// c.f. NAG n = 4, p = 0.5
+</span></pre>
+<p>
+ and values can be output thus:
+ </p>
+<pre class="programlisting">
+<span class="identifier">cout</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">my_dist</span><span class="special">.</span><span class="identifier">trials</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span> <span class="comment">// Echo the NAG input n = 4 trials.
+</span> <span class="special">&lt;&lt;</span> <span class="identifier">my_dist</span><span class="special">.</span><span class="identifier">success_fraction</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span> <span class="comment">// Echo the NAG input p = 0.5
+</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">my_dist</span><span class="special">,</span> <span class="number">2</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span> <span class="comment">// NAG plek with k = 2
+</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">my_dist</span><span class="special">,</span> <span class="number">2</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span> <span class="comment">// NAG pgtk with k = 2
+</span> <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">my_dist</span><span class="special">,</span> <span class="number">2</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// NAG peqk with k = 2
+</span></pre>
+<p>
+ <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">k</span><span class="special">)</span></code>
+ is equivalent to NAG library <code class="computeroutput"><span class="identifier">plek</span></code>,
+ lower tail probability of &lt;= k
+ </p>
+<p>
+ <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">k</span><span class="special">))</span></code>
+ is equivalent to NAG library <code class="computeroutput"><span class="identifier">pgtk</span></code>,
+ upper tail probability of &gt; k
+ </p>
+<p>
+ <code class="computeroutput"><span class="identifier">pdf</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">k</span><span class="special">)</span></code>
+ is equivalent to NAG library <code class="computeroutput"><span class="identifier">peqk</span></code>,
+ point probability of == k
+ </p>
+<p>
+ See binomial_example_nag.cpp
+ for details.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="find_eg/find_mean_and_sd_eg.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../variates.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/neg_binom_eg.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/neg_binom_eg.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,56 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Negative Binomial Distribution Examples</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../weg.html" title="Worked Examples">
+<link rel="prev" href="binom_eg/binom_size_eg.html" title="Estimating Sample Sizes for a Binomial Distribution.">
+<link rel="next" href="neg_binom_eg/neg_binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for the Negative Binomial Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="binom_eg/binom_size_eg.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="neg_binom_eg/neg_binom_conf.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.neg_binom_eg"></a><a href="neg_binom_eg.html" title="Negative Binomial Distribution Examples"> Negative
+ Binomial Distribution Examples</a>
+</h5></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="neg_binom_eg/neg_binom_conf.html">
+ Calculating Confidence Limits on the Frequency of Occurrence for the
+ Negative Binomial Distribution</a></span></dt>
+<dt><span class="section"><a href="neg_binom_eg/neg_binom_size_eg.html">
+ Estimating Sample Sizes for the Negative Binomial.</a></span></dt>
+<dt><span class="section"><a href="neg_binom_eg/negative_binomial_example1.html">
+ Negative Binomial Sales Quota Example.</a></span></dt>
+<dt><span class="section"><a href="neg_binom_eg/negative_binomial_example2.html">
+ Negative Binomial Table Printing Example.</a></span></dt>
+</dl></div>
+<p>
+ (See also the reference documentation for the <a href="../../dist_ref/dists/negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
+ Binomial Distribution</a>.)
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="binom_eg/binom_size_eg.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="neg_binom_eg/neg_binom_conf.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/neg_binom_eg/neg_binom_conf.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/neg_binom_eg/neg_binom_conf.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,274 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Calculating Confidence Limits on the Frequency of Occurrence for the Negative Binomial Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../neg_binom_eg.html" title="Negative Binomial Distribution Examples">
+<link rel="prev" href="../neg_binom_eg.html" title="Negative Binomial Distribution Examples">
+<link rel="next" href="neg_binom_size_eg.html" title="Estimating Sample Sizes for the Negative Binomial.">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../neg_binom_eg.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../neg_binom_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="neg_binom_size_eg.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.neg_binom_eg.neg_binom_conf"></a><a href="neg_binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for the Negative Binomial Distribution">
+ Calculating Confidence Limits on the Frequency of Occurrence for the
+ Negative Binomial Distribution</a>
+</h6></div></div></div>
+<p>
+ Imagine you have a process that follows a negative binomial distribution:
+ for each trial conducted, an event either occurs or does it does not,
+ referred to as "successes" and "failures". The
+ frequency with which successes occur is variously referred to as the
+ success fraction, success ratio, success percentage, occurrence frequency,
+ or probability of occurrence.
+ </p>
+<p>
+ If, by experiment, you want to measure the the best estimate of success
+ fraction is given simply by <span class="emphasis"><em>k</em></span> / <span class="emphasis"><em>N</em></span>,
+ for <span class="emphasis"><em>k</em></span> successes out of <span class="emphasis"><em>N</em></span>
+ trials.
+ </p>
+<p>
+ However our confidence in that estimate will be shaped by how many
+ trials were conducted, and how many successes were observed. The static
+ member functions <code class="computeroutput"><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;&gt;::</span><span class="identifier">find_lower_bound_on_p</span></code>
+ and <code class="computeroutput"><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;&gt;::</span><span class="identifier">find_upper_bound_on_p</span></code>
+ allow you to calculate the confidence intervals for your estimate of
+ the success fraction.
+ </p>
+<p>
+ The sample program neg_binom_confidence_limits.cpp
+ illustrates their use.
+ </p>
+<p>
+ </p>
+<p>
+ First we need some includes to access the negative binomial distribution
+ (and some basic std output of course).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">negative_binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">negative_binomial</span><span class="special">;</span>
+
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+<span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iomanip</span><span class="special">&gt;</span>
+<span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">left</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">fixed</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ First define a table of significance levels: these are the probabilities
+ that the true occurrence frequency lies outside the calculated interval:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">alpha</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">0.5</span><span class="special">,</span> <span class="number">0.25</span><span class="special">,</span> <span class="number">0.1</span><span class="special">,</span> <span class="number">0.05</span><span class="special">,</span> <span class="number">0.01</span><span class="special">,</span> <span class="number">0.001</span><span class="special">,</span> <span class="number">0.0001</span><span class="special">,</span> <span class="number">0.00001</span> <span class="special">};</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Confidence value as % is (1 - alpha) * 100, so alpha 0.05 == 95%
+ confidence that the true occurence frequency lies <span class="bold"><strong>inside</strong></span>
+ the calculated interval.
+ </p>
+<p>
+ </p>
+<p>
+ We need a function to calculate and print confidence limits for an
+ observed frequency of occurrence that follows a negative binomial
+ distribution.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">void</span> <span class="identifier">confidence_limits_on_frequency</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">trials</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">successes</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="comment">// trials = Total number of trials.
+</span> <span class="comment">// successes = Total number of observed successes.
+</span> <span class="comment">// failures = trials - successes.
+</span> <span class="comment">// success_fraction = successes /trials.
+</span> <span class="comment">// Print out general info:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span>
+ <span class="string">"______________________________________________\n"</span>
+ <span class="string">"2-Sided Confidence Limits For Success Fraction\n"</span>
+ <span class="string">"______________________________________________\n\n"</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">7</span><span class="special">);</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">40</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Number of trials"</span> <span class="special">&lt;&lt;</span> <span class="string">" = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">trials</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">40</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Number of successes"</span> <span class="special">&lt;&lt;</span> <span class="string">" = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">successes</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">40</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Number of failures"</span> <span class="special">&lt;&lt;</span> <span class="string">" = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">trials</span> <span class="special">-</span> <span class="identifier">successes</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">40</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Observed frequency of occurrence"</span> <span class="special">&lt;&lt;</span> <span class="string">" = "</span> <span class="special">&lt;&lt;</span> <span class="keyword">double</span><span class="special">(</span><span class="identifier">successes</span><span class="special">)</span> <span class="special">/</span> <span class="identifier">trials</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+
+ <span class="comment">// Print table header:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n\n"</span>
+ <span class="string">"___________________________________________\n"</span>
+ <span class="string">"Confidence Lower Upper\n"</span>
+ <span class="string">" Value (%) Limit Limit\n"</span>
+ <span class="string">"___________________________________________\n"</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ And now for the important part - the bounds themselves. For each
+ value of <span class="emphasis"><em>alpha</em></span>, we call <code class="computeroutput"><span class="identifier">find_lower_bound_on_p</span></code>
+ and <code class="computeroutput"><span class="identifier">find_upper_bound_on_p</span></code>
+ to obtain lower and upper bounds respectively. Note that since we
+ are calculating a two-sided interval, we must divide the value of
+ alpha in two. Had we been calculating a single-sided interval, for
+ example: <span class="emphasis"><em>"Calculate a lower bound so that we are P%
+ sure that the true occurrence frequency is greater than some value"</em></span>
+ then we would <span class="bold"><strong>not</strong></span> have divided by
+ two.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+ <span class="comment">// Now print out the upper and lower limits for the alpha table values.
+</span> <span class="keyword">for</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">)/</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">[</span><span class="number">0</span><span class="special">]);</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="comment">// Confidence value:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="number">100</span> <span class="special">*</span> <span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]);</span>
+ <span class="comment">// Calculate bounds:
+</span> <span class="keyword">double</span> <span class="identifier">lower</span> <span class="special">=</span> <span class="identifier">negative_binomial</span><span class="special">::</span><span class="identifier">find_lower_bound_on_p</span><span class="special">(</span><span class="identifier">trials</span><span class="special">,</span> <span class="identifier">successes</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]/</span><span class="number">2</span><span class="special">);</span>
+ <span class="keyword">double</span> <span class="identifier">upper</span> <span class="special">=</span> <span class="identifier">negative_binomial</span><span class="special">::</span><span class="identifier">find_upper_bound_on_p</span><span class="special">(</span><span class="identifier">trials</span><span class="special">,</span> <span class="identifier">successes</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]/</span><span class="number">2</span><span class="special">);</span>
+ <span class="comment">// Print limits:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">5</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">15</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">lower</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">5</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">15</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">upper</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span> <span class="comment">// void confidence_limits_on_frequency(unsigned trials, unsigned successes)</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ And then call confidence_limits_on_frequency with increasing numbers
+ of trials, but always the same success fraction 0.1, or 1 in 10.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="identifier">confidence_limits_on_frequency</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">2</span><span class="special">);</span> <span class="comment">// 20 trials, 2 successes, 2 in 20, = 1 in 10 = 0.1 success fraction.
+</span> <span class="identifier">confidence_limits_on_frequency</span><span class="special">(</span><span class="number">200</span><span class="special">,</span> <span class="number">20</span><span class="special">);</span> <span class="comment">// More trials, but same 0.1 success fraction.
+</span> <span class="identifier">confidence_limits_on_frequency</span><span class="special">(</span><span class="number">2000</span><span class="special">,</span> <span class="number">200</span><span class="special">);</span> <span class="comment">// Many more trials, but same 0.1 success fraction.
+</span>
+ <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
+<span class="special">}</span> <span class="comment">// int main()
+</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ Let's see some sample output for a 1 in 10 success ratio, first for
+ a mere 20 trials:
+ </p>
+<pre class="programlisting">______________________________________________
+2-Sided Confidence Limits For Success Fraction
+______________________________________________
+Number of trials = 20
+Number of successes = 2
+Number of failures = 18
+Observed frequency of occurrence = 0.1
+___________________________________________
+Confidence Lower Upper
+ Value (%) Limit Limit
+___________________________________________
+ 50.000 0.04812 0.13554
+ 75.000 0.03078 0.17727
+ 90.000 0.01807 0.22637
+ 95.000 0.01235 0.26028
+ 99.000 0.00530 0.33111
+ 99.900 0.00164 0.41802
+ 99.990 0.00051 0.49202
+ 99.999 0.00016 0.55574
+</pre>
+<p>
+ As you can see, even at the 95% confidence level the bounds (0.012
+ to 0.26) are really very wide, and very asymmetric about the observed
+ value 0.1.
+ </p>
+<p>
+ Compare that with the program output for a mass 2000 trials:
+ </p>
+<pre class="programlisting">______________________________________________
+2-Sided Confidence Limits For Success Fraction
+______________________________________________
+Number of trials = 2000
+Number of successes = 200
+Number of failures = 1800
+Observed frequency of occurrence = 0.1
+___________________________________________
+Confidence Lower Upper
+ Value (%) Limit Limit
+___________________________________________
+ 50.000 0.09536 0.10445
+ 75.000 0.09228 0.10776
+ 90.000 0.08916 0.11125
+ 95.000 0.08720 0.11352
+ 99.000 0.08344 0.11802
+ 99.900 0.07921 0.12336
+ 99.990 0.07577 0.12795
+ 99.999 0.07282 0.13206
+</pre>
+<p>
+ Now even when the confidence level is very high, the limits (at 99.999%,
+ 0.07 to 0.13) are really quite close and nearly symmetric to the observed
+ value of 0.1.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../neg_binom_eg.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../neg_binom_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="neg_binom_size_eg.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/neg_binom_eg/neg_binom_size_eg.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/neg_binom_eg/neg_binom_size_eg.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,257 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Estimating Sample Sizes for the Negative Binomial.</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../neg_binom_eg.html" title="Negative Binomial Distribution Examples">
+<link rel="prev" href="neg_binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for the Negative Binomial Distribution">
+<link rel="next" href="negative_binomial_example1.html" title="Negative Binomial Sales Quota Example.">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="neg_binom_conf.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../neg_binom_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="negative_binomial_example1.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.neg_binom_eg.neg_binom_size_eg"></a><a href="neg_binom_size_eg.html" title="Estimating Sample Sizes for the Negative Binomial.">
+ Estimating Sample Sizes for the Negative Binomial.</a>
+</h6></div></div></div>
+<p>
+ Imagine you have an event (let's call it a "failure" - though
+ we could equally well call it a success if we felt it was a 'good'
+ event) that you know will occur in 1 in N trials. You may want to know
+ how many trials you need to conduct to be P% sure of observing at least
+ k such failures. If the failure events follow a negative binomial distribution
+ (each trial either succeeds or fails) then the static member function
+ <code class="computeroutput"><span class="identifier">negative_binomial_distibution</span><span class="special">&lt;&gt;::</span><span class="identifier">find_minimum_number_of_trials</span></code>
+ can be used to estimate the minimum number of trials required to be
+ P% sure of observing the desired number of failures.
+ </p>
+<p>
+ The example program neg_binomial_sample_sizes.cpp
+ demonstrates its usage.
+ </p>
+<p>
+ </p>
+<p>
+ It centres around a routine that prints out a table of minimum sample
+ sizes for various probability thresholds:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">void</span> <span class="identifier">find_number_of_trials</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">failures</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">p</span><span class="special">);</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ First define a table of significance levels: these are the maximum
+ acceptable probability that <span class="emphasis"><em>failure</em></span> or fewer
+ events will be observed.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">alpha</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">0.5</span><span class="special">,</span> <span class="number">0.25</span><span class="special">,</span> <span class="number">0.1</span><span class="special">,</span> <span class="number">0.05</span><span class="special">,</span> <span class="number">0.01</span><span class="special">,</span> <span class="number">0.001</span><span class="special">,</span> <span class="number">0.0001</span><span class="special">,</span> <span class="number">0.00001</span> <span class="special">};</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Confidence value as % is (1 - alpha) * 100, so alpha 0.05 == 95%
+ confidence that the desired number of failures will be observed.
+ </p>
+<p>
+ </p>
+<p>
+ Much of the rest of the program is pretty-printing, the important
+ part is in the calculation of minimum number of trials required for
+ each value of alpha using:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="special">(</span><span class="keyword">int</span><span class="special">)</span><span class="identifier">ceil</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">::</span><span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span><span class="identifier">failures</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]);</span>
+</pre>
+<p>
+ </p>
+<p>
+ find_minimum_number_of_trials returns a double, so ceil rounds this
+ up to ensure we have an integral minimum number of trials.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+
+<span class="keyword">void</span> <span class="identifier">find_number_of_trials</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">failures</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">p</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="comment">// trials = number of trials
+</span> <span class="comment">// failures = number of failures before achieving required success(es).
+</span> <span class="comment">// p = success fraction (0 &lt;= p &lt;= 1.).
+</span> <span class="comment">//
+</span> <span class="comment">// Calculate how many trials we need to ensure the
+</span> <span class="comment">// required number of failures DOES exceed "failures".
+</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="string">"Target number of failures = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">failures</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">", Success fraction = "</span> <span class="special">&lt;&lt;</span> <span class="number">100</span> <span class="special">*</span> <span class="identifier">p</span> <span class="special">&lt;&lt;</span> <span class="string">"%"</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+ <span class="comment">// Print table header:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n\n"</span>
+ <span class="string">"____________________________\n"</span>
+ <span class="string">"Confidence Min Number\n"</span>
+ <span class="string">" Value (%) Of Trials \n"</span>
+ <span class="string">"____________________________\n"</span><span class="special">;</span>
+ <span class="comment">// Now print out the data for the alpha table values.
+</span> <span class="keyword">for</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">)/</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">[</span><span class="number">0</span><span class="special">]);</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span>
+ <span class="special">{</span> <span class="comment">// Confidence values %:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="number">100</span> <span class="special">*</span> <span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">])</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span>
+ <span class="comment">// find_minimum_number_of_trials
+</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">6</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="special">(</span><span class="keyword">int</span><span class="special">)</span><span class="identifier">ceil</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">::</span><span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span><span class="identifier">failures</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]))</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span> <span class="comment">// void find_number_of_trials(double failures, double p)</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ finally we can produce some tables of minimum trials for the chosen
+ confidence levels:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="identifier">find_number_of_trials</span><span class="special">(</span><span class="number">5</span><span class="special">,</span> <span class="number">0.5</span><span class="special">);</span>
+ <span class="identifier">find_number_of_trials</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">);</span>
+ <span class="identifier">find_number_of_trials</span><span class="special">(</span><span class="number">500</span><span class="special">,</span> <span class="number">0.5</span><span class="special">);</span>
+ <span class="identifier">find_number_of_trials</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.1</span><span class="special">);</span>
+ <span class="identifier">find_number_of_trials</span><span class="special">(</span><span class="number">500</span><span class="special">,</span> <span class="number">0.1</span><span class="special">);</span>
+ <span class="identifier">find_number_of_trials</span><span class="special">(</span><span class="number">5</span><span class="special">,</span> <span class="number">0.9</span><span class="special">);</span>
+
+ <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
+<span class="special">}</span> <span class="comment">// int main()
+</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ Since we're calculating the <span class="emphasis"><em>minimum</em></span> number of
+ trials required, we'll err on the safe side and take the ceiling
+ of the result. Had we been calculating the <span class="emphasis"><em>maximum</em></span>
+ number of trials permitted to observe less than a certain number
+ of <span class="emphasis"><em>failures</em></span> then we would have taken the floor
+ instead. We would also have called <code class="computeroutput"><span class="identifier">find_minimum_number_of_trials</span></code>
+ like this:
+</p>
+<pre class="programlisting">
+<span class="identifier">floor</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">::</span><span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span><span class="identifier">failures</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]))</span>
+</pre>
+<p>
+ which would give us the largest number of trials we could conduct
+ and still be P% sure of observing <span class="emphasis"><em>failures or less</em></span>
+ failure events, when the probability of success is <span class="emphasis"><em>p</em></span>.
+ </p>
+</td></tr>
+</table></div>
+<p>
+ We'll finish off by looking at some sample output, firstly suppose
+ we wish to observe at least 5 "failures" with a 50/50 (0.5)
+ chance of success or failure:
+ </p>
+<pre class="programlisting">Target number of failures = 5, Success fraction = 50%
+
+____________________________
+Confidence Min Number
+ Value (%) Of Trials
+____________________________
+ 50.000 11
+ 75.000 14
+ 90.000 17
+ 95.000 18
+ 99.000 22
+ 99.900 27
+ 99.990 31
+ 99.999 36
+
+</pre>
+<p>
+ So 18 trials or more would yield a 95% chance that at least our 5 required
+ failures would be observed.
+ </p>
+<p>
+ Compare that to what happens if the success ratio is 90%:
+ </p>
+<pre class="programlisting">Target number of failures = 5.000, Success fraction = 90.000%
+
+____________________________
+Confidence Min Number
+ Value (%) Of Trials
+____________________________
+ 50.000 57
+ 75.000 73
+ 90.000 91
+ 95.000 103
+ 99.000 127
+ 99.900 159
+ 99.990 189
+ 99.999 217
+</pre>
+<p>
+ So now 103 trials are required to observe at least 5 failures with
+ 95% certainty.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="neg_binom_conf.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../neg_binom_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="negative_binomial_example1.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/neg_binom_eg/negative_binomial_example1.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/neg_binom_eg/negative_binomial_example1.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,844 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Negative Binomial Sales Quota Example.</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../neg_binom_eg.html" title="Negative Binomial Distribution Examples">
+<link rel="prev" href="neg_binom_size_eg.html" title="Estimating Sample Sizes for the Negative Binomial.">
+<link rel="next" href="negative_binomial_example2.html" title="Negative Binomial Table Printing Example.">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="neg_binom_size_eg.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../neg_binom_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="negative_binomial_example2.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.neg_binom_eg.negative_binomial_example1"></a><a href="negative_binomial_example1.html" title="Negative Binomial Sales Quota Example.">
+ Negative Binomial Sales Quota Example.</a>
+</h6></div></div></div>
+<p>
+ This example program <a href="../../../../../../../../example/negative_binomial_example1.cpp" target="_top">negative_binomial_example1.cpp
+ (full source code)</a> demonstrates a simple use to find the probability
+ of meeting a sales quota.
+ </p>
+<p>
+ </p>
+<p>
+ Based on <a href="http://en.wikipedia.org/wiki/Negative_binomial_distribution" target="_top">a
+ problem by Dr. Diane Evans, Professor of Mathematics at Rose-Hulman
+ Institute of Technology</a>.
+ </p>
+<p>
+ </p>
+<p>
+ Pat is required to sell candy bars to raise money for the 6th grade
+ field trip. There are thirty houses in the neighborhood, and Pat
+ is not supposed to return home until five candy bars have been sold.
+ So the child goes door to door, selling candy bars. At each house,
+ there is a 0.4 probability (40%) of selling one candy bar and a 0.6
+ probability (60%) of selling nothing.
+ </p>
+<p>
+ </p>
+<p>
+ What is the probability mass (density) function (pdf) for selling
+ the last (fifth) candy bar at the nth house?
+ </p>
+<p>
+ </p>
+<p>
+ The Negative Binomial(r, p) distribution describes the probability
+ of k failures and r successes in k+r Bernoulli(p) trials with success
+ on the last trial. (A <a href="http://en.wikipedia.org/wiki/Bernoulli_distribution" target="_top">Bernoulli
+ trial</a> is one with only two possible outcomes, success of
+ failure, and p is the probability of success). See also <a href="../../../../../" target="_top">http://en.wikipedia.org/wiki/Bernoulli_distribution
+ Bernoulli distribution</a> and <a href="http://www.math.uah.edu/stat/bernoulli/Introduction.xhtml" target="_top">Bernoulli
+ applications</a>.
+ </p>
+<p>
+ </p>
+<p>
+ In this example, we will deliberately produce a variety of calculations
+ and outputs to demonstrate the ways that the negative binomial distribution
+ can be implemented with this library: it is also deliberately over-commented.
+ </p>
+<p>
+ </p>
+<p>
+ First we need to #define macros to control the error and discrete
+ handling policies. For this simple example, we want to avoid throwing
+ an exception (the default policy) and just return infinity. We want
+ to treat the distribution as if it was continuous, so we choose a
+ discrete_quantile policy of real, rather than the default policy
+ integer_round_outwards.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_OVERFLOW_ERROR_POLICY</span> <span class="identifier">ignore_error</span>
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DISCRETE_QUANTILE_POLICY</span> <span class="identifier">real</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ After that we need some includes to provide easy access to the negative
+ binomial distribution,
+ </p>
+<p>
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ It is vital to #include distributions etc <span class="bold"><strong>after</strong></span>
+ the above #defines
+ </p></td></tr>
+</table></div>
+<p>
+ </p>
+<p>
+ and we need some std library iostream, of course.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">negative_binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+ <span class="comment">// for negative_binomial_distribution
+</span> <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">negative_binomial</span><span class="special">;</span> <span class="comment">// typedef provides default type is double.
+</span> <span class="keyword">using</span> <span class="special">::</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">pdf</span><span class="special">;</span> <span class="comment">// Probability mass function.
+</span> <span class="keyword">using</span> <span class="special">::</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">cdf</span><span class="special">;</span> <span class="comment">// Cumulative density function.
+</span> <span class="keyword">using</span> <span class="special">::</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">quantile</span><span class="special">;</span>
+
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">noshowpoint</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">fixed</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">left</span><span class="special">;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iomanip</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">;</span>
+
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">limits</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ It is always sensible to use try and catch blocks because defaults
+ policies are to throw an exception if anything goes wrong.
+ </p>
+<p>
+ </p>
+<p>
+ A simple catch block (see below) will ensure that you get a helpful
+ error message instead of an abrupt program abort.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">try</span>
+<span class="special">{</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Selling five candy bars means getting five successes, so successes
+ r = 5. The total number of trials (n, in this case, houses visited)
+ this takes is therefore = sucesses + failures or k + r = k + 5.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">sales_quota</span> <span class="special">=</span> <span class="number">5</span><span class="special">;</span> <span class="comment">// Pat's sales quota - successes (r).</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ At each house, there is a 0.4 probability (40%) of selling one candy
+ bar and a 0.6 probability (60%) of selling nothing.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">success_fraction</span> <span class="special">=</span> <span class="number">0.4</span><span class="special">;</span> <span class="comment">// success_fraction (p) - so failure_fraction is 0.6.</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ The Negative Binomial(r, p) distribution describes the probability
+ of k failures and r successes in k+r Bernoulli(p) trials with success
+ on the last trial. (A <a href="http://en.wikipedia.org/wiki/Bernoulli_distribution" target="_top">Bernoulli
+ trial</a> is one with only two possible outcomes, success of
+ failure, and p is the probability of success).
+ </p>
+<p>
+ </p>
+<p>
+ We therefore start by constructing a negative binomial distribution
+ with parameters sales_quota (required successes) and probability
+ of success.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">negative_binomial</span> <span class="identifier">nb</span><span class="special">(</span><span class="identifier">sales_quota</span><span class="special">,</span> <span class="identifier">success_fraction</span><span class="special">);</span> <span class="comment">// type double by default.</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ To confirm, display the success_fraction &amp; successes parameters
+ of the distribution.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Pat has a sales per house success rate of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">success_fraction</span>
+ <span class="special">&lt;&lt;</span> <span class="string">".\nTherefore he would, on average, sell "</span> <span class="special">&lt;&lt;</span> <span class="identifier">nb</span><span class="special">.</span><span class="identifier">success_fraction</span><span class="special">()</span> <span class="special">*</span> <span class="number">100</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" bars after trying 100 houses."</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+
+<span class="keyword">int</span> <span class="identifier">all_houses</span> <span class="special">=</span> <span class="number">30</span><span class="special">;</span> <span class="comment">// The number of houses on the estate.
+</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"With a success rate of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">nb</span><span class="special">.</span><span class="identifier">success_fraction</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", he might expect, on average,\n"</span>
+ <span class="string">"to need to visit about "</span> <span class="special">&lt;&lt;</span> <span class="identifier">success_fraction</span> <span class="special">*</span> <span class="identifier">all_houses</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" houses in order to sell all "</span> <span class="special">&lt;&lt;</span> <span class="identifier">nb</span><span class="special">.</span><span class="identifier">successes</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">" bars. "</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Pat has a sales per house success rate of 0.4.
+Therefore he would, on average, sell 40 bars after trying 100 houses.
+With a success rate of 0.4, he might expect, on average,
+to need to visit about 12 houses in order to sell all 5 bars.
+</pre>
+<p>
+ </p>
+<p>
+ The random variable of interest is the number of houses that must
+ be visited to sell five candy bars, so we substitute k = n - 5 into
+ a negative_binomial(5, 0.4) and obtain the <a href="../../../dist_ref/nmp.html#math.dist.pdf">probability
+ mass (density) function (pdf or pmf)</a> of the distribution of
+ houses visited. Obviously, the best possible case is that Pat makes
+ sales on all the first five houses.
+ </p>
+<p>
+ </p>
+<p>
+ We calculate this using the pdf function:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability that Pat finishes on the "</span> <span class="special">&lt;&lt;</span> <span class="identifier">sales_quota</span> <span class="special">&lt;&lt;</span> <span class="string">"th house is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">5</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// == pdf(nb, 0)</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Of course, he could not finish on fewer than 5 houses because he
+ must sell 5 candy bars. So the 5th house is the first that he could
+ possibly finish on.
+ </p>
+<p>
+ </p>
+<p>
+ To finish on or before the 8th house, Pat must finish at the 5th,
+ 6th, 7th or 8th house. The probability that he will finish on <span class="bold"><strong>exactly</strong></span> ( == ) on any house is the Probability
+ Density Function (pdf).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability that Pat finishes on the 6th house is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">6</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability that Pat finishes on the 7th house is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">7</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability that Pat finishes on the 8th house is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">8</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability that Pat finishes on the 6th house is 0.03072
+Probability that Pat finishes on the 7th house is 0.055296
+Probability that Pat finishes on the 8th house is 0.077414
+</pre>
+<p>
+ </p>
+<p>
+ The sum of the probabilities for these houses is the Cumulative Distribution
+ Function (cdf). We can calculate it by adding the individual probabilities.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability that Pat finishes on or before the 8th house is sum "</span>
+ <span class="string">"\n"</span> <span class="special">&lt;&lt;</span> <span class="string">"pdf(sales_quota) + pdf(6) + pdf(7) + pdf(8) = "</span>
+ <span class="comment">// Sum each of the mass/density probabilities for houses sales_quota = 5, 6, 7, &amp; 8.
+</span> <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">5</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="comment">// 0 failures.
+</span> <span class="special">+</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">6</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="comment">// 1 failure.
+</span> <span class="special">+</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">7</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="comment">// 2 failures.
+</span> <span class="special">+</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">8</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="comment">// 3 failures.
+</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">pdf(sales_quota) + pdf(6) + pdf(7) + pdf(8) = 0.17367
+</pre>
+<p>
+ </p>
+<p>
+ Or, usually better, by using the negative binomial <span class="bold"><strong>cumulative</strong></span>
+ distribution function.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\nProbability of selling his quota of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">sales_quota</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" bars\non or before the "</span> <span class="special">&lt;&lt;</span> <span class="number">8</span> <span class="special">&lt;&lt;</span> <span class="string">"th house is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">8</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability of selling his quota of 5 bars on or before the 8th house is 0.17367
+</pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\nProbability that Pat finishes exactly on the 10th house is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">10</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\nProbability of selling his quota of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">sales_quota</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" bars\non or before the "</span> <span class="special">&lt;&lt;</span> <span class="number">10</span> <span class="special">&lt;&lt;</span> <span class="string">"th house is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">10</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability that Pat finishes exactly on the 10th house is 0.10033
+Probability of selling his quota of 5 bars on or before the 10th house is 0.3669
+</pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability that Pat finishes exactly on the 11th house is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">11</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\nProbability of selling his quota of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">sales_quota</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" bars\non or before the "</span> <span class="special">&lt;&lt;</span> <span class="number">11</span> <span class="special">&lt;&lt;</span> <span class="string">"th house is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">11</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability that Pat finishes on the 11th house is 0.10033
+Probability of selling his quota of 5 candy bars
+on or before the 11th house is 0.46723
+</pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability that Pat finishes exactly on the 12th house is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">12</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\nProbability of selling his quota of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">sales_quota</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" bars\non or before the "</span> <span class="special">&lt;&lt;</span> <span class="number">12</span> <span class="special">&lt;&lt;</span> <span class="string">"th house is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">12</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability that Pat finishes on the 12th house is 0.094596
+Probability of selling his quota of 5 candy bars
+on or before the 12th house is 0.56182
+</pre>
+<p>
+ </p>
+<p>
+ Finally consider the risk of Pat not selling his quota of 5 bars
+ even after visiting all the houses. Calculate the probability that
+ he <span class="emphasis"><em>will</em></span> sell on or before the last house: Calculate
+ the probability that he would sell all his quota on the very last
+ house.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability that Pat finishes on the "</span> <span class="special">&lt;&lt;</span> <span class="identifier">all_houses</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" house is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="identifier">all_houses</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Probability of selling his quota of 5 bars on the 30th house is
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability that Pat finishes on the 30 house is 0.00069145
+</pre>
+<p>
+ </p>
+<p>
+ when he'd be very unlucky indeed!
+ </p>
+<p>
+ </p>
+<p>
+ What is the probability that Pat exhausts all 30 houses in the neighborhood,
+ and <span class="bold"><strong>still</strong></span> doesn't sell the required
+ 5 candy bars?
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\nProbability of selling his quota of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">sales_quota</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" bars\non or before the "</span> <span class="special">&lt;&lt;</span> <span class="identifier">all_houses</span> <span class="special">&lt;&lt;</span> <span class="string">"th house is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="identifier">all_houses</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability of selling his quota of 5 bars
+on or before the 30th house is 0.99849
+</pre>
+<p>
+ </p>
+<p>
+ /*<code class="computeroutput"><span class="identifier">So</span> <span class="identifier">the</span>
+ <span class="identifier">risk</span> <span class="identifier">of</span>
+ <span class="identifier">failing</span> <span class="identifier">even</span>
+ <span class="identifier">after</span> <span class="identifier">visiting</span>
+ <span class="identifier">all</span> <span class="identifier">the</span>
+ <span class="identifier">houses</span> <span class="identifier">is</span>
+ <span class="number">1</span> <span class="special">-</span>
+ <span class="keyword">this</span> <span class="identifier">probability</span><span class="special">,</span> </code><code class="computeroutput"><span class="number">1</span>
+ <span class="special">-</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="identifier">all_houses</span>
+ <span class="special">-</span> <span class="identifier">sales_quota</span></code><code class="computeroutput">
+ <span class="identifier">But</span> <span class="keyword">using</span>
+ <span class="keyword">this</span> <span class="identifier">expression</span>
+ <span class="identifier">may</span> <span class="identifier">cause</span>
+ <span class="identifier">serious</span> <span class="identifier">inaccuracy</span><span class="special">,</span> <span class="identifier">so</span>
+ <span class="identifier">it</span> <span class="identifier">would</span>
+ <span class="identifier">be</span> <span class="identifier">much</span>
+ <span class="identifier">better</span> <span class="identifier">to</span>
+ <span class="identifier">use</span> <span class="identifier">the</span>
+ <span class="identifier">complement</span> <span class="identifier">of</span>
+ <span class="identifier">the</span> <span class="identifier">cdf</span><span class="special">:</span> <span class="identifier">So</span>
+ <span class="identifier">the</span> <span class="identifier">risk</span>
+ <span class="identifier">of</span> <span class="identifier">failing</span>
+ <span class="identifier">even</span> <span class="identifier">at</span><span class="special">,</span> <span class="keyword">or</span> <span class="identifier">after</span><span class="special">,</span>
+ <span class="identifier">the</span> <span class="number">31</span><span class="identifier">th</span> <span class="special">(</span><span class="identifier">non</span><span class="special">-</span><span class="identifier">existent</span><span class="special">)</span>
+ <span class="identifier">houses</span> <span class="identifier">is</span>
+ <span class="number">1</span> <span class="special">-</span>
+ <span class="keyword">this</span> <span class="identifier">probability</span><span class="special">,</span> </code><code class="computeroutput"><span class="number">1</span>
+ <span class="special">-</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="identifier">all_houses</span>
+ <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span></code>` But using this expression may cause
+ serious inaccuracy. So it would be much better to use the complement
+ of the cdf. Why complements?
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\nProbability of failing to sell his quota of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">sales_quota</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" bars\neven after visiting all "</span> <span class="special">&lt;&lt;</span> <span class="identifier">all_houses</span> <span class="special">&lt;&lt;</span> <span class="string">" houses is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="identifier">all_houses</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability of failing to sell his quota of 5 bars
+even after visiting all 30 houses is 0.0015101
+</pre>
+<p>
+ </p>
+<p>
+ We can also use the quantile (percentile), the inverse of the cdf,
+ to predict which house Pat will finish on. So for the 8th house:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="special">(</span><span class="number">8</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">));</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of meeting sales quota on or before 8th house is "</span><span class="special">&lt;&lt;</span> <span class="identifier">p</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Probability of meeting sales quota on or before 8th house is 0.174
+</pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"If the confidence of meeting sales quota is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">p</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", then the finishing house is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">sales_quota</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+
+<span class="identifier">cout</span><span class="special">&lt;&lt;</span> <span class="string">" quantile(nb, p) = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">If the confidence of meeting sales quota is 0.17367, then the finishing house is 8
+</pre>
+<p>
+ </p>
+<p>
+ Demanding absolute certainty that all 5 will be sold, implies an
+ infinite number of trials. (Of course, there are only 30 houses on
+ the estate, so he can't ever be <span class="bold"><strong>certain</strong></span>
+ of selling his quota).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"If the confidence of meeting sales quota is "</span> <span class="special">&lt;&lt;</span> <span class="number">1.</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", then the finishing house is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">1</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">sales_quota</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// 1.#INF == infinity.</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">If the confidence of meeting sales quota is 1, then the finishing house is 1.#INF
+</pre>
+<p>
+ </p>
+<p>
+ And similarly for a few other probabilities:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"If the confidence of meeting sales quota is "</span> <span class="special">&lt;&lt;</span> <span class="number">0.</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", then the finishing house is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">0.</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">sales_quota</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"If the confidence of meeting sales quota is "</span> <span class="special">&lt;&lt;</span> <span class="number">0.5</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", then the finishing house is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">0.5</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">sales_quota</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"If the confidence of meeting sales quota is "</span> <span class="special">&lt;&lt;</span> <span class="number">1</span> <span class="special">-</span> <span class="number">0.00151</span> <span class="comment">// 30 th
+</span> <span class="special">&lt;&lt;</span> <span class="string">", then the finishing house is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="number">1</span> <span class="special">-</span> <span class="number">0.00151</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">sales_quota</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">If the confidence of meeting sales quota is 0, then the finishing house is 5
+If the confidence of meeting sales quota is 0.5, then the finishing house is 11.337
+If the confidence of meeting sales quota is 0.99849, then the finishing house is 30
+</pre>
+<p>
+ </p>
+<p>
+ Notice that because we chose a discrete quantile policy of real,
+ the result can be an 'unreal' fractional house.
+ </p>
+<p>
+ </p>
+<p>
+ If the opposite is true, we don't want to assume any confidence,
+ then this is tantamount to assuming that all the first sales_quota
+ trials will be successful sales.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"If confidence of meeting quota is zero\n(we assume all houses are successful sales)"</span>
+ <span class="string">", then finishing house is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">sales_quota</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">If confidence of meeting quota is zero (we assume all houses are successful sales), then finishing house is 5
+If confidence of meeting quota is 0, then finishing house is 5
+</pre>
+<p>
+ </p>
+<p>
+ We can list quantiles for a few probabilities:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+ <span class="keyword">double</span> <span class="identifier">ps</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">0.</span><span class="special">,</span> <span class="number">0.001</span><span class="special">,</span> <span class="number">0.01</span><span class="special">,</span> <span class="number">0.05</span><span class="special">,</span> <span class="number">0.1</span><span class="special">,</span> <span class="number">0.5</span><span class="special">,</span> <span class="number">0.9</span><span class="special">,</span> <span class="number">0.95</span><span class="special">,</span> <span class="number">0.99</span><span class="special">,</span> <span class="number">0.999</span><span class="special">,</span> <span class="number">1.</span><span class="special">};</span>
+ <span class="comment">// Confidence as fraction = 1-alpha, as percent = 100 * (1-alpha[i]) %
+</span> <span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="number">3</span><span class="special">);</span>
+ <span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">ps</span><span class="special">)/</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">ps</span><span class="special">[</span><span class="number">0</span><span class="special">]);</span> <span class="identifier">i</span><span class="special">++)</span>
+ <span class="special">{</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"If confidence of meeting quota is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">ps</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", then finishing house is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="identifier">ps</span><span class="special">[</span><span class="identifier">i</span><span class="special">])</span> <span class="special">+</span> <span class="identifier">sales_quota</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">If confidence of meeting quota is 0, then finishing house is 5
+If confidence of meeting quota is 0.001, then finishing house is 5
+If confidence of meeting quota is 0.01, then finishing house is 5
+If confidence of meeting quota is 0.05, then finishing house is 6.2
+If confidence of meeting quota is 0.1, then finishing house is 7.06
+If confidence of meeting quota is 0.5, then finishing house is 11.3
+If confidence of meeting quota is 0.9, then finishing house is 17.8
+If confidence of meeting quota is 0.95, then finishing house is 20.1
+If confidence of meeting quota is 0.99, then finishing house is 24.8
+If confidence of meeting quota is 0.999, then finishing house is 31.1
+If confidence of meeting quota is 1, then finishing house is 1.#INF
+</pre>
+<p>
+ </p>
+<p>
+ We could have applied a ceil function to obtain a 'worst case' integer
+ value for house.
+</p>
+<pre class="programlisting">
+<span class="identifier">ceil</span><span class="special">(</span><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="identifier">ps</span><span class="special">[</span><span class="identifier">i</span><span class="special">]))</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Or, if we had used the default discrete quantile policy, integer_outside,
+ by omitting
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DISCRETE_QUANTILE_POLICY</span> <span class="identifier">real</span></pre>
+<p>
+ we would have achieved the same effect.
+ </p>
+<p>
+ </p>
+<p>
+ The real result gives some suggestion which house is most likely.
+ For example, compare the real and integer_outside for 95% confidence.
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">If confidence of meeting quota is 0.95, then finishing house is 20.1
+If confidence of meeting quota is 0.95, then finishing house is 21
+</pre>
+<p>
+ </p>
+<p>
+ The real value 20.1 is much closer to 20 than 21, so integer_outside
+ is pessimistic. We could also use integer_round_nearest policy to
+ suggest that 20 is more likely.
+ </p>
+<p>
+ </p>
+<p>
+ Finally, we can tabulate the probability for the last sale being
+ exactly on each house.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\nHouse for "</span> <span class="special">&lt;&lt;</span> <span class="identifier">sales_quota</span> <span class="special">&lt;&lt;</span> <span class="string">"th (last) sale. Probability (%)"</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="number">5</span><span class="special">);</span>
+<span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="special">(</span><span class="keyword">int</span><span class="special">)</span><span class="identifier">sales_quota</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="identifier">all_houses</span><span class="special">+</span><span class="number">1</span><span class="special">;</span> <span class="identifier">i</span><span class="special">++)</span>
+<span class="special">{</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">8</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="identifier">i</span> <span class="special">-</span> <span class="identifier">sales_quota</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</spa
n>
+<span class="special">}</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">House for 5 th (last) sale. Probability (%)
+5 0.01024
+6 0.04096
+7 0.096256
+8 0.17367
+9 0.26657
+10 0.3669
+11 0.46723
+12 0.56182
+13 0.64696
+14 0.72074
+15 0.78272
+16 0.83343
+17 0.874
+18 0.90583
+19 0.93039
+20 0.94905
+21 0.96304
+22 0.97342
+23 0.98103
+24 0.98655
+25 0.99053
+26 0.99337
+27 0.99539
+28 0.99681
+29 0.9978
+30 0.99849
+</pre>
+<p>
+ </p>
+<p>
+ As noted above, using a catch block is always a good idea, even if
+ you do not expect to use it.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="special">}</span>
+<span class="keyword">catch</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span><span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span>
+<span class="special">{</span> <span class="comment">// Since we have set an overflow policy of ignore_error,
+</span> <span class="comment">// an overflow exception should never be thrown.
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\nMessage from thrown exception was:\n "</span> <span class="special">&lt;&lt;</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ For example, without a ignore domain error policy, if we asked for
+
+</p>
+<pre class="programlisting">
+<span class="identifier">pdf</span><span class="special">(</span><span class="identifier">nb</span><span class="special">,</span> <span class="special">-</span><span class="number">1</span><span class="special">)</span></pre>
+<p>
+ for example, we would get:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Message from thrown exception was:
+ Error in function boost::math::pdf(const negative_binomial_distribution&lt;double&gt;&amp;, double):
+ Number of failures argument is -1, but must be &gt;= 0 !
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="neg_binom_size_eg.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../neg_binom_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="negative_binomial_example2.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/neg_binom_eg/negative_binomial_example2.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/neg_binom_eg/negative_binomial_example2.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,162 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Negative Binomial Table Printing Example.</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../neg_binom_eg.html" title="Negative Binomial Distribution Examples">
+<link rel="prev" href="negative_binomial_example1.html" title="Negative Binomial Sales Quota Example.">
+<link rel="next" href="../normal_example.html" title="Normal Distribution Examples">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="negative_binomial_example1.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../neg_binom_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../normal_example.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.neg_binom_eg.negative_binomial_example2"></a><a href="negative_binomial_example2.html" title="Negative Binomial Table Printing Example.">
+ Negative Binomial Table Printing Example.</a>
+</h6></div></div></div>
+<p>
+ Example program showing output of a table of values of cdf and pdf
+ for various k failures.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="comment">// Print a table of values that can be used to plot
+</span><span class="comment">// using Excel, or some other superior graphical display tool.
+</span>
+<span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="number">17</span><span class="special">);</span> <span class="comment">// Use max_digits10 precision, the maximum available for a reference table.
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">showpoint</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// include trailing zeros.
+</span><span class="comment">// This is a maximum possible precision for the type (here double) to suit a reference table.
+</span><span class="keyword">int</span> <span class="identifier">maxk</span> <span class="special">=</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="number">2.</span> <span class="special">*</span> <span class="identifier">mynbdist</span><span class="special">.</span><span class="identifier">successes</span><span class="special">()</span> <span class="special">/</span> <span class="identifier">mynbdist</span><span class="special">.</span><span class="identifier">success_fraction</span><span class="special">());</span>
+<span class="comment">// This maxk shows most of the range of interest, probability about 0.0001 to 0.999.
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="string">" k pdf cdf"</span><span class="string">"\n"</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">k</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">k</span> <span class="special">&lt;</span> <span class="identifier">maxk</span><span class="special">;</span> <span class="identifier">k</span><span class="special">++)</span>
+<span class="special">{</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">17</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">showpoint</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">k</span> <span class="special">&lt;&lt;</span> <span class="string">", "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">25</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">mynbdist</span><span class="special">,</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;(</span><span class="identifier">k</span><span class="special">))</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">25</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">mynbdist</span><span class="special">,</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;(</span><span class="identifier">k</span><span class="special">))</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">k</span> <span class="identifier">pdf</span> <span class="identifier">cdf</span>
+ <span class="number">0</span><span class="special">,</span> <span class="number">1.5258789062500000e-005</span> <span class="number">1.5258789062500003e-005</span>
+ <span class="number">1</span><span class="special">,</span> <span class="number">9.1552734375000000e-005</span> <span class="number">0.00010681152343750000</span>
+ <span class="number">2</span><span class="special">,</span> <span class="number">0.00030899047851562522</span> <span class="number">0.00041580200195312500</span>
+ <span class="number">3</span><span class="special">,</span> <span class="number">0.00077247619628906272</span> <span class="number">0.0011882781982421875</span>
+ <span class="number">4</span><span class="special">,</span> <span class="number">0.0015932321548461918</span> <span class="number">0.0027815103530883789</span>
+ <span class="number">5</span><span class="special">,</span> <span class="number">0.0028678178787231476</span> <span class="number">0.0056493282318115234</span>
+ <span class="number">6</span><span class="special">,</span> <span class="number">0.0046602040529251142</span> <span class="number">0.010309532284736633</span>
+ <span class="number">7</span><span class="special">,</span> <span class="number">0.0069903060793876605</span> <span class="number">0.017299838364124298</span>
+ <span class="number">8</span><span class="special">,</span> <span class="number">0.0098301179241389001</span> <span class="number">0.027129956288263202</span>
+ <span class="number">9</span><span class="special">,</span> <span class="number">0.013106823898851871</span> <span class="number">0.040236780187115073</span>
+<span class="number">10</span><span class="special">,</span> <span class="number">0.016711200471036140</span> <span class="number">0.056947980658151209</span>
+<span class="number">11</span><span class="special">,</span> <span class="number">0.020509200578089786</span> <span class="number">0.077457181236241013</span>
+<span class="number">12</span><span class="special">,</span> <span class="number">0.024354675686481652</span> <span class="number">0.10181185692272265</span>
+<span class="number">13</span><span class="special">,</span> <span class="number">0.028101548869017230</span> <span class="number">0.12991340579173993</span>
+<span class="number">14</span><span class="special">,</span> <span class="number">0.031614242477644432</span> <span class="number">0.16152764826938440</span>
+<span class="number">15</span><span class="special">,</span> <span class="number">0.034775666725408917</span> <span class="number">0.19630331499479325</span>
+<span class="number">16</span><span class="special">,</span> <span class="number">0.037492515688331451</span> <span class="number">0.23379583068312471</span>
+<span class="number">17</span><span class="special">,</span> <span class="number">0.039697957787645101</span> <span class="number">0.27349378847076977</span>
+<span class="number">18</span><span class="special">,</span> <span class="number">0.041352039362130305</span> <span class="number">0.31484582783290005</span>
+<span class="number">19</span><span class="special">,</span> <span class="number">0.042440250924291580</span> <span class="number">0.35728607875719176</span>
+<span class="number">20</span><span class="special">,</span> <span class="number">0.042970754060845245</span> <span class="number">0.40025683281803687</span>
+<span class="number">21</span><span class="special">,</span> <span class="number">0.042970754060845225</span> <span class="number">0.44322758687888220</span>
+<span class="number">22</span><span class="special">,</span> <span class="number">0.042482450037426581</span> <span class="number">0.48571003691630876</span>
+<span class="number">23</span><span class="special">,</span> <span class="number">0.041558918514873783</span> <span class="number">0.52726895543118257</span>
+<span class="number">24</span><span class="special">,</span> <span class="number">0.040260202311284021</span> <span class="number">0.56752915774246648</span>
+<span class="number">25</span><span class="special">,</span> <span class="number">0.038649794218832620</span> <span class="number">0.60617895196129912</span>
+<span class="number">26</span><span class="special">,</span> <span class="number">0.036791631035234917</span> <span class="number">0.64297058299653398</span>
+<span class="number">27</span><span class="special">,</span> <span class="number">0.034747651533277427</span> <span class="number">0.67771823452981139</span>
+<span class="number">28</span><span class="special">,</span> <span class="number">0.032575923312447595</span> <span class="number">0.71029415784225891</span>
+<span class="number">29</span><span class="special">,</span> <span class="number">0.030329307911589130</span> <span class="number">0.74062346575384819</span>
+<span class="number">30</span><span class="special">,</span> <span class="number">0.028054609818219924</span> <span class="number">0.76867807557206813</span>
+<span class="number">31</span><span class="special">,</span> <span class="number">0.025792141284492545</span> <span class="number">0.79447021685656061</span>
+<span class="number">32</span><span class="special">,</span> <span class="number">0.023575629142856460</span> <span class="number">0.81804584599941710</span>
+<span class="number">33</span><span class="special">,</span> <span class="number">0.021432390129869489</span> <span class="number">0.83947823612928651</span>
+<span class="number">34</span><span class="special">,</span> <span class="number">0.019383705779220189</span> <span class="number">0.85886194190850684</span>
+<span class="number">35</span><span class="special">,</span> <span class="number">0.017445335201298231</span> <span class="number">0.87630727710980494</span>
+<span class="number">36</span><span class="special">,</span> <span class="number">0.015628112784496322</span> <span class="number">0.89193538989430121</span>
+<span class="number">37</span><span class="special">,</span> <span class="number">0.013938587078064250</span> <span class="number">0.90587397697236549</span>
+<span class="number">38</span><span class="special">,</span> <span class="number">0.012379666154859701</span> <span class="number">0.91825364312722524</span>
+<span class="number">39</span><span class="special">,</span> <span class="number">0.010951243136991251</span> <span class="number">0.92920488626421649</span>
+<span class="number">40</span><span class="special">,</span> <span class="number">0.0096507830144735539</span> <span class="number">0.93885566927869002</span>
+<span class="number">41</span><span class="special">,</span> <span class="number">0.0084738582566109364</span> <span class="number">0.94732952753530097</span>
+<span class="number">42</span><span class="special">,</span> <span class="number">0.0074146259745345548</span> <span class="number">0.95474415350983555</span>
+<span class="number">43</span><span class="special">,</span> <span class="number">0.0064662435824429246</span> <span class="number">0.96121039709227851</span>
+<span class="number">44</span><span class="special">,</span> <span class="number">0.0056212231142827853</span> <span class="number">0.96683162020656122</span>
+<span class="number">45</span><span class="special">,</span> <span class="number">0.0048717266990450708</span> <span class="number">0.97170334690560634</span>
+<span class="number">46</span><span class="special">,</span> <span class="number">0.0042098073105878630</span> <span class="number">0.97591315421619418</span>
+<span class="number">47</span><span class="special">,</span> <span class="number">0.0036275999165703964</span> <span class="number">0.97954075413276465</span>
+<span class="number">48</span><span class="special">,</span> <span class="number">0.0031174686783026818</span> <span class="number">0.98265822281106729</span>
+<span class="number">49</span><span class="special">,</span> <span class="number">0.0026721160099737302</span> <span class="number">0.98533033882104104</span>
+<span class="number">50</span><span class="special">,</span> <span class="number">0.0022846591885275322</span> <span class="number">0.98761499800956853</span>
+<span class="number">51</span><span class="special">,</span> <span class="number">0.0019486798960970148</span> <span class="number">0.98956367790566557</span>
+<span class="number">52</span><span class="special">,</span> <span class="number">0.0016582516423517923</span> <span class="number">0.99122192954801736</span>
+<span class="number">53</span><span class="special">,</span> <span class="number">0.0014079495076571762</span> <span class="number">0.99262987905567457</span>
+<span class="number">54</span><span class="special">,</span> <span class="number">0.0011928461106539983</span> <span class="number">0.99382272516632852</span>
+<span class="number">55</span><span class="special">,</span> <span class="number">0.0010084971662802015</span> <span class="number">0.99483122233260868</span>
+<span class="number">56</span><span class="special">,</span> <span class="number">0.00085091948404891532</span> <span class="number">0.99568214181665760</span>
+<span class="number">57</span><span class="special">,</span> <span class="number">0.00071656377604119542</span> <span class="number">0.99639870559269883</span>
+<span class="number">58</span><span class="special">,</span> <span class="number">0.00060228420831048650</span> <span class="number">0.99700098980100937</span>
+<span class="number">59</span><span class="special">,</span> <span class="number">0.00050530624256557675</span> <span class="number">0.99750629604357488</span>
+<span class="number">60</span><span class="special">,</span> <span class="number">0.00042319397814867202</span> <span class="number">0.99792949002172360</span>
+<span class="number">61</span><span class="special">,</span> <span class="number">0.00035381791615708398</span> <span class="number">0.99828330793788067</span>
+<span class="number">62</span><span class="special">,</span> <span class="number">0.00029532382517950324</span> <span class="number">0.99857863176306016</span>
+<span class="number">63</span><span class="special">,</span> <span class="number">0.00024610318764958566</span> <span class="number">0.99882473495070978</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="negative_binomial_example1.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../neg_binom_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../normal_example.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/normal_example.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/normal_example.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,47 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Normal Distribution Examples</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../weg.html" title="Worked Examples">
+<link rel="prev" href="neg_binom_eg/negative_binomial_example2.html" title="Negative Binomial Table Printing Example.">
+<link rel="next" href="normal_example/normal_misc.html" title="Some Miscellaneous Examples of the Normal (Gaussian) Distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="neg_binom_eg/negative_binomial_example2.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="normal_example/normal_misc.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.normal_example"></a><a href="normal_example.html" title="Normal Distribution Examples"> Normal
+ Distribution Examples</a>
+</h5></div></div></div>
+<div class="toc"><dl><dt><span class="section"><a href="normal_example/normal_misc.html">
+ Some Miscellaneous Examples of the Normal (Gaussian) Distribution</a></span></dt></dl></div>
+<p>
+ (See also the reference documentation for the <a href="../../dist_ref/dists/normal_dist.html" title="Normal (Gaussian) Distribution">Normal
+ Distribution</a>.)
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="neg_binom_eg/negative_binomial_example2.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="normal_example/normal_misc.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/normal_example/normal_misc.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/normal_example/normal_misc.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,811 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Some Miscellaneous Examples of the Normal (Gaussian) Distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../normal_example.html" title="Normal Distribution Examples">
+<link rel="prev" href="../normal_example.html" title="Normal Distribution Examples">
+<link rel="next" href="../error_eg.html" title="Error Handling Example">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../normal_example.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../normal_example.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../error_eg.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.normal_example.normal_misc"></a><a href="normal_misc.html" title="Some Miscellaneous Examples of the Normal (Gaussian) Distribution">
+ Some Miscellaneous Examples of the Normal (Gaussian) Distribution</a>
+</h6></div></div></div>
+<p>
+ The sample program normal_misc_examples.cpp
+ illustrates their use.
+ </p>
+<a name="math_toolkit.dist.stat_tut.weg.normal_example.normal_misc.traditional_tables"></a><h5>
+<a name="id546641"></a>
+ <a href="normal_misc.html#math_toolkit.dist.stat_tut.weg.normal_example.normal_misc.traditional_tables">Traditional
+ Tables</a>
+ </h5>
+<p>
+ </p>
+<p>
+ First we need some includes to access the normal distribution (and
+ some std output of course).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">normal</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// for normal_distribution
+</span> <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">normal</span><span class="special">;</span> <span class="comment">// typedef provides default type is double.
+</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">left</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">showpoint</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">noshowpoint</span><span class="special">;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iomanip</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">limits</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">;</span>
+
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Example: Normal distribution, Miscellaneous Applications."</span><span class="special">;</span>
+
+ <span class="keyword">try</span>
+ <span class="special">{</span>
+ <span class="special">{</span> <span class="comment">// Traditional tables and values.</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Let's start by printing some traditional tables.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">step</span> <span class="special">=</span> <span class="number">1.</span><span class="special">;</span> <span class="comment">// in z
+</span><span class="keyword">double</span> <span class="identifier">range</span> <span class="special">=</span> <span class="number">4</span><span class="special">;</span> <span class="comment">// min and max z = -range to +range.
+</span><span class="keyword">int</span> <span class="identifier">precision</span> <span class="special">=</span> <span class="number">17</span><span class="special">;</span> <span class="comment">// traditional tables are only computed to much lower precision.
+</span>
+<span class="comment">// Construct a standard normal distribution s
+</span> <span class="identifier">normal</span> <span class="identifier">s</span><span class="special">;</span> <span class="comment">// (default mean = zero, and standard deviation = unity)
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Standard normal distribution, mean = "</span><span class="special">&lt;&lt;</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">mean</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", standard deviation = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ First the probability distribution function (pdf).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability distribution function values"</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">" z "</span> <span class="string">" pdf "</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="number">5</span><span class="special">);</span>
+<span class="keyword">for</span> <span class="special">(</span><span class="keyword">double</span> <span class="identifier">z</span> <span class="special">=</span> <span class="special">-</span><span class="identifier">range</span><span class="special">;</span> <span class="identifier">z</span> <span class="special">&lt;</span> <span class="identifier">range</span> <span class="special">+</span> <span class="identifier">step</span><span class="special">;</span> <span class="identifier">z</span> <span class="special">+=</span> <span class="identifier">step</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">6</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="identifier">precision</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">12</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+<span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="number">6</span><span class="special">);</span> <span class="comment">// default</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ And the area under the normal curve from -&#8734; up to z, the cumulative
+ distribution function (cdf).
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="comment">// For a standard normal distribution
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Standard normal mean = "</span><span class="special">&lt;&lt;</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">mean</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", standard deviation = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Integral (area under the curve) from - infinity up to z "</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">" z "</span> <span class="string">" cdf "</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="keyword">for</span> <span class="special">(</span><span class="keyword">double</span> <span class="identifier">z</span> <span class="special">=</span> <span class="special">-</span><span class="identifier">range</span><span class="special">;</span> <span class="identifier">z</span> <span class="special">&lt;</span> <span class="identifier">range</span> <span class="special">+</span> <span class="identifier">step</span><span class="special">;</span> <span class="identifier">z</span> <span class="special">+=</span> <span class="identifier">step</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">6</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="identifier">precision</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">12</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+<span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="number">6</span><span class="special">);</span> <span class="comment">// default</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ And all this you can do with a nanoscopic amount of work compared
+ to the team of <span class="bold"><strong>human computers</strong></span> toiling
+ with Milton Abramovitz and Irene Stegen at the US National Bureau
+ of Standards (now NIST). Starting
+ in 1938, their "Handbook of Mathematical Functions with Formulas,
+ Graphs and Mathematical Tables", was eventually published in
+ 1964, and has been reprinted numerous times since. (A major replacement
+ is planned at <a href="http://dlmf.nist.gov" target="_top">Digital Library of
+ Mathematical Functions</a>).
+ </p>
+<p>
+ </p>
+<p>
+ Pretty-printing a traditional 2-dimensional table is left as an exercise
+ for the student, but why bother now that the Math Toolkit lets you
+ write
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">z</span> <span class="special">=</span> <span class="number">2.</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Area for z = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span> <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// to get the area for z.</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Correspondingly, we can obtain the traditional 'critical' values
+ for significance levels. For the 95% confidence level, the significance
+ level usually called alpha, is 0.05 = 1 - 0.95 (for a one-sided test),
+ so we can write
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"95% of area has a z below "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="number">0.95</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// 95% of area has a z below 1.64485</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ and a two-sided test (a comparison between two levels, rather than
+ a one-sided test)
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"95% of area has a z between "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="number">0.975</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" and "</span> <span class="special">&lt;&lt;</span> <span class="special">-</span><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="number">0.975</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// 95% of area has a z between 1.95996 and -1.95996</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ First, define a table of significance levels: these are the probabilities
+ that the true occurrence frequency lies outside the calculated interval.
+ </p>
+<p>
+ </p>
+<p>
+ It is convenient to have an alpha level for the probability that
+ z lies outside just one standard deviation. This will not be some
+ nice neat number like 0.05, but we can easily calculate it,
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">alpha1</span> <span class="special">=</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="special">-</span><span class="number">1</span><span class="special">)</span> <span class="special">*</span> <span class="number">2</span><span class="special">;</span> <span class="comment">// 0.3173105078629142
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">17</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">"Significance level for z == 1 is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">alpha1</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ and place in our array of favorite alpha values.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">alpha</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">0.3173105078629142</span><span class="special">,</span> <span class="comment">// z for 1 standard deviation.
+</span> <span class="number">0.20</span><span class="special">,</span> <span class="number">0.1</span><span class="special">,</span> <span class="number">0.05</span><span class="special">,</span> <span class="number">0.01</span><span class="special">,</span> <span class="number">0.001</span><span class="special">,</span> <span class="number">0.0001</span><span class="special">,</span> <span class="number">0.00001</span> <span class="special">};</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Confidence value as % is (1 - alpha) * 100 (so alpha 0.05 == 95%
+ confidence) that the true occurrence frequency lies <span class="bold"><strong>inside</strong></span>
+ the calculated interval.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"level of significance (alpha)"</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">4</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"2-sided 1 -sided z(alpha) "</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="keyword">for</span> <span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">)/</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">[</span><span class="number">0</span><span class="special">]);</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">15</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">15</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> <span class="special">/</span><span class="number">2</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class=
"special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]/</span><span class="number">2</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+ <span class="comment">// Use quantile(complement(s, alpha[i]/2)) to avoid potential loss of accuracy from quantile(s, 1 - alpha[i]/2)
+</span><span class="special">}</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Notice the distinction between one-sided (also called one-tailed)
+ where we are using a &gt; <span class="bold"><strong>or</strong></span> &lt;
+ test (and not both) and considering the area of the tail (integral)
+ from z up to +&#8734;, and a two-sided test where we are using two &gt;
+ <span class="bold"><strong>and</strong></span> &lt; tests, and thus considering
+ two tails, from -&#8734; up to z low and z high up to +&#8734;.
+ </p>
+<p>
+ </p>
+<p>
+ So the 2-sided values alpha[i] are calculated using alpha[i]/2.
+ </p>
+<p>
+ </p>
+<p>
+ If we consider a simple example of alpha = 0.05, then for a two-sided
+ test, the lower tail area from -&#8734; up to -1.96 is 0.025 (alpha/2) and
+ the upper tail area from +z up to +1.96 is also 0.025 (alpha/2),
+ and the area between -1.96 up to 12.96 is alpha = 0.95. and the sum
+ of the two tails is 0.025 + 0.025 = 0.05,
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<a name="math_toolkit.dist.stat_tut.weg.normal_example.normal_misc.standard_deviations_either_side_of_the_mean"></a><h5>
+<a name="id549817"></a>
+ <a href="normal_misc.html#math_toolkit.dist.stat_tut.weg.normal_example.normal_misc.standard_deviations_either_side_of_the_mean">Standard
+ deviations either side of the Mean</a>
+ </h5>
+<p>
+ </p>
+<p>
+ Armed with the cumulative distribution function, we can easily calculate
+ the easy to remember proportion of values that lie within 1, 2 and
+ 3 standard deviations from the mean.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="number">3</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">showpoint</span> <span class="special">&lt;&lt;</span> <span class="string">"cdf(s, s.standard_deviation()) = "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">())</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// from -infinity to 1 sd
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"cdf(complement(s, s.standard_deviation())) = "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Fraction 1 standard deviation within either side of mean is "</span>
+ <span class="special">&lt;&lt;</span> <span class="number">1</span> <span class="special">-</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()))</span> <span class="special">*</span> <span class="number">2</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Fraction 2 standard deviations within either side of mean is "</span>
+ <span class="special">&lt;&lt;</span> <span class="number">1</span> <span class="special">-</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="number">2</span> <span class="special">*</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()))</span> <span class="special">*</span> <span class="number">2</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Fraction 3 standard deviations within either side of mean is "</span>
+ <span class="special">&lt;&lt;</span> <span class="number">1</span> <span class="special">-</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="number">3</span> <span class="special">*</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()))</span> <span class="special">*</span> <span class="number">2</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ To a useful precision, the 1, 2 &amp; 3 percentages are 68, 95 and
+ 99.7, and these are worth memorising as useful 'rules of thumb',
+ as, for example, in <a href="http://en.wikipedia.org/wiki/Standard_deviation" target="_top">standard
+ deviation</a>:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Fraction 1 standard deviation within either side of mean is 0.683
+Fraction 2 standard deviations within either side of mean is 0.954
+Fraction 3 standard deviations within either side of mean is 0.997
+</pre>
+<p>
+ </p>
+<p>
+ We could of course get some really accurate values for these <a href="http://en.wikipedia.org/wiki/Confidence_interval" target="_top">confidence
+ intervals</a> by using cout.precision(15);
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Fraction 1 standard deviation within either side of mean is 0.682689492137086
+Fraction 2 standard deviations within either side of mean is 0.954499736103642
+Fraction 3 standard deviations within either side of mean is 0.997300203936740
+</pre>
+<p>
+ </p>
+<p>
+ But before you get too excited about this impressive precision, don't
+ forget that the <span class="bold"><strong>confidence intervals of the
+ standard deviation</strong></span> are surprisingly wide, especially if
+ you have estimated the standard deviation from only a few measurements.
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<a name="math_toolkit.dist.stat_tut.weg.normal_example.normal_misc.some_simple_examples"></a><h5>
+<a name="id550554"></a>
+ <a href="normal_misc.html#math_toolkit.dist.stat_tut.weg.normal_example.normal_misc.some_simple_examples">Some
+ simple examples</a>
+ </h5>
+<a name="math_toolkit.dist.stat_tut.weg.normal_example.normal_misc.life_of_light_bulbs"></a><h5>
+<a name="id550580"></a>
+ <a href="normal_misc.html#math_toolkit.dist.stat_tut.weg.normal_example.normal_misc.life_of_light_bulbs">Life
+ of light bulbs</a>
+ </h5>
+<p>
+ </p>
+<p>
+ Examples from K. Krishnamoorthy, Handbook of Statistical Distributions
+ with Applications, ISBN 1 58488 635 8, page 125... implemented using
+ the Math Toolkit library.
+ </p>
+<p>
+ </p>
+<p>
+ A few very simple examples are shown here:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="comment">// K. Krishnamoorthy, Handbook of Statistical Distributions with Applications,
+</span> <span class="comment">// ISBN 1 58488 635 8, page 125, example 10.3.5</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Mean lifespan of 100 W bulbs is 1100 h with standard deviation of
+ 100 h. Assuming, perhaps with little evidence and much faith, that
+ the distribution is normal, we construct a normal distribution called
+ <span class="emphasis"><em>bulbs</em></span> with these values:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">mean_life</span> <span class="special">=</span> <span class="number">1100.</span><span class="special">;</span>
+<span class="keyword">double</span> <span class="identifier">life_standard_deviation</span> <span class="special">=</span> <span class="number">100.</span><span class="special">;</span>
+<span class="identifier">normal</span> <span class="identifier">bulbs</span><span class="special">(</span><span class="identifier">mean_life</span><span class="special">,</span> <span class="identifier">life_standard_deviation</span><span class="special">);</span>
+<span class="keyword">double</span> <span class="identifier">expected_life</span> <span class="special">=</span> <span class="number">1000.</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ The we can use the Cumulative distribution function to predict fractions
+ (or percentages, if * 100) that will last various lifetimes.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Fraction of bulbs that will last at best (&lt;=) "</span> <span class="comment">// P(X &lt;= 1000)
+</span> <span class="special">&lt;&lt;</span> <span class="identifier">expected_life</span> <span class="special">&lt;&lt;</span> <span class="string">" is "</span><span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">bulbs</span><span class="special">,</span> <span class="identifier">expected_life</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Fraction of bulbs that will last at least (&gt;) "</span> <span class="comment">// P(X &gt; 1000)
+</span> <span class="special">&lt;&lt;</span> <span class="identifier">expected_life</span> <span class="special">&lt;&lt;</span> <span class="string">" is "</span><span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">bulbs</span><span class="special">,</span> <span class="identifier">expected_life</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="keyword">double</span> <span class="identifier">min_life</span> <span class="special">=</span> <span class="number">900</span><span class="special">;</span>
+<span class="keyword">double</span> <span class="identifier">max_life</span> <span class="special">=</span> <span class="number">1200</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Fraction of bulbs that will last between "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">min_life</span> <span class="special">&lt;&lt;</span> <span class="string">" and "</span> <span class="special">&lt;&lt;</span> <span class="identifier">max_life</span> <span class="special">&lt;&lt;</span> <span class="string">" is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">bulbs</span><span class="special">,</span> <span class="identifier">max_life</span><span class="special">)</span> <span class="comment">// P(X &lt;= 1200)
+</span> <span class="special">-</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">bulbs</span><span class="special">,</span> <span class="identifier">min_life</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// P(X &lt;= 900)</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ Real-life failures are often very ab-normal, with a significant
+ number that 'dead-on-arrival' or suffer failure very early in their
+ life: the lifetime of the survivors of 'early mortality' may be
+ well described by the normal distribution.
+ </p></td></tr>
+</table></div>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<a name="math_toolkit.dist.stat_tut.weg.normal_example.normal_misc.how_many_onions_"></a><h5>
+<a name="id551290"></a>
+ <a href="normal_misc.html#math_toolkit.dist.stat_tut.weg.normal_example.normal_misc.how_many_onions_">How
+ many onions?</a>
+ </h5>
+<p>
+ </p>
+<p>
+ Weekly demand for 5 lb sacks of onions at a store is normally distributed
+ with mean 140 sacks and standard deviation 10.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">mean</span> <span class="special">=</span> <span class="number">140.</span><span class="special">;</span> <span class="comment">// sacks per week.
+</span><span class="keyword">double</span> <span class="identifier">standard_deviation</span> <span class="special">=</span> <span class="number">10</span><span class="special">;</span>
+<span class="identifier">normal</span> <span class="identifier">sacks</span><span class="special">(</span><span class="identifier">mean</span><span class="special">,</span> <span class="identifier">standard_deviation</span><span class="special">);</span>
+
+<span class="keyword">double</span> <span class="identifier">stock</span> <span class="special">=</span> <span class="number">160.</span><span class="special">;</span> <span class="comment">// per week.
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Percentage of weeks overstocked "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">sacks</span><span class="special">,</span> <span class="identifier">stock</span><span class="special">)</span> <span class="special">*</span> <span class="number">100.</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// P(X &lt;=160)
+</span><span class="comment">// Percentage of weeks overstocked 97.7</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ So there will be lots of mouldy onions! So we should be able to say
+ what stock level will meet demand 95% of the weeks.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">stock_95</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">sacks</span><span class="special">,</span> <span class="number">0.95</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Store should stock "</span> <span class="special">&lt;&lt;</span> <span class="keyword">int</span><span class="special">(</span><span class="identifier">stock_95</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" sacks to meet 95% of demands."</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ And it is easy to estimate how to meet 80% of demand, and waste even
+ less.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">stock_80</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">sacks</span><span class="special">,</span> <span class="number">0.80</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Store should stock "</span> <span class="special">&lt;&lt;</span> <span class="keyword">int</span><span class="special">(</span><span class="identifier">stock_80</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" sacks to meet 8 out of 10 demands."</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<a name="math_toolkit.dist.stat_tut.weg.normal_example.normal_misc.packing_beef"></a><h5>
+<a name="id551872"></a>
+ <a href="normal_misc.html#math_toolkit.dist.stat_tut.weg.normal_example.normal_misc.packing_beef">Packing
+ beef</a>
+ </h5>
+<p>
+ </p>
+<p>
+ A machine is set to pack 3 kg of ground beef per pack. Over a long
+ period of time it is found that the average packed was 3 kg with
+ a standard deviation of 0.1 kg. Assuming the packing is normally
+ distributed, we can find the fraction (or %) of packages that weigh
+ more than 3.1 kg.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">mean</span> <span class="special">=</span> <span class="number">3.</span><span class="special">;</span> <span class="comment">// kg
+</span><span class="keyword">double</span> <span class="identifier">standard_deviation</span> <span class="special">=</span> <span class="number">0.1</span><span class="special">;</span> <span class="comment">// kg
+</span><span class="identifier">normal</span> <span class="identifier">packs</span><span class="special">(</span><span class="identifier">mean</span><span class="special">,</span> <span class="identifier">standard_deviation</span><span class="special">);</span>
+
+<span class="keyword">double</span> <span class="identifier">max_weight</span> <span class="special">=</span> <span class="number">3.1</span><span class="special">;</span> <span class="comment">// kg
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Percentage of packs &gt; "</span> <span class="special">&lt;&lt;</span> <span class="identifier">max_weight</span> <span class="special">&lt;&lt;</span> <span class="string">" is "</span>
+<span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">packs</span><span class="special">,</span> <span class="identifier">max_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// P(X &gt; 3.1)
+</span>
+<span class="keyword">double</span> <span class="identifier">under_weight</span> <span class="special">=</span> <span class="number">2.9</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span><span class="string">"fraction of packs &lt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">under_weight</span> <span class="special">&lt;&lt;</span> <span class="string">" with a mean of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">mean</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">packs</span><span class="special">,</span> <span class="identifier">under_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// fraction of packs &lt;= 2.9 with a mean of 3 is 0.841345
+</span><span class="comment">// This is 0.84 - more than the target 0.95
+</span><span class="comment">// Want 95% to be over this weight, so what should we set the mean weight to be?
+</span><span class="comment">// KK StatCalc says:
+</span><span class="keyword">double</span> <span class="identifier">over_mean</span> <span class="special">=</span> <span class="number">3.0664</span><span class="special">;</span>
+<span class="identifier">normal</span> <span class="identifier">xpacks</span><span class="special">(</span><span class="identifier">over_mean</span><span class="special">,</span> <span class="identifier">standard_deviation</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"fraction of packs &gt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">under_weight</span>
+<span class="special">&lt;&lt;</span> <span class="string">" with a mean of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">xpacks</span><span class="special">.</span><span class="identifier">mean</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">xpacks</span><span class="special">,</span> <span class="identifier">under_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">// fraction of packs &gt;= 2.9 with a mean of 3.06449 is 0.950005
+</span><span class="keyword">double</span> <span class="identifier">under_fraction</span> <span class="special">=</span> <span class="number">0.05</span><span class="special">;</span> <span class="comment">// so 95% are above the minimum weight mean - sd = 2.9
+</span><span class="keyword">double</span> <span class="identifier">low_limit</span> <span class="special">=</span> <span class="identifier">standard_deviation</span><span class="special">;</span>
+<span class="keyword">double</span> <span class="identifier">offset</span> <span class="special">=</span> <span class="identifier">mean</span> <span class="special">-</span> <span class="identifier">low_limit</span> <span class="special">-</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">packs</span><span class="special">,</span> <span class="identifier">under_fraction</span><span class="special">);</span>
+<span class="keyword">double</span> <span class="identifier">nominal_mean</span> <span class="special">=</span> <span class="identifier">mean</span> <span class="special">+</span> <span class="identifier">offset</span><span class="special">;</span>
+
+<span class="identifier">normal</span> <span class="identifier">nominal_packs</span><span class="special">(</span><span class="identifier">nominal_mean</span><span class="special">,</span> <span class="identifier">standard_deviation</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Setting the packer to "</span> <span class="special">&lt;&lt;</span> <span class="identifier">nominal_mean</span> <span class="special">&lt;&lt;</span> <span class="string">" will mean that "</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"fraction of packs &gt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">under_weight</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">nominal_packs</span><span class="special">,</span> <span class="identifier">under_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Setting the packer to 3.06449 will mean that fraction of packs &gt;=
+ 2.9 is 0.95.
+ </p>
+<p>
+ </p>
+<p>
+ Setting the packer to 3.13263 will mean that fraction of packs &gt;=
+ 2.9 is 0.99, but will more than double the mean loss from 0.0644
+ to 0.133.
+ </p>
+<p>
+ </p>
+<p>
+ Alternatively, we could invest in a better (more precise) packer
+ with a lower standard deviation.
+ </p>
+<p>
+ </p>
+<p>
+ To estimate how much better (how much smaller standard deviation)
+ it would have to be, we need to get the 5% quantile to be located
+ at the under_weight limit, 2.9
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">p</span> <span class="special">=</span> <span class="number">0.05</span><span class="special">;</span> <span class="comment">// wanted p th quantile.
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Quantile of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">p</span> <span class="special">&lt;&lt;</span> <span class="string">" = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">packs</span><span class="special">,</span> <span class="identifier">p</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">packs</span><span class="special">.</span><span class="identifier">mean</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">", sd = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">packs</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">//</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Quantile of 0.05 = 2.83551, mean = 3, sd = 0.1
+ </p>
+<p>
+ </p>
+<p>
+ With the current packer (mean = 3, sd = 0.1), the 5% quantile is
+ at 2.8551 kg, a little below our target of 2.9 kg. So we know that
+ the standard deviation is going to have to be smaller.
+ </p>
+<p>
+ </p>
+<p>
+ Let's start by guessing that it (now 0.1) needs to be halved, to
+ a standard deviation of 0.05
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">normal</span> <span class="identifier">pack05</span><span class="special">(</span><span class="identifier">mean</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Quantile of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">p</span> <span class="special">&lt;&lt;</span> <span class="string">" = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">pack05</span><span class="special">,</span> <span class="identifier">p</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pack05</span><span class="special">.</span><span class="identifier">mean</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">", sd = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pack05</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span><span class="string">"Fraction of packs &gt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">under_weight</span> <span class="special">&lt;&lt;</span> <span class="string">" with a mean of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">mean</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" and standard deviation of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pack05</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">pack05</span><span class="special">,</span> <span class="identifier">under_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">//</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Fraction of packs &gt;= 2.9 with a mean of 3 and standard deviation
+ of 0.05 is 0.9772
+ </p>
+<p>
+ </p>
+<p>
+ So 0.05 was quite a good guess, but we are a little over the 2.9
+ target, so the standard deviation could be a tiny bit more. So we
+ could do some more guessing to get closer, say by increasing to 0.06
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">normal</span> <span class="identifier">pack06</span><span class="special">(</span><span class="identifier">mean</span><span class="special">,</span> <span class="number">0.06</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Quantile of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">p</span> <span class="special">&lt;&lt;</span> <span class="string">" = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">pack06</span><span class="special">,</span> <span class="identifier">p</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="string">", mean = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pack06</span><span class="special">.</span><span class="identifier">mean</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">", sd = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pack06</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span><span class="string">"Fraction of packs &gt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">under_weight</span> <span class="special">&lt;&lt;</span> <span class="string">" with a mean of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">mean</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" and standard deviation of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pack06</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">pack06</span><span class="special">,</span> <span class="identifier">under_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Fraction of packs &gt;= 2.9 with a mean of 3 and standard deviation
+ of 0.06 is 0.9522
+ </p>
+<p>
+ </p>
+<p>
+ Now we are getting really close, but to do the job properly, we could
+ use root finding method, for example the tools provided, and used
+ elsewhere, in the Math Toolkit, see <a href="../../../../toolkit/internals1/roots2.html" title="Root Finding Without Derivatives">Root
+ Finding Without Derivatives</a>.
+ </p>
+<p>
+ </p>
+<p>
+ But in this normal distribution case, we could be even smarter and
+ make a direct calculation.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">normal</span> <span class="identifier">s</span><span class="special">;</span> <span class="comment">// For standard normal distribution,
+</span><span class="keyword">double</span> <span class="identifier">sd</span> <span class="special">=</span> <span class="number">0.1</span><span class="special">;</span>
+<span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">2.9</span><span class="special">;</span> <span class="comment">// Our required limit.
+</span><span class="comment">// then probability p = N((x - mean) / sd)
+</span><span class="comment">// So if we want to find the standard deviation that would be required to meet this limit,
+</span><span class="comment">// so that the p th quantile is located at x,
+</span><span class="comment">// in this case the 0.95 (95%) quantile at 2.9 kg pack weight, when the mean is 3 kg.
+</span>
+<span class="keyword">double</span> <span class="identifier">prob</span> <span class="special">=</span> <span class="identifier">pdf</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="special">(</span><span class="identifier">x</span> <span class="special">-</span> <span class="identifier">mean</span><span class="special">)</span> <span class="special">/</span> <span class="identifier">sd</span><span class="special">);</span>
+<span class="keyword">double</span> <span class="identifier">qp</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="number">0.95</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"prob = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">prob</span> <span class="special">&lt;&lt;</span> <span class="string">", quantile(p) "</span> <span class="special">&lt;&lt;</span> <span class="identifier">qp</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// p = 0.241971, quantile(p) 1.64485
+</span><span class="comment">// Rearranging, we can directly calculate the required standard deviation:
+</span><span class="keyword">double</span> <span class="identifier">sd95</span> <span class="special">=</span> <span class="identifier">abs</span><span class="special">((</span><span class="identifier">x</span> <span class="special">-</span> <span class="identifier">mean</span><span class="special">))</span> <span class="special">/</span> <span class="identifier">qp</span><span class="special">;</span>
+
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"If we want the "</span><span class="special">&lt;&lt;</span> <span class="identifier">p</span> <span class="special">&lt;&lt;</span> <span class="string">" th quantile to be located at "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">x</span> <span class="special">&lt;&lt;</span> <span class="string">", would need a standard deviation of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">sd95</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+
+<span class="identifier">normal</span> <span class="identifier">pack95</span><span class="special">(</span><span class="identifier">mean</span><span class="special">,</span> <span class="identifier">sd95</span><span class="special">);</span> <span class="comment">// Distribution of the 'ideal better' packer.
+</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span><span class="string">"Fraction of packs &gt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">under_weight</span> <span class="special">&lt;&lt;</span> <span class="string">" with a mean of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">mean</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" and standard deviation of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">pack95</span><span class="special">.</span><span class="identifier">standard_deviation</span><span class="special">()</span>
+ <span class="special">&lt;&lt;</span> <span class="string">" is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">pack95</span><span class="special">,</span> <span class="identifier">under_weight</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+
+<span class="comment">// Fraction of packs &gt;= 2.9 with a mean of 3 and standard deviation of 0.0608 is 0.95</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Notice that these two deceptively simple questions (do we over-fill
+ or measure better) are actually very common. The weight of beef might
+ be replaced by a measurement of more or less anything. But the calculations
+ rely on the accuracy of the standard deviation - something that is
+ almost always less good than we might wish, especially if based on
+ a few measurements. </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<a name="math_toolkit.dist.stat_tut.weg.normal_example.normal_misc.length_of_bolts"></a><h5>
+<a name="id554882"></a>
+ <a href="normal_misc.html#math_toolkit.dist.stat_tut.weg.normal_example.normal_misc.length_of_bolts">Length
+ of bolts</a>
+ </h5>
+<p>
+ </p>
+<p>
+ A bolt is usable if between 3.9 and 4.1 long. From a large batch
+ of bolts, a sample of 50 show a mean length of 3.95 with standard
+ deviation 0.1. Assuming a normal distribution, what proportion is
+ usable? The true sample mean is unknown, but we can use the sample
+ mean and standard deviation to find approximate solutions.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+ <span class="identifier">normal</span> <span class="identifier">bolts</span><span class="special">(</span><span class="number">3.95</span><span class="special">,</span> <span class="number">0.1</span><span class="special">);</span>
+ <span class="keyword">double</span> <span class="identifier">top</span> <span class="special">=</span> <span class="number">4.1</span><span class="special">;</span>
+ <span class="keyword">double</span> <span class="identifier">bottom</span> <span class="special">=</span> <span class="number">3.9</span><span class="special">;</span>
+
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Fraction long enough [ P(X &lt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">top</span> <span class="special">&lt;&lt;</span> <span class="string">") ] is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">bolts</span><span class="special">,</span> <span class="identifier">top</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Fraction too short [ P(X &lt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">bottom</span> <span class="special">&lt;&lt;</span> <span class="string">") ] is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">bolts</span><span class="special">,</span> <span class="identifier">bottom</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Fraction OK -between "</span> <span class="special">&lt;&lt;</span> <span class="identifier">bottom</span> <span class="special">&lt;&lt;</span> <span class="string">" and "</span> <span class="special">&lt;&lt;</span> <span class="identifier">top</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"[ P(X &lt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">top</span> <span class="special">&lt;&lt;</span> <span class="string">") - P(X&lt;= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">bottom</span> <span class="special">&lt;&lt;</span> <span class="string">" ) ] is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">bolts</span><span class="special">,</span> <span class="identifier">top</span><span class="special">)</span> <span class="special">-</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">bolts</span><span class="special">,</span> <span class="identifier">bottom</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Fraction too long [ P(X &gt; "</span> <span class="special">&lt;&lt;</span> <span class="identifier">top</span> <span class="special">&lt;&lt;</span> <span class="string">") ] is "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">bolts</span><span class="special">,</span> <span class="identifier">top</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"95% of bolts are shorter than "</span> <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">bolts</span><span class="special">,</span> <span class="number">0.95</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../normal_example.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../normal_example.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../error_eg.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,54 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Student's t Distribution Examples</title>
+<link rel="stylesheet" href="../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../weg.html" title="Worked Examples">
+<link rel="prev" href="dist_construct_eg.html" title="Distribution Construction Example">
+<link rel="next" href="st_eg/tut_mean_intervals.html" title="Calculating confidence intervals on the mean with the Students-t distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="dist_construct_eg.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="st_eg/tut_mean_intervals.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.st_eg"></a><a href="st_eg.html" title="Student's t Distribution Examples"> Student's
+ t Distribution Examples</a>
+</h5></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="st_eg/tut_mean_intervals.html">
+ Calculating confidence intervals on the mean with the Students-t distribution</a></span></dt>
+<dt><span class="section"><a href="st_eg/tut_mean_test.html">
+ Testing a sample mean for difference from a "true" mean</a></span></dt>
+<dt><span class="section"><a href="st_eg/tut_mean_size.html">
+ Estimating how large a sample size would have to become in order to give
+ a significant Students-t test result with a single sample test</a></span></dt>
+<dt><span class="section"><a href="st_eg/two_sample_students_t.html">
+ Comparing the means of two samples with the Students-t test</a></span></dt>
+<dt><span class="section"><a href="st_eg/paired_st.html">
+ Comparing two paired samples with the Student's t distribution</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="dist_construct_eg.html"><img src="../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.html"><img src="../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="st_eg/tut_mean_intervals.html"><img src="../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg/paired_st.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg/paired_st.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,75 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Comparing two paired samples with the Student's t distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../st_eg.html" title="Student's t Distribution Examples">
+<link rel="prev" href="two_sample_students_t.html" title="Comparing the means of two samples with the Students-t test">
+<link rel="next" href="../cs_eg.html" title="Chi Squared Distribution Examples">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="two_sample_students_t.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../st_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../cs_eg.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.st_eg.paired_st"></a><a href="paired_st.html" title="Comparing two paired samples with the Student's t distribution">
+ Comparing two paired samples with the Student's t distribution</a>
+</h6></div></div></div>
+<p>
+ Imagine that we have a before and after reading for each item in the
+ sample: for example we might have measured blood pressure before and
+ after administration of a new drug. We can't pool the results and compare
+ the means before and after the change, because each patient will have
+ a different baseline reading. Instead we calculate the difference between
+ before and after measurements in each patient, and calculate the mean
+ and standard deviation of the differences. To test whether a significant
+ change has taken place, we can then test the null-hypothesis that the
+ true mean is zero using the same procedure we used in the single sample
+ cases previously discussed.
+ </p>
+<p>
+ That means we can:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+<a href="tut_mean_intervals.html" title="Calculating confidence intervals on the mean with the Students-t distribution">Calculate
+ confidence intervals of the mean</a>. If the endpoints of the
+ interval differ in sign then we are unable to reject the null-hypothesis
+ that there is no change.
+ </li>
+<li>
+<a href="tut_mean_test.html" title='Testing a sample mean for difference from a "true" mean'>Test
+ whether the true mean is zero</a>. If the result is consistent
+ with a true mean of zero, then we are unable to reject the null-hypothesis
+ that there is no change.
+ </li>
+<li>
+<a href="tut_mean_size.html" title="Estimating how large a sample size would have to become in order to give a significant Students-t test result with a single sample test">Calculate
+ how many pairs of readings we would need in order to obtain a significant
+ result</a>.
+ </li>
+</ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="two_sample_students_t.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../st_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../cs_eg.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg/tut_mean_intervals.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg/tut_mean_intervals.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,269 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Calculating confidence intervals on the mean with the Students-t distribution</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../st_eg.html" title="Student's t Distribution Examples">
+<link rel="prev" href="../st_eg.html" title="Student's t Distribution Examples">
+<link rel="next" href="tut_mean_test.html" title='Testing a sample mean for difference from a "true" mean'>
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../st_eg.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../st_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="tut_mean_test.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.st_eg.tut_mean_intervals"></a><a href="tut_mean_intervals.html" title="Calculating confidence intervals on the mean with the Students-t distribution">
+ Calculating confidence intervals on the mean with the Students-t distribution</a>
+</h6></div></div></div>
+<p>
+ Let's say you have a sample mean, you may wish to know what confidence
+ intervals you can place on that mean. Colloquially: "I want an
+ interval that I can be P% sure contains the true mean". (On a
+ technical point, note that the interval either contains the true mean
+ or it does not: the meaning of the confidence level is subtly different
+ from this colloquialism. More background information can be found on
+ the <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda352.htm" target="_top">NIST
+ site</a>).
+ </p>
+<p>
+ The formula for the interval can be expressed as:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../../equations/dist_tutorial4.png"></span>
+ </p>
+<p>
+ Where, <span class="emphasis"><em>Y<sub>s</sub></em></span> is the sample mean, <span class="emphasis"><em>s</em></span>
+ is the sample standard deviation, <span class="emphasis"><em>N</em></span> is the sample
+ size, <span class="emphasis"><em>[alpha]</em></span> is the desired significance level
+ and <span class="emphasis"><em>t<sub>(&#945;/2,N-1)</sub></em></span> is the upper critical value of the
+ Students-t distribution with <span class="emphasis"><em>N-1</em></span> degrees of freedom.
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ The quantity &#945; is the maximum acceptable risk of falsely rejecting
+ the null-hypothesis. The smaller the value of &#945; the greater the strength
+ of the test.
+ </p>
+<p>
+ The confidence level of the test is defined as 1 - &#945;, and often expressed
+ as a percentage. So for example a significance level of 0.05, is
+ equivalent to a 95% confidence level. Refer to <a href="http://www.itl.nist.gov/div898/handbook/prc/section1/prc14.htm" target="_top">"What
+ are confidence intervals?"</a> in <a href="http://www.itl.nist.gov/div898/handbook/" target="_top">NIST/SEMATECH
+ e-Handbook of Statistical Methods.</a> for more information.
+ </p>
+</td></tr>
+</table></div>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ The usual assumptions of <a href="http://en.wikipedia.org/wiki/Independent_and_identically-distributed_random_variables" target="_top">independent
+ and identically distributed (i.i.d.)</a> variables and normal distribution
+ of course apply here, as they do in other examples.
+ </p></td></tr>
+</table></div>
+<p>
+ From the formula, it should be clear that:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ The width of the confidence interval decreases as the sample size
+ increases.
+ </li>
+<li>
+ The width increases as the standard deviation increases.
+ </li>
+<li>
+ The width increases as the <span class="emphasis"><em>confidence level increases</em></span>
+ (0.5 towards 0.99999 - stronger).
+ </li>
+<li>
+ The width increases as the <span class="emphasis"><em>significance level decreases</em></span>
+ (0.5 towards 0.00000...01 - stronger).
+ </li>
+</ul></div>
+<p>
+ The following example code is taken from the example program students_t_single_sample.cpp.
+ </p>
+<p>
+ We'll begin by defining a procedure to calculate intervals for various
+ confidence levels; the procedure will print these out as a table:
+ </p>
+<pre class="programlisting">
+<span class="comment">// Needed includes:
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">students_t</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iomanip</span><span class="special">&gt;</span>
+<span class="comment">// Bring everything into global namespace for ease of use:
+</span><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">std</span><span class="special">;</span>
+
+<span class="keyword">void</span> <span class="identifier">confidence_limits_on_mean</span><span class="special">(</span>
+ <span class="keyword">double</span> <span class="identifier">Sm</span><span class="special">,</span> <span class="comment">// Sm = Sample Mean.
+</span> <span class="keyword">double</span> <span class="identifier">Sd</span><span class="special">,</span> <span class="comment">// Sd = Sample Standard Deviation.
+</span> <span class="keyword">unsigned</span> <span class="identifier">Sn</span><span class="special">)</span> <span class="comment">// Sn = Sample Size.
+</span><span class="special">{</span>
+ <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">std</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+
+ <span class="comment">// Print out general info:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span>
+ <span class="string">"__________________________________\n"</span>
+ <span class="string">"2-Sided Confidence Limits For Mean\n"</span>
+ <span class="string">"__________________________________\n\n"</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">7</span><span class="special">);</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">40</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Number of Observations"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">Sn</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">40</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Mean"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">Sm</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">40</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Standard Deviation"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">Sd</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+</pre>
+<p>
+ We'll define a table of significance/risk levels for which we'll compute
+ intervals:
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">alpha</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">0.5</span><span class="special">,</span> <span class="number">0.25</span><span class="special">,</span> <span class="number">0.1</span><span class="special">,</span> <span class="number">0.05</span><span class="special">,</span> <span class="number">0.01</span><span class="special">,</span> <span class="number">0.001</span><span class="special">,</span> <span class="number">0.0001</span><span class="special">,</span> <span class="number">0.00001</span> <span class="special">};</span>
+</pre>
+<p>
+ Note that these are the complements of the confidence/probability levels:
+ 0.5, 0.75, 0.9 .. 0.99999).
+ </p>
+<p>
+ Next we'll declare the distribution object we'll need, note that the
+ <span class="emphasis"><em>degrees of freedom</em></span> parameter is the sample size
+ less one:
+ </p>
+<pre class="programlisting">
+<span class="identifier">students_t</span> <span class="identifier">dist</span><span class="special">(</span><span class="identifier">Sn</span> <span class="special">-</span> <span class="number">1</span><span class="special">);</span>
+</pre>
+<p>
+ Most of what follows in the program is pretty printing, so let's focus
+ on the calculation of the interval. First we need the t-statistic,
+ computed using the <span class="emphasis"><em>quantile</em></span> function and our significance
+ level. Note that since the significance levels are the complement of
+ the probability, we have to wrap the arguments in a call to <span class="emphasis"><em>complement(...)</em></span>:
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">T</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> <span class="special">/</span> <span class="number">2</span><span class="special">));</span>
+</pre>
+<p>
+ Note that alpha was divided by two, since we'll be calculating both
+ the upper and lower bounds: had we been interested in a single sided
+ interval then we would have omitted this step.
+ </p>
+<p>
+ Now to complete the picture, we'll get the (one-sided) width of the
+ interval from the t-statistic by multiplying by the standard deviation,
+ and dividing by the square root of the sample size:
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">w</span> <span class="special">=</span> <span class="identifier">T</span> <span class="special">*</span> <span class="identifier">Sd</span> <span class="special">/</span> <span class="identifier">sqrt</span><span class="special">(</span><span class="keyword">double</span><span class="special">(</span><span class="identifier">Sn</span><span class="special">));</span>
+</pre>
+<p>
+ The two-sided interval is then the sample mean plus and minus this
+ width.
+ </p>
+<p>
+ And apart from some more pretty-printing that completes the procedure.
+ </p>
+<p>
+ Let's take a look at some sample output, first using the <a href="http://www.itl.nist.gov/div898/handbook/eda/section4/eda428.htm" target="_top">Heat
+ flow data</a> from the NIST site. The data set was collected by
+ Bob Zarr of NIST in January, 1990 from a heat flow meter calibration
+ and stability analysis. The corresponding dataplot output for this
+ test can be found in <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda352.htm" target="_top">section
+ 3.5.2</a> of the <a href="http://www.itl.nist.gov/div898/handbook/" target="_top">NIST/SEMATECH
+ e-Handbook of Statistical Methods.</a>.
+ </p>
+<pre class="programlisting"> __________________________________
+ 2-Sided Confidence Limits For Mean
+ __________________________________
+
+ Number of Observations = 195
+ Mean = 9.26146
+ Standard Deviation = 0.02278881
+
+
+ ___________________________________________________________________
+ Confidence T Interval Lower Upper
+ Value (%) Value Width Limit Limit
+ ___________________________________________________________________
+ 50.000 0.676 1.103e-003 9.26036 9.26256
+ 75.000 1.154 1.883e-003 9.25958 9.26334
+ 90.000 1.653 2.697e-003 9.25876 9.26416
+ 95.000 1.972 3.219e-003 9.25824 9.26468
+ 99.000 2.601 4.245e-003 9.25721 9.26571
+ 99.900 3.341 5.453e-003 9.25601 9.26691
+ 99.990 3.973 6.484e-003 9.25498 9.26794
+ 99.999 4.537 7.404e-003 9.25406 9.26886
+</pre>
+<p>
+ As you can see the large sample size (195) and small standard deviation
+ (0.023) have combined to give very small intervals, indeed we can be
+ very confident that the true mean is 9.2.
+ </p>
+<p>
+ For comparison the next example data output is taken from <span class="emphasis"><em>P.K.Hou,
+ O. W. Lau &amp; M.C. Wong, Analyst (1983) vol. 108, p 64. and from
+ Statistics for Analytical Chemistry, 3rd ed. (1994), pp 54-55 J. C.
+ Miller and J. N. Miller, Ellis Horwood ISBN 0 13 0309907.</em></span>
+ The values result from the determination of mercury by cold-vapour
+ atomic absorption.
+ </p>
+<pre class="programlisting"> __________________________________
+ 2-Sided Confidence Limits For Mean
+ __________________________________
+
+ Number of Observations = 3
+ Mean = 37.8000000
+ Standard Deviation = 0.9643650
+
+
+ ___________________________________________________________________
+ Confidence T Interval Lower Upper
+ Value (%) Value Width Limit Limit
+ ___________________________________________________________________
+ 50.000 0.816 0.455 37.34539 38.25461
+ 75.000 1.604 0.893 36.90717 38.69283
+ 90.000 2.920 1.626 36.17422 39.42578
+ 95.000 4.303 2.396 35.40438 40.19562
+ 99.000 9.925 5.526 32.27408 43.32592
+ 99.900 31.599 17.594 20.20639 55.39361
+ 99.990 99.992 55.673 -17.87346 93.47346
+ 99.999 316.225 176.067 -138.26683 213.86683
+</pre>
+<p>
+ This time the fact that there are only three measurements leads to
+ much wider intervals, indeed such large intervals that it's hard to
+ be very confident in the location of the mean.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../st_eg.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../st_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="tut_mean_test.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg/tut_mean_size.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg/tut_mean_size.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,180 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Estimating how large a sample size would have to become in order to give a significant Students-t test result with a single sample test</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../st_eg.html" title="Student's t Distribution Examples">
+<link rel="prev" href="tut_mean_test.html" title='Testing a sample mean for difference from a "true" mean'>
+<link rel="next" href="two_sample_students_t.html" title="Comparing the means of two samples with the Students-t test">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tut_mean_test.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../st_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="two_sample_students_t.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.st_eg.tut_mean_size"></a><a href="tut_mean_size.html" title="Estimating how large a sample size would have to become in order to give a significant Students-t test result with a single sample test">
+ Estimating how large a sample size would have to become in order to give
+ a significant Students-t test result with a single sample test</a>
+</h6></div></div></div>
+<p>
+ Imagine you have conducted a Students-t test on a single sample in
+ order to check for systematic errors in your measurements. Imagine
+ that the result is borderline. At this point one might go off and collect
+ more data, but it might be prudent to first ask the question "How
+ much more?". The parameter estimators of the students_t_distribution
+ class can provide this information.
+ </p>
+<p>
+ This section is based on the example code in students_t_single_sample.cpp
+ and we begin by defining a procedure that will print out a table of
+ estimated sample sizes for various confidence levels:
+ </p>
+<pre class="programlisting">
+<span class="comment">// Needed includes:
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">students_t</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iomanip</span><span class="special">&gt;</span>
+<span class="comment">// Bring everything into global namespace for ease of use:
+</span><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">std</span><span class="special">;</span>
+
+<span class="keyword">void</span> <span class="identifier">single_sample_find_df</span><span class="special">(</span>
+ <span class="keyword">double</span> <span class="identifier">M</span><span class="special">,</span> <span class="comment">// M = true mean.
+</span> <span class="keyword">double</span> <span class="identifier">Sm</span><span class="special">,</span> <span class="comment">// Sm = Sample Mean.
+</span> <span class="keyword">double</span> <span class="identifier">Sd</span><span class="special">)</span> <span class="comment">// Sd = Sample Standard Deviation.
+</span><span class="special">{</span>
+</pre>
+<p>
+ Next we define a table of significance levels:
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">alpha</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">0.5</span><span class="special">,</span> <span class="number">0.25</span><span class="special">,</span> <span class="number">0.1</span><span class="special">,</span> <span class="number">0.05</span><span class="special">,</span> <span class="number">0.01</span><span class="special">,</span> <span class="number">0.001</span><span class="special">,</span> <span class="number">0.0001</span><span class="special">,</span> <span class="number">0.00001</span> <span class="special">};</span>
+</pre>
+<p>
+ Printing out the table of sample sizes required for various confidence
+ levels begins with the table header:
+ </p>
+<pre class="programlisting">
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"\n\n"</span>
+ <span class="string">"_______________________________________________________________\n"</span>
+ <span class="string">"Confidence Estimated Estimated\n"</span>
+ <span class="string">" Value (%) Sample Size Sample Size\n"</span>
+ <span class="string">" (one sided test) (two sided test)\n"</span>
+ <span class="string">"_______________________________________________________________\n"</span><span class="special">;</span>
+</pre>
+<p>
+ And now the important part: the sample sizes required. Class <code class="computeroutput"><span class="identifier">students_t_distribution</span></code> has a static
+ member function <code class="computeroutput"><span class="identifier">find_degrees_of_freedom</span></code>
+ that will calculate how large a sample size needs to be in order to
+ give a definitive result.
+ </p>
+<p>
+ The first argument is the difference between the means that you wish
+ to be able to detect, here it's the absolute value of the difference
+ between the sample mean, and the true mean.
+ </p>
+<p>
+ Then come two probability values: alpha and beta. Alpha is the maximum
+ acceptable risk of rejecting the null-hypothesis when it is in fact
+ true. Beta is the maximum acceptable risk of failing to reject the
+ null-hypothesis when in fact it is false. Also note that for a two-sided
+ test, alpha must be divided by 2.
+ </p>
+<p>
+ The final parameter of the function is the standard deviation of the
+ sample.
+ </p>
+<p>
+ In this example, we assume that alpha and beta are the same, and call
+ <code class="computeroutput"><span class="identifier">find_degrees_of_freedom</span></code>
+ twice: once with alpha for a one-sided test, and once with alpha/2
+ for a two-sided test.
+ </p>
+<pre class="programlisting">
+ <span class="keyword">for</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">)/</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">alpha</span><span class="special">[</span><span class="number">0</span><span class="special">]);</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="comment">// Confidence value:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="number">100</span> <span class="special">*</span> <span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]);</span>
+ <span class="comment">// calculate df for single sided test:
+</span> <span class="keyword">double</span> <span class="identifier">df</span> <span class="special">=</span> <span class="identifier">students_t</span><span class="special">::</span><span class="identifier">find_degrees_of_freedom</span><span class="special">(</span>
+ <span class="identifier">fabs</span><span class="special">(</span><span class="identifier">M</span> <span class="special">-</span> <span class="identifier">Sm</span><span class="special">),</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">],</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">],</span> <span class="identifier">Sd</span><span class="special">);</span>
+ <span class="comment">// convert to sample size:
+</span> <span class="keyword">double</span> <span class="identifier">size</span> <span class="special">=</span> <span class="identifier">ceil</span><span class="special">(</span><span class="identifier">df</span><span class="special">)</span> <span class="special">+</span> <span class="number">1</span><span class="special">;</span>
+ <span class="comment">// Print size:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">16</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">size</span><span class="special">;</span>
+ <span class="comment">// calculate df for two sided test:
+</span> <span class="identifier">df</span> <span class="special">=</span> <span class="identifier">students_t</span><span class="special">::</span><span class="identifier">find_degrees_of_freedom</span><span class="special">(</span>
+ <span class="identifier">fabs</span><span class="special">(</span><span class="identifier">M</span> <span class="special">-</span> <span class="identifier">Sm</span><span class="special">),</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">]/</span><span class="number">2</span><span class="special">,</span> <span class="identifier">alpha</span><span class="special">[</span><span class="identifier">i</span><span class="special">],</span> <span class="identifier">Sd</span><span class="special">);</span>
+ <span class="comment">// convert to sample size:
+</span> <span class="identifier">size</span> <span class="special">=</span> <span class="identifier">ceil</span><span class="special">(</span><span class="identifier">df</span><span class="special">)</span> <span class="special">+</span> <span class="number">1</span><span class="special">;</span>
+ <span class="comment">// Print size:
+</span> <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">fixed</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">16</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">right</span> <span class="special">&lt;&lt;</span> <span class="identifier">size</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ Let's now look at some sample output using data taken from <span class="emphasis"><em>P.K.Hou,
+ O. W. Lau &amp; M.C. Wong, Analyst (1983) vol. 108, p 64. and from
+ Statistics for Analytical Chemistry, 3rd ed. (1994), pp 54-55 J. C.
+ Miller and J. N. Miller, Ellis Horwood ISBN 0 13 0309907.</em></span>
+ The values result from the determination of mercury by cold-vapour
+ atomic absorption.
+ </p>
+<p>
+ Only three measurements were made, and the Students-t test above gave
+ a borderline result, so this example will show us how many samples
+ would need to be collected:
+ </p>
+<pre class="programlisting">_____________________________________________________________
+Estimated sample sizes required for various confidence levels
+_____________________________________________________________
+
+True Mean = 38.90000
+Sample Mean = 37.80000
+Sample Standard Deviation = 0.96437
+
+
+_______________________________________________________________
+Confidence Estimated Estimated
+ Value (%) Sample Size Sample Size
+ (one sided test) (two sided test)
+_______________________________________________________________
+ 50.000 2 3
+ 75.000 4 5
+ 90.000 8 10
+ 95.000 12 14
+ 99.000 21 23
+ 99.900 36 38
+ 99.990 51 54
+ 99.999 67 69
+</pre>
+<p>
+ So in this case, many more measurements would have had to be made,
+ for example at the 95% level, 14 measurements in total for a two-sided
+ test.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tut_mean_test.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../st_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="two_sample_students_t.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg/tut_mean_test.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg/tut_mean_test.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,333 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Testing a sample mean for difference from a "true" mean</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../st_eg.html" title="Student's t Distribution Examples">
+<link rel="prev" href="tut_mean_intervals.html" title="Calculating confidence intervals on the mean with the Students-t distribution">
+<link rel="next" href="tut_mean_size.html" title="Estimating how large a sample size would have to become in order to give a significant Students-t test result with a single sample test">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tut_mean_intervals.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../st_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="tut_mean_size.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.st_eg.tut_mean_test"></a><a href="tut_mean_test.html" title='Testing a sample mean for difference from a "true" mean'>
+ Testing a sample mean for difference from a "true" mean</a>
+</h6></div></div></div>
+<p>
+ When calibrating or comparing a scientific instrument or measurement
+ method of some kind, we want to be answer the question "Does an
+ observed sample mean differ from the "true" mean in any significant
+ way?". If it does, then we have evidence of a systematic difference.
+ This question can be answered with a Students-t test: more information
+ can be found <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda352.htm" target="_top">on
+ the NIST site</a>.
+ </p>
+<p>
+ Of course, the assignment of "true" to one mean may be quite
+ arbitrary, often this is simply a "traditional" method of
+ measurement.
+ </p>
+<p>
+ The following example code is taken from the example program students_t_single_sample.cpp.
+ </p>
+<p>
+ We'll begin by defining a procedure to determine which of the possible
+ hypothesis are rejected or not-rejected at a given significance level:
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ Non-statisticians might say 'not-rejected' means 'accepted', (often
+ of the null-hypothesis) implying, wrongly, that there really <span class="bold"><strong>IS</strong></span> no difference, but statisticans eschew
+ this to avoid implying that there is positive evidence of 'no difference'.
+ 'Not-rejected' here means there is <span class="bold"><strong>no evidence</strong></span>
+ of difference, but there still might well be a difference. For example,
+ see <a href="http://en.wikipedia.org/wiki/Argument_from_ignorance" target="_top">argument
+ from ignorance</a> and <a href="http://www.bmj.com/cgi/content/full/311/7003/485" target="_top">Absence
+ of evidence does not constitute evidence of absence.</a>
+ </p></td></tr>
+</table></div>
+<pre class="programlisting">
+<span class="comment">// Needed includes:
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">students_t</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iomanip</span><span class="special">&gt;</span>
+<span class="comment">// Bring everything into global namespace for ease of use:
+</span><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">std</span><span class="special">;</span>
+
+<span class="keyword">void</span> <span class="identifier">single_sample_t_test</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">M</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">Sm</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">Sd</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">Sn</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">alpha</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="comment">//
+</span> <span class="comment">// M = true mean.
+</span> <span class="comment">// Sm = Sample Mean.
+</span> <span class="comment">// Sd = Sample Standard Deviation.
+</span> <span class="comment">// Sn = Sample Size.
+</span> <span class="comment">// alpha = Significance Level.
+</span></pre>
+<p>
+ Most of the procedure is pretty-printing, so let's just focus on the
+ calculation, we begin by calculating the t-statistic:
+ </p>
+<pre class="programlisting">
+<span class="comment">// Difference in means:
+</span><span class="keyword">double</span> <span class="identifier">diff</span> <span class="special">=</span> <span class="identifier">Sm</span> <span class="special">-</span> <span class="identifier">M</span><span class="special">;</span>
+<span class="comment">// Degrees of freedom:
+</span><span class="keyword">unsigned</span> <span class="identifier">v</span> <span class="special">=</span> <span class="identifier">Sn</span> <span class="special">-</span> <span class="number">1</span><span class="special">;</span>
+<span class="comment">// t-statistic:
+</span><span class="keyword">double</span> <span class="identifier">t_stat</span> <span class="special">=</span> <span class="identifier">diff</span> <span class="special">*</span> <span class="identifier">sqrt</span><span class="special">(</span><span class="keyword">double</span><span class="special">(</span><span class="identifier">Sn</span><span class="special">))</span> <span class="special">/</span> <span class="identifier">Sd</span><span class="special">;</span>
+</pre>
+<p>
+ Finally calculate the probability from the t-statistic. If we're interested
+ in simply whether there is a difference (either less or greater) or
+ not, we don't care about the sign of the t-statistic, and we take the
+ complement of the probability for comparison to the significance level:
+ </p>
+<pre class="programlisting">
+<span class="identifier">students_t</span> <span class="identifier">dist</span><span class="special">(</span><span class="identifier">v</span><span class="special">);</span>
+<span class="keyword">double</span> <span class="identifier">q</span> <span class="special">=</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">fabs</span><span class="special">(</span><span class="identifier">t_stat</span><span class="special">)));</span>
+</pre>
+<p>
+ The procedure then prints out the results of the various tests that
+ can be done, these can be summarised in the following table:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Hypothesis
+ </p>
+ </th>
+<th>
+ <p>
+ Test
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ The Null-hypothesis: there is <span class="bold"><strong>no difference</strong></span>
+ in means
+ </p>
+ </td>
+<td>
+ <p>
+ Reject if complement of CDF for |t| &lt; significance level
+ / 2:
+ </p>
+ <p>
+ <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span>
+ <span class="identifier">fabs</span><span class="special">(</span><span class="identifier">t</span><span class="special">)))</span>
+ <span class="special">&lt;</span> <span class="identifier">alpha</span>
+ <span class="special">/</span> <span class="number">2</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ The Alternative-hypothesis: there <span class="bold"><strong>is
+ difference</strong></span> in means
+ </p>
+ </td>
+<td>
+ <p>
+ Reject if complement of CDF for |t| &gt; significance level
+ / 2:
+ </p>
+ <p>
+ <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span>
+ <span class="identifier">fabs</span><span class="special">(</span><span class="identifier">t</span><span class="special">)))</span>
+ <span class="special">&gt;</span> <span class="identifier">alpha</span>
+ <span class="special">/</span> <span class="number">2</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ The Alternative-hypothesis: the sample mean <span class="bold"><strong>is
+ less</strong></span> than the true mean.
+ </p>
+ </td>
+<td>
+ <p>
+ Reject if CDF of t &gt; significance level:
+ </p>
+ <p>
+ <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span>
+ <span class="identifier">t</span><span class="special">)</span>
+ <span class="special">&gt;</span> <span class="identifier">alpha</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ The Alternative-hypothesis: the sample mean <span class="bold"><strong>is
+ greater</strong></span> than the true mean.
+ </p>
+ </td>
+<td>
+ <p>
+ Reject if complement of CDF of t &gt; significance level:
+ </p>
+ <p>
+ <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span>
+ <span class="identifier">t</span><span class="special">))</span>
+ <span class="special">&gt;</span> <span class="identifier">alpha</span></code>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ Notice that the comparisons are against <code class="computeroutput"><span class="identifier">alpha</span>
+ <span class="special">/</span> <span class="number">2</span></code>
+ for a two-sided test and against <code class="computeroutput"><span class="identifier">alpha</span></code>
+ for a one-sided test
+ </p></td></tr>
+</table></div>
+<p>
+ Now that we have all the parts in place, let's take a look at some
+ sample output, first using the <a href="http://www.itl.nist.gov/div898/handbook/eda/section4/eda428.htm" target="_top">Heat
+ flow data</a> from the NIST site. The data set was collected by
+ Bob Zarr of NIST in January, 1990 from a heat flow meter calibration
+ and stability analysis. The corresponding dataplot output for this
+ test can be found in <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda352.htm" target="_top">section
+ 3.5.2</a> of the <a href="http://www.itl.nist.gov/div898/handbook/" target="_top">NIST/SEMATECH
+ e-Handbook of Statistical Methods.</a>.
+ </p>
+<pre class="programlisting"> __________________________________
+ Student t test for a single sample
+ __________________________________
+
+ Number of Observations = 195
+ Sample Mean = 9.26146
+ Sample Standard Deviation = 0.02279
+ Expected True Mean = 5.00000
+
+ Sample Mean - Expected Test Mean = 4.26146
+ Degrees of Freedom = 194
+ T Statistic = 2611.28380
+ Probability that difference is due to chance = 0.000e+000
+
+ Results for Alternative Hypothesis and alpha = 0.0500
+
+ Alternative Hypothesis Conclusion
+ Mean != 5.000 NOT REJECTED
+ Mean &lt; 5.000 REJECTED
+ Mean &gt; 5.000 NOT REJECTED
+</pre>
+<p>
+ You will note the line that says the probability that the difference
+ is due to chance is zero. From a philosophical point of view, of course,
+ the probability can never reach zero. However, in this case the calculated
+ probability is smaller than the smallest representable double precision
+ number, hence the appearance of a zero here. Whatever its "true"
+ value is, we know it must be extraordinarily small, so the alternative
+ hypothesis - that there is a difference in means - is not rejected.
+ </p>
+<p>
+ For comparison the next example data output is taken from <span class="emphasis"><em>P.K.Hou,
+ O. W. Lau &amp; M.C. Wong, Analyst (1983) vol. 108, p 64. and from
+ Statistics for Analytical Chemistry, 3rd ed. (1994), pp 54-55 J. C.
+ Miller and J. N. Miller, Ellis Horwood ISBN 0 13 0309907.</em></span>
+ The values result from the determination of mercury by cold-vapour
+ atomic absorption.
+ </p>
+<pre class="programlisting"> __________________________________
+ Student t test for a single sample
+ __________________________________
+
+ Number of Observations = 3
+ Sample Mean = 37.80000
+ Sample Standard Deviation = 0.96437
+ Expected True Mean = 38.90000
+
+ Sample Mean - Expected Test Mean = -1.10000
+ Degrees of Freedom = 2
+ T Statistic = -1.97566
+ Probability that difference is due to chance = 1.869e-001
+
+ Results for Alternative Hypothesis and alpha = 0.0500
+
+ Alternative Hypothesis Conclusion
+ Mean != 38.900 REJECTED
+ Mean &lt; 38.900 REJECTED
+ Mean &gt; 38.900 REJECTED
+</pre>
+<p>
+ As you can see the small number of measurements (3) has led to a large
+ uncertainty in the location of the true mean. So even though there
+ appears to be a difference between the sample mean and the expected
+ true mean, we conclude that there is no significant difference, and
+ are unable to reject the null hypothesis. However, if we were to lower
+ the bar for acceptance down to alpha = 0.1 (a 90% confidence level)
+ we see a different output:
+ </p>
+<pre class="programlisting">__________________________________
+Student t test for a single sample
+__________________________________
+
+Number of Observations = 3
+Sample Mean = 37.80000
+Sample Standard Deviation = 0.96437
+Expected True Mean = 38.90000
+
+Sample Mean - Expected Test Mean = -1.10000
+Degrees of Freedom = 2
+T Statistic = -1.97566
+Probability that difference is due to chance = 1.869e-001
+
+Results for Alternative Hypothesis and alpha = 0.1000
+
+Alternative Hypothesis Conclusion
+Mean != 38.900 REJECTED
+Mean &lt; 38.900 NOT REJECTED
+Mean &gt; 38.900 REJECTED
+</pre>
+<p>
+ In this case, we really have a borderline result, and more data (and/or
+ more accurate data), is needed for a more convincing conclusion.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tut_mean_intervals.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../st_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="tut_mean_size.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg/two_sample_students_t.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/st_eg/two_sample_students_t.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,358 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Comparing the means of two samples with the Students-t test</title>
+<link rel="stylesheet" href="../../../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../../../index.html" title="Math Toolkit">
+<link rel="up" href="../st_eg.html" title="Student's t Distribution Examples">
+<link rel="prev" href="tut_mean_size.html" title="Estimating how large a sample size would have to become in order to give a significant Students-t test result with a single sample test">
+<link rel="next" href="paired_st.html" title="Comparing two paired samples with the Student's t distribution">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tut_mean_size.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../st_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="paired_st.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="math_toolkit.dist.stat_tut.weg.st_eg.two_sample_students_t"></a><a href="two_sample_students_t.html" title="Comparing the means of two samples with the Students-t test">
+ Comparing the means of two samples with the Students-t test</a>
+</h6></div></div></div>
+<p>
+ Imagine that we have two samples, and we wish to determine whether
+ their means are different or not. This situation often arises when
+ determining whether a new process or treatment is better than an old
+ one.
+ </p>
+<p>
+ In this example, we'll be using the <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3531.htm" target="_top">Car
+ Mileage sample data</a> from the <a href="http://www.itl.nist.gov" target="_top">NIST
+ website</a>. The data compares miles per gallon of US cars with
+ miles per gallon of Japanese cars.
+ </p>
+<p>
+ The sample code is in students_t_two_samples.cpp.
+ </p>
+<p>
+ There are two ways in which this test can be conducted: we can assume
+ that the true standard deviations of the two samples are equal or not.
+ If the standard deviations are assumed to be equal, then the calculation
+ of the t-statistic is greatly simplified, so we'll examine that case
+ first. In real life we should verify whether this assumption is valid
+ with a Chi-Squared test for equal variances.
+ </p>
+<p>
+ We begin by defining a procedure that will conduct our test assuming
+ equal variances:
+ </p>
+<pre class="programlisting">
+<span class="comment">// Needed headers:
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">students_t</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iomanip</span><span class="special">&gt;</span>
+<span class="comment">// Simplify usage:
+</span><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">std</span><span class="special">;</span>
+
+<span class="keyword">void</span> <span class="identifier">two_samples_t_test_equal_sd</span><span class="special">(</span>
+ <span class="keyword">double</span> <span class="identifier">Sm1</span><span class="special">,</span> <span class="comment">// Sm1 = Sample 1 Mean.
+</span> <span class="keyword">double</span> <span class="identifier">Sd1</span><span class="special">,</span> <span class="comment">// Sd1 = Sample 1 Standard Deviation.
+</span> <span class="keyword">unsigned</span> <span class="identifier">Sn1</span><span class="special">,</span> <span class="comment">// Sn1 = Sample 1 Size.
+</span> <span class="keyword">double</span> <span class="identifier">Sm2</span><span class="special">,</span> <span class="comment">// Sm2 = Sample 2 Mean.
+</span> <span class="keyword">double</span> <span class="identifier">Sd2</span><span class="special">,</span> <span class="comment">// Sd2 = Sample 2 Standard Deviation.
+</span> <span class="keyword">unsigned</span> <span class="identifier">Sn2</span><span class="special">,</span> <span class="comment">// Sn2 = Sample 2 Size.
+</span> <span class="keyword">double</span> <span class="identifier">alpha</span><span class="special">)</span> <span class="comment">// alpha = Significance Level.
+</span><span class="special">{</span>
+</pre>
+<p>
+ Our procedure will begin by calculating the t-statistic, assuming equal
+ variances the needed formulae are:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../../equations/dist_tutorial1.png"></span>
+ </p>
+<p>
+ where Sp is the "pooled" standard deviation of the two samples,
+ and <span class="emphasis"><em>v</em></span> is the number of degrees of freedom of the
+ two combined samples. We can now write the code to calculate the t-statistic:
+ </p>
+<pre class="programlisting">
+<span class="comment">// Degrees of freedom:
+</span><span class="keyword">double</span> <span class="identifier">v</span> <span class="special">=</span> <span class="identifier">Sn1</span> <span class="special">+</span> <span class="identifier">Sn2</span> <span class="special">-</span> <span class="number">2</span><span class="special">;</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Degrees of Freedom"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">v</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+<span class="comment">// Pooled variance:
+</span><span class="keyword">double</span> <span class="identifier">sp</span> <span class="special">=</span> <span class="identifier">sqrt</span><span class="special">(((</span><span class="identifier">Sn1</span><span class="special">-</span><span class="number">1</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">Sd1</span> <span class="special">*</span> <span class="identifier">Sd1</span> <span class="special">+</span> <span class="special">(</span><span class="identifier">Sn2</span><span class="special">-</span><span class="number">1</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">Sd2</span> <span class="special">*</span> <span class="identifier">Sd2</span><span class="special">)</span> <span class="special">/</span> <span class="identifier">v</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Pooled Standard Deviation"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">v</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+<span class="comment">// t-statistic:
+</span><span class="keyword">double</span> <span class="identifier">t_stat</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">Sm1</span> <span class="special">-</span> <span class="identifier">Sm2</span><span class="special">)</span> <span class="special">/</span> <span class="special">(</span><span class="identifier">sp</span> <span class="special">*</span> <span class="identifier">sqrt</span><span class="special">(</span><span class="number">1.0</span> <span class="special">/</span> <span class="identifier">Sn1</span> <span class="special">+</span> <span class="number">1.0</span> <span class="special">/</span> <span class="identifier">Sn2</span><span class="special">));</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"T Statistic"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">t_stat</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+</pre>
+<p>
+ The next step is to define our distribution object, and calculate the
+ complement of the probability:
+ </p>
+<pre class="programlisting">
+<span class="identifier">students_t</span> <span class="identifier">dist</span><span class="special">(</span><span class="identifier">v</span><span class="special">);</span>
+<span class="keyword">double</span> <span class="identifier">q</span> <span class="special">=</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">fabs</span><span class="special">(</span><span class="identifier">t_stat</span><span class="special">)));</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability that difference is due to chance"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">setprecision</span><span class="special">(</span><span class="number">3</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">scientific</span> <span class="special">&lt;&lt;</span> <span class="number">2</span> <span class="special">*</span> <span class="identifier">q</span> <span class="special">&lt;&lt;</span> <span class="string">"\n\n"</span><span class="special">;</span>
+</pre>
+<p>
+ Here we've used the absolute value of the t-statistic, because we initially
+ want to know simply whether there is a difference or not (a two-sided
+ test). However, we can also test whether the mean of the second sample
+ is greater or is less (one-sided test) than that of the first: all
+ the possible tests are summed up in the following table:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Hypothesis
+ </p>
+ </th>
+<th>
+ <p>
+ Test
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ The Null-hypothesis: there is <span class="bold"><strong>no difference</strong></span>
+ in means
+ </p>
+ </td>
+<td>
+ <p>
+ Reject if complement of CDF for |t| &lt; significance level
+ / 2:
+ </p>
+ <p>
+ <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span>
+ <span class="identifier">fabs</span><span class="special">(</span><span class="identifier">t</span><span class="special">)))</span>
+ <span class="special">&lt;</span> <span class="identifier">alpha</span>
+ <span class="special">/</span> <span class="number">2</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ The Alternative-hypothesis: there is a <span class="bold"><strong>difference</strong></span>
+ in means
+ </p>
+ </td>
+<td>
+ <p>
+ Reject if complement of CDF for |t| &gt; significance level
+ / 2:
+ </p>
+ <p>
+ <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span>
+ <span class="identifier">fabs</span><span class="special">(</span><span class="identifier">t</span><span class="special">)))</span>
+ <span class="special">&lt;</span> <span class="identifier">alpha</span>
+ <span class="special">/</span> <span class="number">2</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ The Alternative-hypothesis: Sample 1 Mean is <span class="bold"><strong>less</strong></span>
+ than Sample 2 Mean.
+ </p>
+ </td>
+<td>
+ <p>
+ Reject if CDF of t &gt; significance level:
+ </p>
+ <p>
+ <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span>
+ <span class="identifier">t</span><span class="special">)</span>
+ <span class="special">&gt;</span> <span class="identifier">alpha</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ The Alternative-hypothesis: Sample 1 Mean is <span class="bold"><strong>greater</strong></span>
+ than Sample 2 Mean.
+ </p>
+ </td>
+<td>
+ <p>
+ Reject if complement of CDF of t &gt; significance level:
+ </p>
+ <p>
+ <code class="computeroutput"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span>
+ <span class="identifier">t</span><span class="special">))</span>
+ <span class="special">&gt;</span> <span class="identifier">alpha</span></code>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ For a two-sided test we must compare against alpha / 2 and not alpha.
+ </p></td></tr>
+</table></div>
+<p>
+ Most of the rest of the sample program is pretty-printing, so we'll
+ skip over that, and take a look at the sample output for alpha=0.05
+ (a 95% probability level). For comparison the dataplot output for the
+ same data is in <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda353.htm" target="_top">section
+ 1.3.5.3</a> of the <a href="http://www.itl.nist.gov/div898/handbook/" target="_top">NIST/SEMATECH
+ e-Handbook of Statistical Methods.</a>.
+ </p>
+<pre class="programlisting"> ________________________________________________
+ Student t test for two samples (equal variances)
+ ________________________________________________
+
+ Number of Observations (Sample 1) = 249
+ Sample 1 Mean = 20.14458
+ Sample 1 Standard Deviation = 6.41470
+ Number of Observations (Sample 2) = 79
+ Sample 2 Mean = 30.48101
+ Sample 2 Standard Deviation = 6.10771
+ Degrees of Freedom = 326.00000
+ Pooled Standard Deviation = 326.00000
+ T Statistic = -12.62059
+ Probability that difference is due to chance = 5.273e-030
+
+ Results for Alternative Hypothesis and alpha = 0.0500
+
+ Alternative Hypothesis Conclusion
+ Sample 1 Mean != Sample 2 Mean NOT REJECTED
+ Sample 1 Mean &lt; Sample 2 Mean NOT REJECTED
+ Sample 1 Mean &gt; Sample 2 Mean REJECTED
+</pre>
+<p>
+ So with a probability that the difference is due to chance of just
+ 5.273e-030, we can safely conclude that there is indeed a difference.
+ </p>
+<p>
+ The tests on the alternative hypothesis show that we must also reject
+ the hypothesis that Sample 1 Mean is greater than that for Sample 2:
+ in this case Sample 1 represents the miles per gallon for Japanese
+ cars, and Sample 2 the miles per gallon for US cars, so we conclude
+ that Japanese cars are on average more fuel efficient.
+ </p>
+<p>
+ Now that we have the simple case out of the way, let's look for a moment
+ at the more complex one: that the standard deviations of the two samples
+ are not equal. In this case the formula for the t-statistic becomes:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../../equations/dist_tutorial2.png"></span>
+ </p>
+<p>
+ And for the combined degrees of freedom we use the Welch-Satterthwaite
+ approximation:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../../../equations/dist_tutorial3.png"></span>
+ </p>
+<p>
+ Note that this is one of the rare situations where the degrees-of-freedom
+ parameter to the Student's t distribution is a real number, and not
+ an integer value.
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ Some statistical packages truncate the effective degrees of freedom
+ to an integer value: this may be necessary if you are relying on
+ lookup tables, but since our code fully supports non-integer degrees
+ of freedom there is no need to truncate in this case. Also note that
+ when the degrees of freedom is small then the Welch-Satterthwaite
+ approximation may be a significant source of error.
+ </p></td></tr>
+</table></div>
+<p>
+ Putting these formulae into code we get:
+ </p>
+<pre class="programlisting">
+<span class="comment">// Degrees of freedom:
+</span><span class="keyword">double</span> <span class="identifier">v</span> <span class="special">=</span> <span class="identifier">Sd1</span> <span class="special">*</span> <span class="identifier">Sd1</span> <span class="special">/</span> <span class="identifier">Sn1</span> <span class="special">+</span> <span class="identifier">Sd2</span> <span class="special">*</span> <span class="identifier">Sd2</span> <span class="special">/</span> <span class="identifier">Sn2</span><span class="special">;</span>
+<span class="identifier">v</span> <span class="special">*=</span> <span class="identifier">v</span><span class="special">;</span>
+<span class="keyword">double</span> <span class="identifier">t1</span> <span class="special">=</span> <span class="identifier">Sd1</span> <span class="special">*</span> <span class="identifier">Sd1</span> <span class="special">/</span> <span class="identifier">Sn1</span><span class="special">;</span>
+<span class="identifier">t1</span> <span class="special">*=</span> <span class="identifier">t1</span><span class="special">;</span>
+<span class="identifier">t1</span> <span class="special">/=</span> <span class="special">(</span><span class="identifier">Sn1</span> <span class="special">-</span> <span class="number">1</span><span class="special">);</span>
+<span class="keyword">double</span> <span class="identifier">t2</span> <span class="special">=</span> <span class="identifier">Sd2</span> <span class="special">*</span> <span class="identifier">Sd2</span> <span class="special">/</span> <span class="identifier">Sn2</span><span class="special">;</span>
+<span class="identifier">t2</span> <span class="special">*=</span> <span class="identifier">t2</span><span class="special">;</span>
+<span class="identifier">t2</span> <span class="special">/=</span> <span class="special">(</span><span class="identifier">Sn2</span> <span class="special">-</span> <span class="number">1</span><span class="special">);</span>
+<span class="identifier">v</span> <span class="special">/=</span> <span class="special">(</span><span class="identifier">t1</span> <span class="special">+</span> <span class="identifier">t2</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"Degrees of Freedom"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">v</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+<span class="comment">// t-statistic:
+</span><span class="keyword">double</span> <span class="identifier">t_stat</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">Sm1</span> <span class="special">-</span> <span class="identifier">Sm2</span><span class="special">)</span> <span class="special">/</span> <span class="identifier">sqrt</span><span class="special">(</span><span class="identifier">Sd1</span> <span class="special">*</span> <span class="identifier">Sd1</span> <span class="special">/</span> <span class="identifier">Sn1</span> <span class="special">+</span> <span class="identifier">Sd2</span> <span class="special">*</span> <span class="identifier">Sd2</span> <span class="special">/</span> <span class="identifier">Sn2</span><span class="special">);</span>
+<span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">55</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">left</span> <span class="special">&lt;&lt;</span> <span class="string">"T Statistic"</span> <span class="special">&lt;&lt;</span> <span class="string">"= "</span> <span class="special">&lt;&lt;</span> <span class="identifier">t_stat</span> <span class="special">&lt;&lt;</span> <span class="string">"\n"</span><span class="special">;</span>
+</pre>
+<p>
+ Thereafter the code and the tests are performed the same as before.
+ Using are car mileage data again, here's what the output looks like:
+ </p>
+<pre class="programlisting"> __________________________________________________
+ Student t test for two samples (unequal variances)
+ __________________________________________________
+
+ Number of Observations (Sample 1) = 249
+ Sample 1 Mean = 20.145
+ Sample 1 Standard Deviation = 6.4147
+ Number of Observations (Sample 2) = 79
+ Sample 2 Mean = 30.481
+ Sample 2 Standard Deviation = 6.1077
+ Degrees of Freedom = 136.87
+ T Statistic = -12.946
+ Probability that difference is due to chance = 1.571e-025
+
+ Results for Alternative Hypothesis and alpha = 0.0500
+
+ Alternative Hypothesis Conclusion
+ Sample 1 Mean != Sample 2 Mean NOT REJECTED
+ Sample 1 Mean &lt; Sample 2 Mean NOT REJECTED
+ Sample 1 Mean &gt; Sample 2 Mean REJECTED
+</pre>
+<p>
+ This time allowing the variances in the two samples to differ has yielded
+ a higher likelihood that the observed difference is down to chance
+ alone (1.571e-025 compared to 5.273e-030 when equal variances were
+ assumed). However, the conclusion remains the same: US cars are less
+ fuel efficient than Japanese models.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tut_mean_size.html"><img src="../../../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../st_eg.html"><img src="../../../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../../index.html"><img src="../../../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="paired_st.html"><img src="../../../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,62 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Overview</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../index.html" title="Math Toolkit">
+<link rel="up" href="../index.html" title="Math Toolkit">
+<link rel="prev" href="../index.html" title="Math Toolkit">
+<link rel="next" href="main_overview/intro.html" title="About the Math Toolkit">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="main_overview/intro.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="math_toolkit.main_overview"></a> Overview
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"> About the Math Toolkit</span></dt>
+<dt><span class="section"> Navigation</span></dt>
+<dt><span class="section"><a href="main_overview/directories.html"> Directory and
+ File Structure</a></span></dt>
+<dt><span class="section"> Namespaces</span></dt>
+<dt><span class="section"><a href="main_overview/result_type.html"> Calculation
+ of the Type of the Result</a></span></dt>
+<dt><span class="section"> Error Handling</span></dt>
+<dt><span class="section"><a href="main_overview/pol_overview.html"> Configuration
+ and Policies</a></span></dt>
+<dt><span class="section"> Thread Safety</span></dt>
+<dt><span class="section"> Performance</span></dt>
+<dt><span class="section"><a href="main_overview/history1.html"> History and What's
+ New</a></span></dt>
+<dt><span class="section"><a href="main_overview/contact.html"> Contact Info and
+ Support</a></span></dt>
+</dl></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="main_overview/intro.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/contact.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/contact.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,58 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Contact Info and Support</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../main_overview.html" title="Overview">
+<link rel="prev" href="history1.html" title="History and What's New">
+<link rel="next" href="../dist.html" title="Statistical Distributions and Functions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="history1.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../dist.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.main_overview.contact"></a><a href="contact.html" title="Contact Info and Support"> Contact Info and
+ Support</a>
+</h3></div></div></div>
+<p>
+ The main support for this library is via the Boost mailing lists:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Use the <a href="http://www.boost.org/more/mailing_lists.htm#users" target="_top">boost-user
+ list</a> for general support questions.
+ </li>
+<li>
+ Use the <a href="http://www.boost.org/more/mailing_lists.htm#main" target="_top">boost-developer
+ list</a> for discussion about implementation and or submission of extensions.
+ </li>
+</ul></div>
+<p>
+ You can also find JM at john - at - johnmaddock.co.uk and PAB at pbristow
+ - at - hetp.u-net.com.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="history1.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../dist.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/directories.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/directories.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,120 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Directory and File Structure</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../main_overview.html" title="Overview">
+<link rel="prev" href="navigation.html" title="Navigation">
+<link rel="next" href="namespaces.html" title="Namespaces">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="navigation.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="namespaces.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.main_overview.directories"></a><a href="directories.html" title="Directory and File Structure"> Directory and
+ File Structure</a>
+</h3></div></div></div>
+<a name="math_toolkit.main_overview.directories.boost_math"></a><h5>
+<a name="id435869"></a>
+ boost/math
+ </h5>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">/concepts/</span></dt>
+<dd><p>
+ Prototype defining the <span class="bold"><strong>essential</strong></span> features
+ of a RealType class (see real_concept.hpp). Most applications will use
+ <code class="computeroutput"><span class="keyword">double</span></code> as the RealType (and
+ short <code class="computeroutput"><span class="keyword">typedef</span></code> names of distributions
+ are reserved for this type where possible), a few will use <code class="computeroutput"><span class="keyword">float</span></code> or <code class="computeroutput"><span class="keyword">long</span>
+ <span class="keyword">double</span></code>, but it is also possible
+ to use higher precision types like NTL::RR
+ that conform to the requirements specified by real_concept.
+ </p></dd>
+<dt><span class="term">/constants/</span></dt>
+<dd><p>
+ Templated definition of some highly accurate math constants (in constants.hpp).
+ </p></dd>
+<dt><span class="term">/distributions/</span></dt>
+<dd><p>
+ Distributions used in mathematics and, especially, statistics: Gaussian,
+ Students-t, Fisher, Binomial etc
+ </p></dd>
+<dt><span class="term">/policies/</span></dt>
+<dd><p>
+ Policy framework, for handling user requested behaviour modifications.
+ </p></dd>
+<dt><span class="term">/special_functions/</span></dt>
+<dd><p>
+ Math functions generally regarded as 'special', like beta, cbrt, erf,
+ gamma, lgamma, tgamma ... (Some of these are specified in C++, and C99/TR1,
+ and perhaps TR2).
+ </p></dd>
+<dt><span class="term">/tools/</span></dt>
+<dd><p>
+ Tools used by functions, like evaluating polynomials, continued fractions,
+ root finding, precision and limits, and by tests. Some will find application
+ outside this package.
+ </p></dd>
+</dl>
+</div>
+<a name="math_toolkit.main_overview.directories.boost_libs"></a><h5>
+<a name="id436060"></a>
+ boost/libs
+ </h5>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">/doc/</span></dt>
+<dd><p>
+ Documentation source files in Quickbook format processed into html and
+ pdf formats.
+ </p></dd>
+<dt><span class="term">/examples/</span></dt>
+<dd><p>
+ Examples and demos of using math functions and distributions.
+ </p></dd>
+<dt><span class="term">/performance/</span></dt>
+<dd><p>
+ Performance testing and tuning program.
+ </p></dd>
+<dt><span class="term">/test/</span></dt>
+<dd><p>
+ Test files, in various .cpp files, most using Boost.Test (some with test
+ data as .ipp files, usually generated using NTL RR type with ample precision
+ for the type, often for precisions suitable for up to 256-bit significand
+ real types).
+ </p></dd>
+<dt><span class="term">/tools/</span></dt>
+<dd><p>
+ Programs used to generate test data. Also changes to the NTL
+ released package to provide a few additional (and vital) extra features.
+ </p></dd>
+</dl>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="navigation.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="namespaces.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/error_handling.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/error_handling.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,895 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Error Handling</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../main_overview.html" title="Overview">
+<link rel="prev" href="result_type.html" title="Calculation of the Type of the Result">
+<link rel="next" href="pol_overview.html" title="Configuration and Policies">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="result_type.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="pol_overview.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.main_overview.error_handling"></a> Error Handling
+</h3></div></div></div>
+<a name="math_toolkit.main_overview.error_handling.quick_reference"></a><h5>
+<a name="id491012"></a>
+ <a href="error_handling.html#math_toolkit.main_overview.error_handling.quick_reference">Quick
+ Reference</a>
+ </h5>
+<p>
+ Handling of errors by this library is split into two orthogonal parts:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ What kind of error has been raised?
+ </li>
+<li>
+ What should be done when the error is raised?
+ </li>
+</ul></div>
+<p>
+ The kinds of errors that can be raised are:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">Domain Error</span></dt>
+<dd><p>
+ Occurs when one or more arguments to a function are out of range.
+ </p></dd>
+<dt><span class="term">Pole Error</span></dt>
+<dd><p>
+ Occurs when the particular arguments cause the function to be evaluated
+ at a pole with no well defined residual value. For example if tgamma
+ is evaluated at exactly -2, the function approaches different limiting
+ values depending upon whether you approach from just above or just below
+ -2. Hence the function has no well defined value at this point and a
+ Pole Error will be raised.
+ </p></dd>
+<dt><span class="term">Overflow Error</span></dt>
+<dd><p>
+ Occurs when the result is either infinite, or too large to represent
+ in the numeric type being returned by the function.
+ </p></dd>
+<dt><span class="term">Underflow Error</span></dt>
+<dd><p>
+ Occurs when the result is not zero, but is too small to be represented
+ by any other value in the type being returned by the function.
+ </p></dd>
+<dt><span class="term">Denormalisation Error</span></dt>
+<dd><p>
+ Occurs when the returned result would be a denormalised value.
+ </p></dd>
+<dt><span class="term">Evaluation Error</span></dt>
+<dd><p>
+ Occurs when an internal error occured that prevented the result from
+ being evaluated: this should never occur, but if it does, then it's likely
+ to be due to an iterative method not converging fast enough.
+ </p></dd>
+</dl>
+</div>
+<p>
+ The action undertaken by each error condition is determined by the current
+ Policy in effect. This can be
+ changed program-wide by setting some configuration macros, or at namespace
+ scope, or at the call site (by specifying a specific policy in the function
+ call).
+ </p>
+<p>
+ The available actions are:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">throw_on_error</span></dt>
+<dd><p>
+ Throws the exception most appropriate to the error condition.
+ </p></dd>
+<dt><span class="term">errno_on_error</span></dt>
+<dd><p>
+ Sets ::errno to an appropriate value, and then returns the most appropriate
+ result
+ </p></dd>
+<dt><span class="term">ignore_error</span></dt>
+<dd><p>
+ Ignores the error and simply the returns the most appropriate result.
+ </p></dd>
+<dt><span class="term">user_error</span></dt>
+<dd><p>
+ Calls a <a href="../policy/pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">user-supplied
+ error handler</a>.
+ </p></dd>
+</dl>
+</div>
+<p>
+ The following tables show all the permutations of errors and actions, with
+ the default action for each error shown in bold:
+ </p>
+<div class="table">
+<a name="id491270"></a><p class="title"><b>Table 1. Possible Actions for Domain Errors</b></p>
+<div class="table-contents"><table class="table" summary="Possible Actions for Domain Errors">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Action
+ </p>
+ </th>
+<th>
+ <p>
+ Behaviour
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ throw_on_error
+ </p>
+ </td>
+<td>
+ <p>
+ <span class="bold"><strong>Throws <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code></strong></span>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ errno_on_error
+ </p>
+ </td>
+<td>
+ <p>
+ Sets <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
+ to <code class="computeroutput"><span class="identifier">EDOM</span></code> and returns
+ <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">quiet_NaN</span><span class="special">()</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ignore_error
+ </p>
+ </td>
+<td>
+ <p>
+ Returns <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">quiet_NaN</span><span class="special">()</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ user_error
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the result of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">user_domain_error</span></code>:
+ <a href="../policy/pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">this
+ function must be defined by the user</a>.
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id491586"></a><p class="title"><b>Table 2. Possible Actions for Pole Errors</b></p>
+<div class="table-contents"><table class="table" summary="Possible Actions for Pole Errors">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Action
+ </p>
+ </th>
+<th>
+ <p>
+ Behaviour
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ throw_on_error
+ </p>
+ </td>
+<td>
+ <p>
+ <span class="bold"><strong>Throws <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code></strong></span>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ errno_on_error
+ </p>
+ </td>
+<td>
+ <p>
+ Sets <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
+ to <code class="computeroutput"><span class="identifier">EDOM</span></code> and returns
+ <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">quiet_NaN</span><span class="special">()</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ignore_error
+ </p>
+ </td>
+<td>
+ <p>
+ Returns <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">quiet_NaN</span><span class="special">()</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ user_error
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the result of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">user_pole_error</span></code>:
+ <a href="../policy/pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">this
+ function must be defined by the user</a>.
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id491900"></a><p class="title"><b>Table 3. Possible Actions for Overflow Errors</b></p>
+<div class="table-contents"><table class="table" summary="Possible Actions for Overflow Errors">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Action
+ </p>
+ </th>
+<th>
+ <p>
+ Behaviour
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ throw_on_error
+ </p>
+ </td>
+<td>
+ <p>
+ <span class="bold"><strong>Throws <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">overflow_error</span></code></strong></span>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ errno_on_error
+ </p>
+ </td>
+<td>
+ <p>
+ Sets <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
+ to <code class="computeroutput"><span class="identifier">ERANGE</span></code> and returns
+ <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">()</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ignore_error
+ </p>
+ </td>
+<td>
+ <p>
+ Returns <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">()</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ user_error
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the result of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">user_overflow_error</span></code>:
+ <a href="../policy/pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">this
+ function must be defined by the user</a>.
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id492216"></a><p class="title"><b>Table 4. Possible Actions for Underflow Errors</b></p>
+<div class="table-contents"><table class="table" summary="Possible Actions for Underflow Errors">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Action
+ </p>
+ </th>
+<th>
+ <p>
+ Behaviour
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ throw_on_error
+ </p>
+ </td>
+<td>
+ <p>
+ Throws <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">underflow_error</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ errno_on_error
+ </p>
+ </td>
+<td>
+ <p>
+ Sets <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
+ to <code class="computeroutput"><span class="identifier">ERANGE</span></code> and returns
+ 0.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ignore_error
+ </p>
+ </td>
+<td>
+ <p>
+ <span class="bold"><strong>Returns 0</strong></span>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ user_error
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the result of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">user_underflow_error</span></code>:
+ <a href="../policy/pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">this
+ function must be defined by the user</a>.
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id492440"></a><p class="title"><b>Table 5. Possible Actions for Denorm Errors</b></p>
+<div class="table-contents"><table class="table" summary="Possible Actions for Denorm Errors">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Action
+ </p>
+ </th>
+<th>
+ <p>
+ Behaviour
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ throw_on_error
+ </p>
+ </td>
+<td>
+ <p>
+ Throws <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">underflow_error</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ errno_on_error
+ </p>
+ </td>
+<td>
+ <p>
+ Sets <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
+ to <code class="computeroutput"><span class="identifier">ERANGE</span></code> and returns
+ the denormalised value.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ignore_error
+ </p>
+ </td>
+<td>
+ <p>
+ <span class="bold"><strong>Returns the denormalised value.</strong></span>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ user_error
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the result of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">user_denorm_error</span></code>:
+ <a href="../policy/pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">this
+ function must be defined by the user</a>.
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id492664"></a><p class="title"><b>Table 6. Possible Actions for Internal Evaluation
+ Errors</b></p>
+<div class="table-contents"><table class="table" summary="Possible Actions for Internal Evaluation
+ Errors">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Action
+ </p>
+ </th>
+<th>
+ <p>
+ Behaviour
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ throw_on_error
+ </p>
+ </td>
+<td>
+ <p>
+ <span class="bold"><strong>Throws <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">evaluation_error</span></code></strong></span>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ errno_on_error
+ </p>
+ </td>
+<td>
+ <p>
+ Sets <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
+ to <code class="computeroutput"><span class="identifier">EDOM</span></code> and returns
+ <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">()</span></code>.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ignore_error
+ </p>
+ </td>
+<td>
+ <p>
+ Returns <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">()</span></code>.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ user_error
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the result of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">user_evaluation_error</span></code>:
+ <a href="../policy/pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">this
+ function must be defined by the user</a>.
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><a name="math_toolkit.main_overview.error_handling.rationale"></a><h5>
+<a name="id493000"></a>
+ Rationale
+ </h5>
+<p>
+ The flexibility of the current implementation should be reasonably obvious,
+ the default behaviours were chosen based on feedback during the formal review
+ of this library. It was felt that:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Genuine errors should be flagged with exceptions rather than following
+ C-compatible behaviour and setting ::errno.
+ </li>
+<li>
+ Numeric underflow and denormalised results were not considered to be fatal
+ errors in most cases, so it was felt that these should be ignored.
+ </li>
+</ul></div>
+<a name="math_toolkit.main_overview.error_handling.finding_more_information"></a><h5>
+<a name="id493049"></a>
+ <a href="error_handling.html#math_toolkit.main_overview.error_handling.finding_more_information">Finding
+ More Information</a>
+ </h5>
+<p>
+ There are some pre-processor macro defines that can be used to <a href="../policy/pol_ref/policy_defaults.html" title="Using macros to Change the Policy Defaults">change
+ the policy defaults</a>. See also the <a href="../policy.html" title="Policies">policy
+ section</a>.
+ </p>
+<p>
+ An example is at the Policy tutorial in <a href="../policy/pol_tutorial/changing_policy_defaults.html" title="Changing the Policy Defaults">Changing
+ the Policy Defaults</a>.
+ </p>
+<p>
+ Full source code of this typical example of passing a 'bad' argument (negative
+ degrees of freedom) to Student's t distribution is <a href="../dist/stat_tut/weg/error_eg.html" title="Error Handling Example">in
+ the error handling example</a>.
+ </p>
+<p>
+ The various kind of errors are described in more detail below.
+ </p>
+<a name="domain_error"></a><a name="math_toolkit.main_overview.error_handling.domain_errors"></a><h5>
+<a name="id493143"></a>
+ <a href="error_handling.html#math_toolkit.main_overview.error_handling.domain_errors">Domain
+ Errors</a>
+ </h5>
+<p>
+ When a special function is passed an argument that is outside the range of
+ values for which that function is defined, then the function returns the
+ result of:
+ </p>
+<pre class="programlisting">
+<span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">raise_domain_error</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</span><span class="identifier">FunctionName</span><span class="special">,</span> <span class="identifier">Message</span><span class="special">,</span> <span class="identifier">Val</span><span class="special">,</span> Policy<span class="special">);</span>
+</pre>
+<p>
+ Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating-point
+ type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
+ is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
+ is an error message describing the problem, Val is the value that was out
+ of range, and Policy is the current
+ policy in use for the function that was called.
+ </p>
+<p>
+ The default policy behaviour of this function is to throw a std::domain_error
+ C++ exception. But if the Policy
+ is to ignore the error, or set global ::errno, then a NaN will be returned.
+ </p>
+<p>
+ This behaviour is chosen to assist compatibility with the behaviour of <span class="emphasis"><em>ISO/IEC
+ 9899:1999 Programming languages - C</em></span> and with the <a href="../../www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf" target="_top">Draft
+ Technical Report on C++ Library Extensions, 2005-06-24, section 5.2.1, paragraph
+ 6</a>:
+ </p>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ <span class="emphasis"><em>"Each of the functions declared above shall return a NaN
+ (Not a Number) if any argument value is a NaN, but it shall not report
+ a domain error. Otherwise, each of the functions declared above shall
+ report a domain error for just those argument values for which:</em></span>
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ <span class="emphasis"><em>"the function description's Returns clause explicitly
+ specifies a domain, and those arguments fall outside the specified domain;
+ or</em></span>
+ </p>
+<p>
+ </p>
+<p>
+ <span class="emphasis"><em>"the corresponding mathematical function value has a non-zero
+ imaginary component; or</em></span>
+ </p>
+<p>
+ </p>
+<p>
+ <span class="emphasis"><em>"the corresponding mathematical function is not mathematically
+ defined.</em></span>
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ <span class="emphasis"><em>"Note 2: A mathematical function is mathematically defined
+ for a given set of argument values if it is explicitly defined for that
+ set of argument values or if its limiting value exists and does not depend
+ on the direction of approach."</em></span>
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<p>
+ Note that in order to support information-rich error messages when throwing
+ exceptions, <code class="computeroutput"><span class="identifier">Message</span></code> must
+ contain a Boost.Format
+ recognised format specifier: the argument <code class="computeroutput"><span class="identifier">Val</span></code>
+ is inserted into the error message according to the specifier used.
+ </p>
+<p>
+ For example if <code class="computeroutput"><span class="identifier">Message</span></code> contains
+ a "%1%" then it is replaced by the value of <code class="computeroutput"><span class="identifier">Val</span></code>
+ to the full precision of T, where as "%.3g" would contain the value
+ of <code class="computeroutput"><span class="identifier">Val</span></code> to 3 digits. See the
+ Boost.Format documentation
+ for more details.
+ </p>
+<a name="pole_error"></a><a name="math_toolkit.main_overview.error_handling.evaluation_at_a_pole"></a><h5>
+<a name="id493528"></a>
+ <a href="error_handling.html#math_toolkit.main_overview.error_handling.evaluation_at_a_pole">Evaluation
+ at a pole</a>
+ </h5>
+<p>
+ When a special function is passed an argument that is at a pole without a
+ well defined residual value, then the function returns the result of:
+ </p>
+<pre class="programlisting">
+<span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">raise_pole_error</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</span><span class="identifier">FunctionName</span><span class="special">,</span> <span class="identifier">Message</span><span class="special">,</span> <span class="identifier">Val</span><span class="special">,</span> Policy<span class="special">);</span>
+</pre>
+<p>
+ Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating point
+ type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
+ is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
+ is an error message describing the problem, <code class="computeroutput"><span class="identifier">Val</span></code>
+ is the value of the argument that is at a pole, and Policy
+ is the current policy in use for the function that was called.
+ </p>
+<p>
+ The default behaviour of this function is to throw a std::domain_error exception.
+ But <a href="../policy/pol_ref/error_handling_policies.html" title="Error Handling Policies">error
+ handling policies</a> can be used to change this, for example to <code class="computeroutput"><span class="identifier">ignore_error</span></code> and return NaN.
+ </p>
+<p>
+ Note that in order to support information-rich error messages when throwing
+ exceptions, <code class="computeroutput"><span class="identifier">Message</span></code> must
+ contain a Boost.Format
+ recognised format specifier: the argument <code class="computeroutput"><span class="identifier">val</span></code>
+ is inserted into the error message according to the specifier used.
+ </p>
+<p>
+ For example if <code class="computeroutput"><span class="identifier">Message</span></code> contains
+ a "%1%" then it is replaced by the value of <code class="computeroutput"><span class="identifier">val</span></code>
+ to the full precision of T, where as "%.3g" would contain the value
+ of <code class="computeroutput"><span class="identifier">val</span></code> to 3 digits. See the
+ Boost.Format documentation
+ for more details.
+ </p>
+<a name="overflow_error"></a><a name="math_toolkit.main_overview.error_handling.numeric_overflow"></a><h5>
+<a name="id493851"></a>
+ <a href="error_handling.html#math_toolkit.main_overview.error_handling.numeric_overflow">Numeric
+ Overflow</a>
+ </h5>
+<p>
+ When the result of a special function is too large to fit in the argument
+ floating-point type, then the function returns the result of:
+ </p>
+<pre class="programlisting">
+<span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">raise_overflow_error</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</span><span class="identifier">FunctionName</span><span class="special">,</span> <span class="identifier">Message</span><span class="special">,</span> Policy<span class="special">);</span>
+</pre>
+<p>
+ Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating-point
+ type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
+ is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
+ is an error message describing the problem, and Policy
+ is the current policy in use for the function that was called.
+ </p>
+<p>
+ The default policy for this function is that <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">overflow_error</span></code>
+ C++ exception is thrown. But if, for example, an <code class="computeroutput"><span class="identifier">ignore_error</span></code>
+ policy is used, then returns <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">()</span></code>.
+ In this situation if the type <code class="computeroutput"><span class="identifier">T</span></code>
+ doesn't support infinities, the maximum value for the type is returned.
+ </p>
+<a name="underflow_error"></a><a name="math_toolkit.main_overview.error_handling.numeric_underflow"></a><h5>
+<a name="id494133"></a>
+ <a href="error_handling.html#math_toolkit.main_overview.error_handling.numeric_underflow">Numeric
+ Underflow</a>
+ </h5>
+<p>
+ If the result of a special function is known to be non-zero, but the calculated
+ result underflows to zero, then the function returns the result of:
+ </p>
+<pre class="programlisting">
+<span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">raise_underflow_error</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</span><span class="identifier">FunctionName</span><span class="special">,</span> <span class="identifier">Message</span><span class="special">,</span> Policy<span class="special">);</span>
+</pre>
+<p>
+ Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating point
+ type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
+ is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
+ is an error message describing the problem, and Policy
+ is the current policy in use for the called function.
+ </p>
+<p>
+ The default version of this function returns zero. But with another policy,
+ like <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, throws
+ an <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">underflow_error</span></code> C++ exception.
+ </p>
+<a name="denorm_error"></a><a name="math_toolkit.main_overview.error_handling.denormalisation_errors"></a><h5>
+<a name="id494354"></a>
+ <a href="error_handling.html#math_toolkit.main_overview.error_handling.denormalisation_errors">Denormalisation
+ Errors</a>
+ </h5>
+<p>
+ If the result of a special function is a denormalised value <span class="emphasis"><em>z</em></span>
+ then the function returns the result of:
+ </p>
+<pre class="programlisting">
+<span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">raise_denorm_error</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">FunctionName</span><span class="special">,</span> <span class="identifier">Message</span><span class="special">,</span> Policy<span class="special">);</span>
+</pre>
+<p>
+ Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating point
+ type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
+ is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
+ is an error message describing the problem, and Policy
+ is the current policy in use for the called function.
+ </p>
+<p>
+ The default version of this function returns <span class="emphasis"><em>z</em></span>. But
+ with another policy, like <code class="computeroutput"><span class="identifier">throw_on_error</span></code>
+ throws an <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">underflow_error</span></code> C++ exception.
+ </p>
+<a name="evaluation_error"></a><a name="math_toolkit.main_overview.error_handling.evaluation_errors"></a><h5>
+<a name="id494593"></a>
+ <a href="error_handling.html#math_toolkit.main_overview.error_handling.evaluation_errors">Evaluation
+ Errors</a>
+ </h5>
+<p>
+ When a special function calculates a result that is known to be erroneous,
+ or where the result is incalculable then it calls:
+ </p>
+<pre class="programlisting">
+<span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">raise_evaluation_error</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</span><span class="identifier">FunctionName</span><span class="special">,</span> <span class="identifier">Message</span><span class="special">,</span> <span class="identifier">Val</span><span class="special">,</span> Policy<span class="special">);</span>
+</pre>
+<p>
+ Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating point
+ type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
+ is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
+ is an error message describing the problem, <code class="computeroutput"><span class="identifier">Val</span></code>
+ is the erroneous value, and Policy
+ is the current policy in use for the called function.
+ </p>
+<p>
+ The default behaviour of this function is to throw a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">evaluation_error</span></code>.
+ </p>
+<p>
+ Note that in order to support information rich error messages when throwing
+ exceptions, <code class="computeroutput"><span class="identifier">Message</span></code> must
+ contain a Boost.Format
+ recognised format specifier: the argument <code class="computeroutput"><span class="identifier">val</span></code>
+ is inserted into the error message according to the specifier used.
+ </p>
+<p>
+ For example if <code class="computeroutput"><span class="identifier">Message</span></code> contains
+ a "%1%" then it is replaced by the value of <code class="computeroutput"><span class="identifier">val</span></code>
+ to the full precision of T, where as "%.3g" would contain the value
+ of <code class="computeroutput"><span class="identifier">val</span></code> to 3 digits. See the
+ Boost.Format documentation
+ for more details.
+ </p>
+<a name="checked_narrowing_cast"></a><a name="math_toolkit.main_overview.error_handling.errors_from_typecasts"></a><h5>
+<a name="id494922"></a>
+ <a href="error_handling.html#math_toolkit.main_overview.error_handling.errors_from_typecasts">Errors
+ from typecasts</a>
+ </h5>
+<p>
+ Many special functions evaluate their results at a higher precision than
+ their arguments in order to ensure full machine precision in the result:
+ for example, a function passed a float argument may evaluate its result using
+ double precision internally. Many of the errors listed above may therefore
+ occur not during evaluation, but when converting the result to the narrower
+ result type. The function:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">checked_narrowing_cast</span><span class="special">(</span><span class="identifier">U</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">);</span>
+</pre>
+<p>
+ Is used to perform these conversions, and will call the error handlers listed
+ above on overflow, underflow
+ or denormalisation.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="result_type.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="pol_overview.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/history1.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/history1.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,214 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>History and What's New</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../main_overview.html" title="Overview">
+<link rel="prev" href="perf_over.html" title="Performance">
+<link rel="next" href="contact.html" title="Contact Info and Support">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="perf_over.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="contact.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.main_overview.history1"></a><a href="history1.html" title="History and What's New"> History and What's
+ New</a>
+</h3></div></div></div>
+<p>
+ <a name="math_toolkit.main_overview.history1.milestone_5__post_review_first_official_release"></a>
+ </p>
+<h5>
+<a name="id495695"></a>
+ <a href="history1.html#math_toolkit.main_overview.history1.milestone_5__post_review_first_official_release">Milestone
+ 5: Post Review First Official Release</a>
+ </h5>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Added Policy based framework that allows fine grained control over function
+ behaviour.
+ </li>
+<li>
+<span class="bold"><strong>Breaking change:</strong></span> Changed default behaviour
+ for domain, pole and overflow errors to throw an exception (based on
+ review feedback), this behaviour can be customised using Policy's.
+ </li>
+<li>
+<span class="bold"><strong>Breaking change:</strong></span> Changed exception thrown
+ when an internal evaluation error occurs to boost::math::evaluation_error.
+ </li>
+<li>
+<span class="bold"><strong>Breaking change:</strong></span> Changed discrete quantiles
+ to return an integer result: this is anything up to 20 times faster than
+ finding the true root, this behaviour can be customised using Policy's.
+ </li>
+<li>
+ Polynomial/rational function evaluation is now customisable and hopefully
+ faster than before.
+ </li>
+<li>
+ Added performance test program.
+ </li>
+</ul></div>
+<p>
+ <a name="math_toolkit.main_overview.history1.milestone_4__second_review_candidate__1st_march_2007_"></a>
+ </p>
+<h5>
+<a name="id495800"></a>
+ <a href="history1.html#math_toolkit.main_overview.history1.milestone_4__second_review_candidate__1st_march_2007_">Milestone
+ 4: Second Review Candidate (1st March 2007)</a>
+ </h5>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Moved Xiaogang Zhang's Bessel Functions code into the library, and brought
+ them into line with the rest of the code.
+ </li>
+<li>
+ Added C# "Distribution Explorer" demo application.
+ </li>
+</ul></div>
+<p>
+ <a name="math_toolkit.main_overview.history1.milestone_3__first_review_candidate__31st_dec_2006_"></a>
+ </p>
+<h5>
+<a name="id495842"></a>
+ <a href="history1.html#math_toolkit.main_overview.history1.milestone_3__first_review_candidate__31st_dec_2006_">Milestone
+ 3: First Review Candidate (31st Dec 2006)</a>
+ </h5>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Implemented the main probability distribution and density functions.
+ </li>
+<li>
+ Implemented digamma.
+ </li>
+<li>
+ Added more factorial functions.
+ </li>
+<li>
+ Implemented the Hermite, Legendre and Laguerre polynomials plus the spherical
+ harmonic functions from TR1.
+ </li>
+<li>
+ Moved Xiaogang Zhang's elliptic integral code into the library, and brought
+ them into line with the rest of the code.
+ </li>
+<li>
+ Moved Hubert Holin's existing Boost.Math special functions into this
+ library and brought them into line with the rest of the code.
+ </li>
+</ul></div>
+<p>
+ <a name="math_toolkit.main_overview.history1.milestone_2__released_september_10th_2006"></a>
+ </p>
+<h5>
+<a name="id495906"></a>
+ <a href="history1.html#math_toolkit.main_overview.history1.milestone_2__released_september_10th_2006">Milestone
+ 2: Released September 10th 2006</a>
+ </h5>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Implement preview release of the statistical distributions.
+ </li>
+<li>
+ Added statistical distributions tutorial.
+ </li>
+<li>
+ Implemented root finding algorithms.
+ </li>
+<li>
+ Implemented the inverses of the incomplete gamma and beta functions.
+ </li>
+<li>
+ Rewrite erf/erfc as rational approximations (valid to 128-bit precision).
+ </li>
+<li>
+ Integrated the statistical results generated from the test data with
+ Boost.Test: uses a database of expected results, indexed by test, floating
+ point type, platform, and compiler.
+ </li>
+<li>
+ Improved lgamma near 1 and 2 (rational approximations).
+ </li>
+<li>
+ Improved erf/erfc inverses (rational approximations).
+ </li>
+<li>
+ Implemented Rational function generation (the Remez method).
+ </li>
+</ul></div>
+<p>
+ <a name="math_toolkit.main_overview.history1.milestone_1__released_march_31st_2006"></a>
+ </p>
+<h5>
+<a name="id495982"></a>
+ <a href="history1.html#math_toolkit.main_overview.history1.milestone_1__released_march_31st_2006">Milestone
+ 1: Released March 31st 2006</a>
+ </h5>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Implement gamma/beta/erf functions along with their incomplete counterparts.
+ </li>
+<li>
+ Generate high quality test data, against which future improvements can
+ be judged.
+ </li>
+<li>
+ Provide tools for the evaluation of infinite series, continued fractions,
+ and rational functions.
+ </li>
+<li>
+ Provide tools for testing against tabulated test data, and collecting
+ statistics on error rates.
+ </li>
+<li>
+ Provide sufficient docs for people to be able to find their way around
+ the library.
+ </li>
+</ul></div>
+<p>
+ </p>
+<p>
+ SVN Revisions:
+ </p>
+<p>
+ </p>
+<p>
+ Sandbox revision merged to trunk: 39833. Trunk revision: 39833.
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="perf_over.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="contact.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/intro.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/intro.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,130 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>About the Math Toolkit</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../main_overview.html" title="Overview">
+<link rel="prev" href="../main_overview.html" title="Overview">
+<link rel="next" href="navigation.html" title="Navigation">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../main_overview.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="navigation.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.main_overview.intro"></a> About the Math Toolkit
+</h3></div></div></div>
+<p>
+ This library is divided into three interconnected parts:
+ </p>
+<a name="math_toolkit.main_overview.intro.statistical_distributions"></a><h5>
+<a name="id437693"></a>
+ <a href="intro.html#math_toolkit.main_overview.intro.statistical_distributions">Statistical
+ Distributions</a>
+ </h5>
+<p>
+ Provides a reasonably comprehensive set of <a href="../dist.html" title="Statistical Distributions and Functions">statistical
+ distributions</a>, upon which higher level statistical tests can be built.
+ </p>
+<p>
+ The initial focus is on the central <a href="http://en.wikipedia.org/wiki/Univariate" target="_top">univariate
+ </a> distributions.
+ Both continuous
+ (like normal
+ &amp; Fisher)
+ and discrete
+ (like binomial
+ &amp; Poisson)
+ distributions are provided.
+ </p>
+<p>
+ A comprehensive tutorial is provided,
+ along with a series of <a href="../dist/stat_tut/weg.html" title="Worked Examples">worked
+ examples</a> illustrating how the library is used to conduct statistical
+ tests.
+ </p>
+<a name="math_toolkit.main_overview.intro.mathematical_special_functions"></a><h5>
+<a name="id436171"></a>
+ <a href="intro.html#math_toolkit.main_overview.intro.mathematical_special_functions">Mathematical
+ Special Functions</a>
+ </h5>
+<p>
+ Provides a small number of high quality <a href="../special.html" title="Special Functions">special
+ functions</a>, initially these were concentrated on functions used in
+ statistical applications along with those in the <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf" target="_top">Technical
+ Report on C++ Library Extensions</a>.
+ </p>
+<p>
+ The function families currently implemented are the gamma, beta &amp; 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.
+ </p>
+<p>
+ 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 <a href="http://en.wikipedia.org/wiki/Significand" target="_top">significand
+ (or mantissa)</a> sizes: typically <code class="computeroutput"><span class="keyword">float</span></code>,
+ <code class="computeroutput"><span class="keyword">double</span></code> or <code class="computeroutput"><span class="keyword">long</span>
+ <span class="keyword">double</span></code>.
+ </p>
+<a name="math_toolkit.main_overview.intro.implementation_toolkit"></a><h5>
+<a name="id436296"></a>
+ <a href="intro.html#math_toolkit.main_overview.intro.implementation_toolkit">Implementation
+ Toolkit</a>
+ </h5>
+<p>
+ 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. These tools are currently considered experimental: they are
+ "exposed implementation details" whose interfaces and/or implementations
+ may change.
+ </p>
+<p>
+ There are helpers for the <a href="../toolkit/internals1/series_evaluation.html" title="Series Evaluation">evaluation
+ of infinite series</a>, <a href="../toolkit/internals1/cf.html" title="Continued Fraction Evaluation">continued
+ fractions</a> and <a href="../toolkit/internals1/rational.html" title="Polynomial and Rational Function Evaluation">rational
+ approximations</a>.
+ </p>
+<p>
+ There is a fairly comprehensive set of root finding and <a href="../toolkit/internals1/minima.html" title="Locating Function Minima">function
+ minimisation algorithms</a>: the root finding algorithms are both with and without
+ derivative support.
+ </p>
+<p>
+ A <a href="../toolkit/internals2/minimax.html" title="Minimax Approximations and the Remez Algorithm">Remez algorithm
+ implementation</a> allows for the locating of minimax rational approximations.
+ </p>
+<p>
+ There are also (experimental) classes for the <a href="../toolkit/internals2/polynomials.html" title="Polynomials">manipulation
+ of polynomials</a>, for <a href="../toolkit/internals2/error_test.html" title="Relative Error and Testing">testing
+ a special function against tabulated test data</a>, and for the <a href="../toolkit/internals2/test_data.html" title="Graphing, Profiling, and Generating Test Data for Special Functions">rapid generation of test
+ data</a> and/or data for output to an external graphing application.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../main_overview.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="navigation.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/namespaces.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/namespaces.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,72 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Namespaces</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../main_overview.html" title="Overview">
+<link rel="prev" href="directories.html" title="Directory and File Structure">
+<link rel="next" href="result_type.html" title="Calculation of the Type of the Result">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="directories.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="result_type.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.main_overview.namespaces"></a> Namespaces
+</h3></div></div></div>
+<p>
+ All math functions and distributions are in <code class="computeroutput"><span class="keyword">namespace</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span></code>
+ </p>
+<p>
+ So, for example, the Students-t distribution template in <code class="computeroutput"><span class="keyword">namespace</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span></code> is
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">&gt;</span> <span class="keyword">class</span> <span class="identifier">students_t_distribution</span>
+</pre>
+<p>
+ and can be instantiated with the help of the reserved name <code class="computeroutput"><span class="identifier">students_t</span></code>(for <code class="computeroutput"><span class="identifier">RealType</span>
+ <span class="keyword">double</span></code>)
+ </p>
+<pre class="programlisting">
+<span class="keyword">typedef</span> <span class="identifier">students_t_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">students_t</span><span class="special">;</span>
+
+<span class="identifier">student_t</span> <span class="identifier">mydist</span><span class="special">(</span><span class="number">10</span><span class="special">);</span>
+</pre>
+<p>
+ Functions not intended for use by applications are in <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">detail</span></code>.
+ </p>
+<p>
+ Functions that may have more general use, like <code class="computeroutput"><span class="identifier">digits</span></code>
+ (significand), <code class="computeroutput"><span class="identifier">max_value</span></code>,
+ <code class="computeroutput"><span class="identifier">min_value</span></code> and <code class="computeroutput"><span class="identifier">epsilon</span></code> are in <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span></code>.
+ </p>
+<p>
+ Policy and configuration information
+ is in namespace <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span></code>.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="directories.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="result_type.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/navigation.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/navigation.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,150 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Navigation</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../main_overview.html" title="Overview">
+<link rel="prev" href="intro.html" title="About the Math Toolkit">
+<link rel="next" href="directories.html" title="Directory and File Structure">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="intro.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="directories.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.main_overview.navigation"></a> Navigation
+</h3></div></div></div>
+<p>
+ Used in combination with the configured browser key, the following keys act
+ as handy shortcuts for common navigation tasks.
+ </p>
+<a name="math_toolkit.main_overview.navigation.shortcuts"></a><h6>
+<a name="id440191"></a>
+ Shortcuts
+ </h6>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ <code class="literal"><span class="bold"><strong>p</strong></span></code> - Previous page
+ </p>
+<p>
+ </p>
+<p>
+ <code class="literal"><span class="bold"><strong>n</strong></span></code> - Next page
+ </p>
+<p>
+ </p>
+<p>
+ <code class="literal"><span class="bold"><strong>h</strong></span></code> - home
+ </p>
+<p>
+ </p>
+<p>
+ <code class="literal"><span class="bold"><strong>u</strong></span></code> - Up
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<p>
+ The following table shows how to access these from common browsers:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Browser
+ </p>
+ </th>
+<th>
+ <p>
+ Access Method
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ Internet Explorer
+ </p>
+ </td>
+<td>
+ <p>
+ Alt+Key highlights the link only, so for example to move to the next
+ topic you would need "Alt+n" followed by "Enter".
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Firefox 2.0 and later
+ </p>
+ </td>
+<td>
+ <p>
+ Alt+Shift+Key follows the link, so for example "Alt+Shift+n"
+ will take you to the next topic.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Opera
+ </p>
+ </td>
+<td>
+ <p>
+ Press Shift+Esc followed by the access key.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Konqueror
+ </p>
+ </td>
+<td>
+ <p>
+ Press and release the Ctrl key, followed by the access key
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<p>
+ Some browsers also make these links available in their site-navigation toolbars:
+ in Opera for example you can use Ctrl plus the left and right arrow keys
+ to move between "next" and "previous" topics.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="intro.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="directories.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/perf_over.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/perf_over.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,89 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Performance</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../main_overview.html" title="Overview">
+<link rel="prev" href="threads.html" title="Thread Safety">
+<link rel="next" href="history1.html" title="History and What's New">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="threads.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="history1.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.main_overview.perf_over"></a> Performance
+</h3></div></div></div>
+<p>
+ </p>
+<p>
+ 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 <span class="emphasis"><em>not</em></span> speed.
+ </p>
+<p>
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ </p>
+<p>
+ The two most important things you can do to ensure the best performance
+ from this library are:
+ </p>
+<p>
+ </p>
+<div class="orderedlist"><ol type="1">
+<li>
+ Turn on your compilers optimisations: the difference between "release"
+ and "debug" builds can easily be a <a href="../perf/getting_best.html" title="Getting the Best Performance from this Library">factor
+ of 20</a>.
+ </li>
+<li>
+ Pick your compiler carefully: <a href="../perf/comp_compilers.html" title="Comparing Compilers">performance
+ differences of up to 8 fold</a> have been found between some windows
+ compilers for example.
+ </li>
+</ol></div>
+<p>
+ </p>
+<p>
+ The 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.
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="threads.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="history1.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/pol_overview.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/pol_overview.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,132 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Configuration and Policies</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../main_overview.html" title="Overview">
+<link rel="prev" href="error_handling.html" title="Error Handling">
+<link rel="next" href="threads.html" title="Thread Safety">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="error_handling.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="threads.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.main_overview.pol_overview"></a><a href="pol_overview.html" title="Configuration and Policies"> Configuration
+ and Policies</a>
+</h3></div></div></div>
+<p>
+ </p>
+<p>
+ 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 <a href="../policy/pol_tutorial.html" title="Policy Tutorial">policy
+ tutorial</a> and the <a href="../policy/pol_ref.html" title="Policy Reference">policy
+ reference</a>.
+ </p>
+<p>
+ </p>
+<p>
+ Generally speaking unless you find that the <a href="../policy/pol_tutorial/policy_tut_defaults.html" title="Policies Have Sensible Defaults">default
+ policy behaviour</a> when encountering 'bad' argument values does not
+ meet your needs, you should not need to worry about policies.
+ </p>
+<p>
+ </p>
+<p>
+ Policies are a compile-time mechanism that allow you to change error-handling
+ or calculation precision either program wide, or at the call site.
+ </p>
+<p>
+ </p>
+<p>
+ Although the policy mechanism itself is rather complicated, in practice
+ it is easy to use, and very flexible.
+ </p>
+<p>
+ </p>
+<p>
+ Using policies you can control:
+ </p>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+<a href="../policy/pol_ref/error_handling_policies.html" title="Error Handling Policies">How
+ results from 'bad' arguments are handled</a>, including those that
+ cannot be fully evaluated.
+ </li>
+<li>
+ How <a href="../policy/pol_ref/internal_promotion.html" title="Internal Promotion Policies">accuracy
+ is controlled by internal promotion</a> to use more precise types.
+ </li>
+<li>
+ What working precision
+ should be used to calculate results.
+ </li>
+<li>
+ What to do when a <a href="../policy/pol_ref/assert_undefined.html" title="Mathematically Undefined Function Policies">mathematically
+ undefined function</a> is used: Should this raise a run-time or compile-time
+ error?
+ </li>
+<li>
+ Whether <a href="../policy/pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">discrete
+ functions</a>, like the binomial, should return real or only integral
+ values, and how they are rounded.
+ </li>
+<li>
+ 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.
+ </li>
+</ul></div>
+<p>
+ </p>
+<p>
+ You can control policies:
+ </p>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Using macros
+ to change any default policy: the is the prefered method for installation
+ wide policies.
+ </li>
+<li>
+ At your chosen <a href="../policy/pol_ref/namespace_pol.html" title="Setting Polices at Namespace Scope">namespace
+ scope</a> for distributions and/or functions: this is the prefered
+ method for project, namespace, or translation unit scope policies.
+ </li>
+<li>
+ In an ad-hoc manner <a href="../policy/pol_tutorial/ad_hoc_sf_policies.html" title="Changing the Policy on an Ad Hoc Basis for the Special Functions">by
+ passing a specific policy to a special function</a>, or to a <a href="../policy/pol_tutorial/ad_hoc_dist_policies.html" title="Setting Policies for Distributions on an Ad Hoc Basis">statistical
+ distribution</a>.
+ </li>
+</ul></div>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="error_handling.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="threads.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/result_type.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/result_type.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,150 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Calculation of the Type of the Result</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../main_overview.html" title="Overview">
+<link rel="prev" href="namespaces.html" title="Namespaces">
+<link rel="next" href="error_handling.html" title="Error Handling">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="namespaces.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="error_handling.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.main_overview.result_type"></a><a href="result_type.html" title="Calculation of the Type of the Result"> Calculation
+ of the Type of the Result</a>
+</h3></div></div></div>
+<p>
+ The functions in this library are all overloaded to accept mixed floating
+ point (or mixed integer and floating point type) arguments. So for example:
+ </p>
+<pre class="programlisting">
+<span class="identifier">foo</span><span class="special">(</span><span class="number">1.0</span><span class="special">,</span> <span class="number">2.0</span><span class="special">);</span>
+<span class="identifier">foo</span><span class="special">(</span><span class="number">1.0f</span><span class="special">,</span> <span class="number">2</span><span class="special">);</span>
+<span class="identifier">foo</span><span class="special">(</span><span class="number">1.0</span><span class="special">,</span> <span class="number">2L</span><span class="special">);</span>
+</pre>
+<p>
+ etc, are all valid calls, as long as "foo" is a function taking
+ two floating-point arguments. But that leaves the question:
+ </p>
+<div class="sidebar">
+<p class="title"><b></b></p>
+<p>
+ <span class="emphasis"><em>"Given a special function with N arguments of types T1, T2,
+ T3 ... TN, then what type is the result?"</em></span>
+ </p>
+</div>
+<p>
+ <span class="bold"><strong>If all the arguments are of the same (floating point)
+ type then the result is the same type as the arguments.</strong></span>
+ </p>
+<p>
+ Otherwise, the type of the result is computed using the following logic:
+ </p>
+<div class="orderedlist"><ol type="1">
+<li>
+ Any arguments that are not template arguments are disregarded from further
+ analysis.
+ </li>
+<li>
+ For each type in the argument list, if that type is an integer type then
+ it is treated as if it were of type double for the purposes of further
+ analysis.
+ </li>
+<li>
+ If any of the arguments is a user-defined class type, then the result type
+ is the first such class type that is constructible from all of the other
+ argument types.
+ </li>
+<li>
+ If any of the arguments is of type <code class="computeroutput"><span class="keyword">long</span>
+ <span class="keyword">double</span></code>, then the result is of type
+ <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>.
+ </li>
+<li>
+ If any of the arguments is of type <code class="computeroutput"><span class="keyword">double</span></code>,
+ then the result is of type <code class="computeroutput"><span class="keyword">double</span></code>.
+ </li>
+<li>
+ Otherwise the result is of type <code class="computeroutput"><span class="keyword">float</span></code>.
+ </li>
+</ol></div>
+<p>
+ For example:
+ </p>
+<pre class="programlisting">
+<span class="identifier">cyl_bessel</span><span class="special">(</span><span class="number">2</span><span class="special">,</span> <span class="number">3.0</span><span class="special">);</span>
+</pre>
+<p>
+ Returns a <code class="computeroutput"><span class="keyword">double</span></code> result, as
+ does:
+ </p>
+<pre class="programlisting">
+<span class="identifier">cyl_bessel</span><span class="special">(</span><span class="number">2</span><span class="special">,</span> <span class="number">3.0f</span><span class="special">);</span>
+</pre>
+<p>
+ as in this case the integer first argument is treated as a <code class="computeroutput"><span class="keyword">double</span></code> and takes precedence over the <code class="computeroutput"><span class="keyword">float</span></code> second argument. To get a <code class="computeroutput"><span class="keyword">float</span></code> result we would need all the arguments
+ to be of type float:
+ </p>
+<pre class="programlisting">
+<span class="identifier">cyl_bessel_j</span><span class="special">(</span><span class="number">2.0f</span><span class="special">,</span> <span class="number">3.0f</span><span class="special">);</span>
+</pre>
+<p>
+ When one or more of the arguments is not a template argument then it doesn't
+ effect the return type at all, for example:
+ </p>
+<pre class="programlisting">
+<span class="identifier">sph_bessel</span><span class="special">(</span><span class="number">2</span><span class="special">,</span> <span class="number">3.0f</span><span class="special">);</span>
+</pre>
+<p>
+ returns a <code class="computeroutput"><span class="keyword">float</span></code>, since the first
+ argument is not a template argument and so doesn't effect the result: without
+ this rule functions that take explicitly integer arguments could never return
+ <code class="computeroutput"><span class="keyword">float</span></code>.
+ </p>
+<p>
+ And for user defined types, all of the following return an NTL::RR result:
+ </p>
+<pre class="programlisting">
+<span class="identifier">cyl_bessel_j</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span><span class="special">(</span><span class="number">2</span><span class="special">));</span>
+
+<span class="identifier">cyl_bessel_j</span><span class="special">(</span><span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span><span class="special">(</span><span class="number">2</span><span class="special">),</span> <span class="number">3</span><span class="special">);</span>
+
+<span class="identifier">cyl_bessel_j</span><span class="special">(</span><span class="identifier">NTL</span><span class="special">::</span><span class="identifier">quad_float</span><span class="special">(</span><span class="number">2</span><span class="special">),</span> <span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span><span class="special">(</span><span class="number">3</span><span class="special">));</span>
+</pre>
+<p>
+ In the last case, quad_float is convertible to RR, but not vice-versa, so
+ the result will be an NTL::RR. Note that this assumes that you are using
+ a patched NTL library.
+ </p>
+<p>
+ These rules are chosen to be compatible with the behaviour of <span class="emphasis"><em>ISO/IEC
+ 9899:1999 Programming languages - C</em></span> and with the <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf" target="_top">Draft
+ Technical Report on C++ Library Extensions, 2005-06-24, section 5.2.1, paragraph
+ 5</a>.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="namespaces.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="error_handling.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/threads.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/main_overview/threads.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,66 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Thread Safety</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../main_overview.html" title="Overview">
+<link rel="prev" href="pol_overview.html" title="Configuration and Policies">
+<link rel="next" href="perf_over.html" title="Performance">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="pol_overview.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="perf_over.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.main_overview.threads"></a> Thread Safety
+</h3></div></div></div>
+<p>
+ The library is fully thread safe and re-entrant provided the function and
+ class templates in the library are instantiated with built-in floating point
+ types: i.e. the types <code class="computeroutput"><span class="keyword">float</span></code>,
+ <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">long</span>
+ <span class="keyword">double</span></code>.
+ </p>
+<p>
+ However, the library <span class="bold"><strong>is not thread safe</strong></span>
+ when used with user-defined (i.e. class type) numeric types.
+ </p>
+<p>
+ The reason for the latter limitation is the need to initialise symbolic constants
+ using constructs such as:
+ </p>
+<pre class="programlisting">
+<span class="keyword">static</span> <span class="keyword">const</span> <span class="identifier">T</span> <span class="identifier">coefficient_array</span> <span class="special">=</span> <span class="special">{</span> <span class="special">...</span> <span class="identifier">list</span> <span class="identifier">of</span> <span class="identifier">values</span> <span class="special">...</span> <span class="special">};</span>
+</pre>
+<p>
+ Which is always thread safe when T is a built-in floating point type, but
+ not when T is a user defined type: as in this case there is a need for T's
+ constructors to be run, leading to potential race conditions.
+ </p>
+<p>
+ This limitation may be addressed in a future release.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="pol_overview.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../main_overview.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="perf_over.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,52 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Performance</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../index.html" title="Math Toolkit">
+<link rel="up" href="../index.html" title="Math Toolkit">
+<link rel="prev" href="policy/pol_ref/pol_ref_ref.html" title="Policy Class Reference">
+<link rel="next" href="perf/perf_over.html" title="Performance Overview">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="policy/pol_ref/pol_ref_ref.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="perf/perf_over.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="math_toolkit.perf"></a> Performance
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"> Performance Overview</span></dt>
+<dt><span class="section"> Interpretting these Results</span></dt>
+<dt><span class="section"><a href="perf/getting_best.html"> Getting the Best Performance
+ from this Library</a></span></dt>
+<dt><span class="section"> Comparing Compilers</span></dt>
+<dt><span class="section"> Performance Tuning Macros</span></dt>
+<dt><span class="section"><a href="perf/comparisons.html"> Comparisons to Other
+ Open Source Libraries</a></span></dt>
+<dt><span class="section"><a href="perf/perf_test_app.html"> The Performance Test
+ Application</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="policy/pol_ref/pol_ref_ref.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="perf/perf_over.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/comp_compilers.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/comp_compilers.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,373 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Comparing Compilers</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../perf.html" title="Performance">
+<link rel="prev" href="getting_best.html" title="Getting the Best Performance from this Library">
+<link rel="next" href="tuning.html" title="Performance Tuning Macros">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="getting_best.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../perf.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="tuning.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.perf.comp_compilers"></a> Comparing Compilers
+</h3></div></div></div>
+<p>
+ After a good choice of build settings the next most important thing you can
+ do, is choose your compiler - and the standard C library it sits on top of
+ - very carefully. GCC-3.x in particular has been found to be particularly
+ bad at inlining code, and performing the kinds of high level transformations
+ that good C++ performance demands (thankfully GCC-4.x is somewhat better
+ in this respect).
+ </p>
+<div class="table">
+<a name="id776819"></a><p class="title"><b>Table 38. Performance Comparison of Various Windows Compilers</b></p>
+<div class="table-contents"><table class="table" summary="Performance Comparison of Various Windows Compilers">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Intel C++ 10.0
+ </p>
+ <p>
+ ( /Ox /Qipo /QxN )
+ </p>
+ </th>
+<th>
+ <p>
+ Microsoft Visual C++ 8.0
+ </p>
+ <p>
+ ( /Ox /arch:SSE2 )
+ </p>
+ </th>
+<th>
+ <p>
+ Cygwin G++ 3.4
+ </p>
+ <p>
+ ( /O3 )
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ erf
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(4.118e-008s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.50</p>
+<p> </p>
+<p>(6.173e-008s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>3.24</p>
+<p> </p>
+<p>(1.336e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ erf_inv
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(4.439e-008s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.42</p>
+<p> </p>
+<p>(6.302e-008s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>7.88</p>
+<p> </p>
+<p>(3.500e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ibeta
+ and ibetac
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.631e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.14</p>
+<p> </p>
+<p>(1.852e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>3.05</p>
+<p> </p>
+<p>(4.975e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ibeta_inv
+ and ibetac_inv
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(6.133e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.19</p>
+<p> </p>
+<p>(7.311e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>2.60</p>
+<p> </p>
+<p>(1.597e-005s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ibeta_inva,
+ ibetac_inva,
+ ibeta_invb
+ and ibetac_invb
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(2.453e-005s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.16</p>
+<p> </p>
+<p>(2.847e-005s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>2.83</p>
+<p> </p>
+<p>(6.947e-005s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ gamma_p
+ and gamma_q
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(6.735e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.41</p>
+<p> </p>
+<p>(9.504e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>2.78</p>
+<p> </p>
+<p>(1.872e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ gamma_p_inv
+ and gamma_q_inv
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(2.637e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.38</p>
+<p> </p>
+<p>(3.631e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>3.31</p>
+<p> </p>
+<p>(8.736e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ gamma_p_inva
+ and gamma_q_inva
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(7.716e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.29</p>
+<p> </p>
+<p>(9.982e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>2.56</p>
+<p> </p>
+<p>(1.974e-005s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break">
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="getting_best.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../perf.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="tuning.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/comparisons.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/comparisons.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,1768 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Comparisons to Other Open Source Libraries</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../perf.html" title="Performance">
+<link rel="prev" href="tuning.html" title="Performance Tuning Macros">
+<link rel="next" href="perf_test_app.html" title="The Performance Test Application">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tuning.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../perf.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="perf_test_app.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.perf.comparisons"></a><a href="comparisons.html" title="Comparisons to Other Open Source Libraries"> Comparisons to Other
+ Open Source Libraries</a>
+</h3></div></div></div>
+<p>
+ We've run our performance tests both for our own code, and against other
+ open source implementations of the same functions. The results are presented
+ below to give you a rough idea of how they all compare.
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ You should exercise extreme caution when interpreting these results, relative
+ performance may vary by platform, the tests use data that gives good code
+ coverage of <span class="emphasis"><em>our</em></span> code, but which may skew the results
+ towards the corner cases. Finally, remember that different libraries make
+ different choices with regard to performance verses numerical stability.
+ </p></td></tr>
+</table></div>
+<a name="math_toolkit.perf.comparisons.comparison_to_gsl_1_9_and_cephes"></a><h5>
+<a name="id779286"></a>
+ <a href="comparisons.html#math_toolkit.perf.comparisons.comparison_to_gsl_1_9_and_cephes">Comparison
+ to GSL-1.9 and Cephes</a>
+ </h5>
+<p>
+ All the results were measured on a 2.8GHz Intel Pentium 4, 2Gb RAM, Windows
+ XP machine, with all the libraries compiled with Microsoft Visual C++ 2005
+ using the <code class="computeroutput"><span class="special">/</span><span class="identifier">Ox</span>
+ <span class="special">/</span><span class="identifier">arch</span><span class="special">:</span><span class="identifier">SSE2</span></code> options.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Boost
+ </p>
+ </th>
+<th>
+ <p>
+ GSL-1.9
+ </p>
+ </th>
+<th>
+ <p>
+ Cephes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ tgamma
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.50</p>
+<p> </p>
+<p>(2.566e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.54</p>
+<p> </p>
+<p>(2.627e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.709e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ lgamma
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.73</p>
+<p> </p>
+<p>(2.688e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>3.61</p>
+<p> </p>
+<p>(5.621e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.556e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ gamma_p
+ and gamma_q
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(9.504e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>2.15</p>
+<p> </p>
+<p>(2.042e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>2.57</p>
+<p> </p>
+<p>(2.439e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ gamma_p_inv
+ and gamma_q_inv
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(3.631e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ N/A
+ </p>
+ </td>
+<td>
+ <p>
+ +INF
+ <sup>[<a name="id779653" href="#ftn.id779653">1</a>]</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ibeta
+ and ibetac
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.852e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.07</p>
+<p> </p>
+<p>(1.974e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.07</p>
+<p> </p>
+<p>(1.974e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ibeta_inv
+ and ibetac_inv
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(7.311e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ N/A
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>2.24</p>
+<p> </p>
+<p>(1.637e-005s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+</tbody>
+<tbody class="footnotes"><tr><td colspan="4"><div class="footnote"><p><sup>[<a name="ftn.id779653" href="#id779653">1</a>] </sup>
+ Cephes gets stuck in an infinite loop while trying to execute
+ our test cases.
+ </p></div></td></tr></tbody>
+</table></div>
+<a name="math_toolkit.perf.comparisons.comparison_to_the_r_statistical_library_on_windows"></a><h5>
+<a name="id779822"></a>
+ <a href="comparisons.html#math_toolkit.perf.comparisons.comparison_to_the_r_statistical_library_on_windows">Comparison
+ to the R Statistical Library on Windows</a>
+ </h5>
+<p>
+ All the results were measured on a 2.8GHz Intel Pentium 4, 2Gb RAM, Windows
+ XP machine, with the test program compiled with Microsoft Visual C++ 2005,
+ and R-2.5.0 compiled in "standalone mode" with MinGW-3.4 (R-2.5.0
+ appears not to be buildable with Visual C++).
+ </p>
+<div class="table">
+<a name="id779850"></a><p class="title"><b>Table 41. A Comparison to the R Statistical Library on Windows
+ XP</b></p>
+<div class="table-contents"><table class="table" summary="A Comparison to the R Statistical Library on Windows
+ XP">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Statistical Function
+ </p>
+ </th>
+<th>
+ <p>
+ Boost
+ </p>
+ </th>
+<th>
+ <p>
+ R
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ Beta Distribution
+ CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.20</p>
+<p> </p>
+<p>(1.916e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.597e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Beta Distribution
+ Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(6.570e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>74.66
+ <sup>[<a name="id779990" href="#ftn.id779990">1</a>]</sup>
+ </p>
+<p> </p>
+<p>(4.905e-004s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/binomial_dist.html" title="Binomial Distribution">Binomial
+ Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(5.276e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>2.45</p>
+<p> </p>
+<p>(1.293e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/binomial_dist.html" title="Binomial Distribution">Binomial
+ Distribution</a> Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(4.013e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.32</p>
+<p> </p>
+<p>(5.280e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/cauchy_dist.html" title="Cauchy-Lorentz Distribution">Cauchy
+ Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.231e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.28</p>
+<p> </p>
+<p>(1.576e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/cauchy_dist.html" title="Cauchy-Lorentz Distribution">Cauchy
+ Distribution</a> Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.498e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.498e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/chi_squared_dist.html" title="Chi Squared Distribution">Chi
+ Squared Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(7.889e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>2.48</p>
+<p> </p>
+<p>(1.955e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/chi_squared_dist.html" title="Chi Squared Distribution">Chi
+ Squared Distribution</a> Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(4.303e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.61</p>
+<p> </p>
+<p>(6.925e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/exp_dist.html" title="Exponential Distribution">Exponential
+ Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.955e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.97</p>
+<p> </p>
+<p>(3.844e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/exp_dist.html" title="Exponential Distribution">Exponential
+ Distribution</a> Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.07</p>
+<p> </p>
+<p>(1.206e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.126e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Fisher F Distribution
+ CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.309e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>2.12</p>
+<p> </p>
+<p>(2.780e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Fisher F Distribution
+ Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(7.204e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.78</p>
+<p> </p>
+<p>(1.280e-005s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Gamma Distribution
+ CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.076e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>2.07</p>
+<p> </p>
+<p>(2.227e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Gamma Distribution
+ Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(5.189e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.14</p>
+<p> </p>
+<p>(5.937e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/lognormal_dist.html" title="Log Normal Distribution">Log-normal
+ Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(2.078e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.41</p>
+<p> </p>
+<p>(2.930e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/lognormal_dist.html" title="Log Normal Distribution">Log-normal
+ Distribution</a> Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(6.692e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.63</p>
+<p> </p>
+<p>(1.090e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
+ Binomial Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(9.005e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>2.42</p>
+<p> </p>
+<p>(2.178e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
+ Binomial Distribution</a> Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(9.601e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>53.59
+ <sup>[<a name="id780839" href="#ftn.id780839">2</a>]</sup>
+ </p>
+<p> </p>
+<p>(5.145e-004s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/normal_dist.html" title="Normal (Gaussian) Distribution">Normal
+ Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(5.926e-008s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>3.01</p>
+<p> </p>
+<p>(1.785e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/normal_dist.html" title="Normal (Gaussian) Distribution">Normal
+ Distribution</a> Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.248e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.05</p>
+<p> </p>
+<p>(1.311e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/poisson_dist.html" title="Poisson Distribution">Poisson
+ Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(8.999e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>2.42</p>
+<p> </p>
+<p>(2.175e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/poisson_dist.html" title="Poisson Distribution">Poisson
+ Distribution</a>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.853e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>2.17</p>
+<p> </p>
+<p>(4.014e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/students_t_dist.html" title="Students t Distribution">Students
+ t Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.223e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.13</p>
+<p> </p>
+<p>(1.376e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/students_t_dist.html" title="Students t Distribution">Students
+ t Distribution</a> Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(2.570e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.04</p>
+<p> </p>
+<p>(2.668e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Weibull Distribution
+ CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(4.741e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.46</p>
+<p> </p>
+<p>(6.943e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Weibull Distribution
+ Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(7.926e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.08</p>
+<p> </p>
+<p>(8.542e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+</tbody>
+<tbody class="footnotes"><tr><td colspan="3">
+<div class="footnote"><p><sup>[<a name="ftn.id779990" href="#id779990">1</a>] </sup>
+ 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.
+ </p></div>
+<div class="footnote"><p><sup>[<a name="ftn.id780839" href="#id780839">2</a>] </sup>
+ 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
+ </p></div>
+</td></tr></tbody>
+</table></div>
+</div>
+<br class="table-break"><a name="math_toolkit.perf.comparisons.comparison_to_the_r_statistical_library_on_linux"></a><h5>
+<a name="id781289"></a>
+ <a href="comparisons.html#math_toolkit.perf.comparisons.comparison_to_the_r_statistical_library_on_linux">Comparison
+ to the R Statistical Library on Linux</a>
+ </h5>
+<p>
+ All the results were measured on a 2.8GHz Intel Pentium 4, 2Gb RAM, Mandriva
+ Linux machine, with the test program and R-2.5.0 compiled with GNU G++ 4.2.0.
+ </p>
+<div class="table">
+<a name="id781314"></a><p class="title"><b>Table 42. A Comparison to the R Statistical Library on Linux</b></p>
+<div class="table-contents"><table class="table" summary="A Comparison to the R Statistical Library on Linux">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Statistical Function
+ </p>
+ </th>
+<th>
+ <p>
+ Boost
+ </p>
+ </th>
+<th>
+ <p>
+ R
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ Beta Distribution
+ CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.71</p>
+<p> </p>
+<p>(3.508e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(2.050e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Beta Distribution
+ Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.294e-005s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>44.06
+ <sup>[<a name="id781453" href="#ftn.id781453">1</a>]</sup>
+ </p>
+<p> </p>
+<p>(5.701e-004s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/binomial_dist.html" title="Binomial Distribution">Binomial
+ Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.22</p>
+<p> </p>
+<p>(1.342e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.104e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/binomial_dist.html" title="Binomial Distribution">Binomial
+ Distribution</a> Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.36</p>
+<p> </p>
+<p>(7.083e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(5.194e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/cauchy_dist.html" title="Cauchy-Lorentz Distribution">Cauchy
+ Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.372e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.47</p>
+<p> </p>
+<p>(2.017e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/cauchy_dist.html" title="Cauchy-Lorentz Distribution">Cauchy
+ Distribution</a> Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.542e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.14</p>
+<p> </p>
+<p>(1.752e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/chi_squared_dist.html" title="Chi Squared Distribution">Chi
+ Squared Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.04</p>
+<p> </p>
+<p>(1.820e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.753e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/chi_squared_dist.html" title="Chi Squared Distribution">Chi
+ Squared Distribution</a> Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.39</p>
+<p> </p>
+<p>(9.345e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(6.728e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/exp_dist.html" title="Exponential Distribution">Exponential
+ Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(2.195e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.17</p>
+<p> </p>
+<p>(2.561e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/exp_dist.html" title="Exponential Distribution">Exponential
+ Distribution</a> Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.123e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.03</p>
+<p> </p>
+<p>(1.155e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Fisher F Distribution
+ CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(2.744e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.08</p>
+<p> </p>
+<p>(2.970e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Fisher F Distribution
+ Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.14</p>
+<p> </p>
+<p>(1.550e-005s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.359e-005s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Gamma Distribution
+ CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.29</p>
+<p> </p>
+<p>(2.578e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.992e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Gamma Distribution
+ Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.77</p>
+<p> </p>
+<p>(1.020e-005s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(5.757e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/lognormal_dist.html" title="Log Normal Distribution">Log-normal
+ Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.782e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>2.00</p>
+<p> </p>
+<p>(3.564e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/lognormal_dist.html" title="Log Normal Distribution">Log-normal
+ Distribution</a> Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(7.093e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.07</p>
+<p> </p>
+<p>(7.607e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
+ Binomial Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.03</p>
+<p> </p>
+<p>(2.209e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(2.141e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
+ Binomial Distribution</a> Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.826e-005s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>30.07
+ <sup>[<a name="id782298" href="#ftn.id782298">2</a>]</sup>
+ </p>
+<p> </p>
+<p>(5.490e-004s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/normal_dist.html" title="Normal (Gaussian) Distribution">Normal
+ Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(8.542e-008s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>2.09</p>
+<p> </p>
+<p>(1.782e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/normal_dist.html" title="Normal (Gaussian) Distribution">Normal
+ Distribution</a> Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.362e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.26</p>
+<p> </p>
+<p>(1.722e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/poisson_dist.html" title="Poisson Distribution">Poisson
+ Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.10</p>
+<p> </p>
+<p>(1.953e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.775e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/poisson_dist.html" title="Poisson Distribution">Poisson
+ Distribution</a>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.12</p>
+<p> </p>
+<p>(4.214e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(3.752e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/students_t_dist.html" title="Students t Distribution">Students
+ t Distribution</a> CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.55</p>
+<p> </p>
+<p>(2.441e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.576e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <a href="../dist/dist_ref/dists/students_t_dist.html" title="Students t Distribution">Students
+ t Distribution</a> Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.33</p>
+<p> </p>
+<p>(3.972e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(2.990e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Weibull Distribution
+ CDF
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(6.640e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.06</p>
+<p> </p>
+<p>(7.031e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Weibull Distribution
+ Quantile
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(7.504e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.03</p>
+<p> </p>
+<p>(7.710e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+</tbody>
+<tbody class="footnotes"><tr><td colspan="3">
+<div class="footnote"><p><sup>[<a name="ftn.id781453" href="#id781453">1</a>] </sup>
+ 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.
+ </p></div>
+<div class="footnote"><p><sup>[<a name="ftn.id782298" href="#id782298">2</a>] </sup>
+ 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
+ </p></div>
+</td></tr></tbody>
+</table></div>
+</div>
+<br class="table-break">
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tuning.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../perf.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="perf_test_app.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/getting_best.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/getting_best.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,290 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Getting the Best Performance from this Library</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../perf.html" title="Performance">
+<link rel="prev" href="interp.html" title="Interpretting these Results">
+<link rel="next" href="comp_compilers.html" title="Comparing Compilers">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="interp.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../perf.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="comp_compilers.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.perf.getting_best"></a><a href="getting_best.html" title="Getting the Best Performance from this Library"> Getting the Best Performance
+ from this Library</a>
+</h3></div></div></div>
+<p>
+ 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.
+ </p>
+<div class="table">
+<a name="id776256"></a><p class="title"><b>Table 37. Performance Comparison of Release and Debug Settings</b></p>
+<div class="table-contents"><table class="table" summary="Performance Comparison of Release and Debug Settings">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ Microsoft Visual C++ 8.0
+ </p>
+ <p>
+ Debug Settings: /Od /ZI
+ </p>
+ </th>
+<th>
+ <p>
+ Microsoft Visual C++ 8.0
+ </p>
+ <p>
+ Release settings: /Ox /arch:SSE2
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ erf
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>16.65</p>
+<p> </p>
+<p>(1.028e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(6.173e-008s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ erf_inv
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>19.28</p>
+<p> </p>
+<p>(1.215e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(6.302e-008s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ibeta
+ and ibetac
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>8.32</p>
+<p> </p>
+<p>(1.540e-005s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.852e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ibeta_inv
+ and ibetac_inv
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>10.25</p>
+<p> </p>
+<p>(7.492e-005s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(7.311e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ibeta_inva,
+ ibetac_inva,
+ ibeta_invb
+ and ibetac_invb
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>8.57</p>
+<p> </p>
+<p>(2.441e-004s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(2.847e-005s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ gamma_p
+ and gamma_q
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>10.98</p>
+<p> </p>
+<p>(1.044e-005s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(9.504e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ gamma_p_inv
+ and gamma_q_inv
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>10.25</p>
+<p> </p>
+<p>(3.721e-005s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(3.631e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ gamma_p_inva
+ and gamma_q_inva
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>11.26</p>
+<p> </p>
+<p>(1.124e-004s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(9.982e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break">
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="interp.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../perf.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="comp_compilers.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/interp.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/interp.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,66 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Interpretting these Results</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../perf.html" title="Performance">
+<link rel="prev" href="perf_over.html" title="Performance Overview">
+<link rel="next" href="getting_best.html" title="Getting the Best Performance from this Library">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="perf_over.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../perf.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="getting_best.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.perf.interp"></a> Interpretting these Results
+</h3></div></div></div>
+<p>
+ 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 <span class="emphasis"><em>"twice as slow as the best performing
+ result".</em></span> Actual timings in seconds per function call are
+ also shown in parenthesis.
+ </p>
+<p>
+ Result were obtained on a system with an Intel 2.8GHz Pentium 4 processor
+ with 2Gb of RAM and running either Windows XP or Mandriva Linux.
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ 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!
+ </p></td></tr>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="perf_over.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../perf.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="getting_best.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/perf_over.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/perf_over.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,89 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Performance Overview</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../perf.html" title="Performance">
+<link rel="prev" href="../perf.html" title="Performance">
+<link rel="next" href="interp.html" title="Interpretting these Results">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../perf.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../perf.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="interp.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.perf.perf_over"></a> Performance Overview
+</h3></div></div></div>
+<p>
+ </p>
+<p>
+ 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 <span class="emphasis"><em>not</em></span> speed.
+ </p>
+<p>
+ </p>
+<p>
+ 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.
+ </p>
+<p>
+ </p>
+<p>
+ The two most important things you can do to ensure the best performance
+ from this library are:
+ </p>
+<p>
+ </p>
+<div class="orderedlist"><ol type="1">
+<li>
+ Turn on your compilers optimisations: the difference between "release"
+ and "debug" builds can easily be a <a href="getting_best.html" title="Getting the Best Performance from this Library">factor
+ of 20</a>.
+ </li>
+<li>
+ Pick your compiler carefully: <a href="comp_compilers.html" title="Comparing Compilers">performance
+ differences of up to 8 fold</a> have been found between some windows
+ compilers for example.
+ </li>
+</ol></div>
+<p>
+ </p>
+<p>
+ The 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.
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../perf.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../perf.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="interp.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/perf_test_app.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/perf_test_app.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,59 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>The Performance Test Application</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../perf.html" title="Performance">
+<link rel="prev" href="comparisons.html" title="Comparisons to Other Open Source Libraries">
+<link rel="next" href="../backgrounders.html" title="Backgrounders">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="comparisons.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../perf.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../backgrounders.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.perf.perf_test_app"></a><a href="perf_test_app.html" title="The Performance Test Application"> The Performance Test
+ Application</a>
+</h3></div></div></div>
+<p>
+ Under <span class="emphasis"><em>boost-path</em></span>/libs/math/performance you will find
+ a (fairly rudimentary) performance test application for this library.
+ </p>
+<p>
+ To run this application yourself, build the all the .cpp files in <span class="emphasis"><em>boost-path</em></span>/libs/math/performance
+ into an application using your usual release-build settings. Run the application
+ with --help to see a full list of options, or with --all to test everything
+ (which takes quite a while), or with --tune to test the <a href="tuning.html" title="Performance Tuning Macros">available
+ performance tuning options</a>.
+ </p>
+<p>
+ If you want to use this application to test the effect of changing any of
+ the Policies, then you will need
+ to build and run it twice: once with the default Policies,
+ and then a second time with the Policies
+ you want to test set as the default.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="comparisons.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../perf.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../backgrounders.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/tuning.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/perf/tuning.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,893 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Performance Tuning Macros</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../perf.html" title="Performance">
+<link rel="prev" href="comp_compilers.html" title="Comparing Compilers">
+<link rel="next" href="comparisons.html" title="Comparisons to Other Open Source Libraries">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="comp_compilers.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../perf.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="comparisons.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.perf.tuning"></a> Performance Tuning Macros
+</h3></div></div></div>
+<p>
+ There are a small number of performance tuning options that are determined
+ by configuration macros. These should be set in boost/math/tools/user.hpp;
+ or else reported to the Boost-development mailing list so that the appropriate
+ option for a given compiler and OS platform can be set automatically in our
+ configuration setup.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Macro
+ </p>
+ </th>
+<th>
+ <p>
+ Meaning
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ BOOST_MATH_POLY_METHOD
+ </p>
+ </td>
+<td>
+ <p>
+ Determines how polynomials and most rational functions are evaluated.
+ Define to one of the values 0, 1, 2 or 3: see below for the meaning
+ of these values.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ BOOST_MATH_RATIONAL_METHOD
+ </p>
+ </td>
+<td>
+ <p>
+ Determines how symmetrical rational functions are evaluated: mostly
+ this only effects how the Lanczos approximation is evaluated, and
+ how the <code class="computeroutput"><span class="identifier">evaluate_rational</span></code>
+ function behaves. Define to one of the values 0, 1, 2 or 3: see below
+ for the meaning of these values.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ BOOST_MATH_MAX_POLY_ORDER
+ </p>
+ </td>
+<td>
+ <p>
+ The maximum order of polynomial or rational function that will be
+ evaluated by a method other than 0 (a simple "for" loop).
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ BOOST_MATH_INT_TABLE_TYPE(RT, IT)
+ </p>
+ </td>
+<td>
+ <p>
+ Many of the coefficients to the polynomials and rational functions
+ used by this library are integers. Normally these are stored as tables
+ as integers, but if mixed integer / floating point arithmetic is
+ much slower than regular floating point arithmetic then they can
+ be stored as tables of floating point values instead. If mixed arithmetic
+ is slow then add:
+ </p>
+ <p>
+ #define BOOST_MATH_INT_TABLE_TYPE(RT, IT) RT
+ </p>
+ <p>
+ to boost/math/tools/user.hpp, otherwise the default of:
+ </p>
+ <p>
+ #define BOOST_MATH_INT_TABLE_TYPE(RT, IT) IT
+ </p>
+ <p>
+ Set in boost/math/config.hpp is fine, and may well result in smaller
+ code.
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<p>
+ The values to which <code class="computeroutput"><span class="identifier">BOOST_MATH_POLY_METHOD</span></code>
+ and <code class="computeroutput"><span class="identifier">BOOST_MATH_RATIONAL_METHOD</span></code>
+ may be set are as follows:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Value
+ </p>
+ </th>
+<th>
+ <p>
+ Effect
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 0
+ </p>
+ </td>
+<td>
+ <p>
+ The polynomial or rational function is evaluated using Horner's method,
+ and a simple for-loop.
+ </p>
+ <p>
+ Note that if the order of the polynomial or rational function is
+ a runtime parameter, or the order is greater than the value of <code class="computeroutput"><span class="identifier">BOOST_MATH_MAX_POLY_ORDER</span></code>, then
+ this method is always used, irrespective of the value of <code class="computeroutput"><span class="identifier">BOOST_MATH_POLY_METHOD</span></code> or <code class="computeroutput"><span class="identifier">BOOST_MATH_RATIONAL_METHOD</span></code>.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 1
+ </p>
+ </td>
+<td>
+ <p>
+ The polynomial or rational function is evaluated without the use
+ of a loop, and using Horner's method. This only occurs if the order
+ of the polynomial is known at compile time and is less than or equal
+ to <code class="computeroutput"><span class="identifier">BOOST_MATH_MAX_POLY_ORDER</span></code>.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 2
+ </p>
+ </td>
+<td>
+ <p>
+ The polynomial or rational function is evaluated without the use
+ of a loop, and using a second order Horner's method. In theory this
+ permits two operations to occur in parallel for polynomials, and
+ four in parallel for rational functions. This only occurs if the
+ order of the polynomial is known at compile time and is less than
+ or equal to <code class="computeroutput"><span class="identifier">BOOST_MATH_MAX_POLY_ORDER</span></code>.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 3
+ </p>
+ </td>
+<td>
+ <p>
+ The polynomial or rational function is evaluated without the use
+ of a loop, and using a second order Horner's method. In theory this
+ permits two operations to occur in parallel for polynomials, and
+ four in parallel for rational functions. This differs from method
+ "2" in that the code is carefully ordered to make the parallelisation
+ more obvious to the compiler: rather than relying on the compiler's
+ optimiser to spot the parallelisation opportunities. This only occurs
+ if the order of the polynomial is known at compile time and is less
+ than or equal to <code class="computeroutput"><span class="identifier">BOOST_MATH_MAX_POLY_ORDER</span></code>.
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<p>
+ To determine which of these options is best for your particular compiler/platform
+ build the performance test application with your usual release settings,
+ and run the program with the --tune command line option.
+ </p>
+<p>
+ In practice the difference between methods is rather small at present, as
+ the following table shows. However, parallelisation /vectorisation is likely
+ to become more important in the future: quite likely the methods currently
+ supported will need to be supplemented or replaced by ones more suited to
+ highly vectorisable processors in the future.
+ </p>
+<div class="table">
+<a name="id777935"></a><p class="title"><b>Table 39. A Comparison of Polynomial Evaluation Methods</b></p>
+<div class="table-contents"><table class="table" summary="A Comparison of Polynomial Evaluation Methods">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Compiler/platform
+ </p>
+ </th>
+<th>
+ <p>
+ Method 0
+ </p>
+ </th>
+<th>
+ <p>
+ Method 1
+ </p>
+ </th>
+<th>
+ <p>
+ Method 2
+ </p>
+ </th>
+<th>
+ <p>
+ Method 3
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ Microsoft C++ 8.0, Polynomial evaluation
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.34</p>
+<p> </p>
+<p>(1.161e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.13</p>
+<p> </p>
+<p>(9.777e-008s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.07</p>
+<p> </p>
+<p>(9.289e-008s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(8.678e-008s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Microsoft C++ 8.0, Rational evaluation
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.443e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.03</p>
+<p> </p>
+<p>(1.492e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.20</p>
+<p> </p>
+<p>(1.736e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.07</p>
+<p> </p>
+<p>(1.540e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Intel C++ 10.0 (Windows), Polynomial evaluation
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.03</p>
+<p> </p>
+<p>(7.702e-008s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.03</p>
+<p> </p>
+<p>(7.702e-008s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(7.446e-008s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.03</p>
+<p> </p>
+<p>(7.690e-008s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Intel C++ 10.0 (Windows), Rational evaluation
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.245e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.245e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.18</p>
+<p> </p>
+<p>(1.465e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.06</p>
+<p> </p>
+<p>(1.318e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ GNU G++ 4.2 (Linux), Polynomial evaluation
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.61</p>
+<p> </p>
+<p>(1.220e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.68</p>
+<p> </p>
+<p>(1.269e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.23</p>
+<p> </p>
+<p>(9.275e-008s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(7.566e-008s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ GNU G++ 4.2 (Linux), Rational evaluation
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.26</p>
+<p> </p>
+<p>(1.660e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.33</p>
+<p> </p>
+<p>(1.758e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.318e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.15</p>
+<p> </p>
+<p>(1.513e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Intel C++ 10.0 (Linux), Polynomial evaluation
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.15</p>
+<p> </p>
+<p>(9.154e-008s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.15</p>
+<p> </p>
+<p>(9.154e-008s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(7.934e-008s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(7.934e-008s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Intel C++ 10.0 (Linux), Rational evaluation
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.245e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.245e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.35</p>
+<p> </p>
+<p>(1.684e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.04</p>
+<p> </p>
+<p>(1.294e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><p>
+ There is one final performance tuning option that is available as a compile
+ time policy. Normally when evaluating
+ functions at <code class="computeroutput"><span class="keyword">double</span></code> precision,
+ these are actually evaluated at <code class="computeroutput"><span class="keyword">long</span>
+ <span class="keyword">double</span></code> precision internally: this
+ helps to ensure that as close to full <code class="computeroutput"><span class="keyword">double</span></code>
+ precision as possible is achieved, but may slow down execution in some environments.
+ The defaults for this policy can be changed by <a href="../policy/pol_ref/policy_defaults.html" title="Using macros to Change the Policy Defaults">defining
+ the macro <code class="computeroutput"><span class="identifier">BOOST_MATH_PROMOTE_DOUBLE_POLICY</span></code></a>
+ to <code class="computeroutput"><span class="keyword">false</span></code>, or <a href="../policy/pol_ref/internal_promotion.html" title="Internal Promotion Policies">by
+ specifying a specific policy</a> when calling the special functions or
+ distributions. See also the <a href="../policy/pol_tutorial.html" title="Policy Tutorial">policy
+ tutorial</a>.
+ </p>
+<div class="table">
+<a name="id778690"></a><p class="title"><b>Table 40. Performance Comparison with and Without Internal
+ Promotion to long double</b></p>
+<div class="table-contents"><table class="table" summary="Performance Comparison with and Without Internal
+ Promotion to long double">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Function
+ </p>
+ </th>
+<th>
+ <p>
+ GCC 4.2 , Linux
+ </p>
+ <p>
+ (with internal promotion of double to long double).
+ </p>
+ </th>
+<th>
+ <p>
+ GCC 4.2, Linux
+ </p>
+ <p>
+ (without promotion of double).
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ erf
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.48</p>
+<p> </p>
+<p>(1.387e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(9.377e-008s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ erf_inv
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.11</p>
+<p> </p>
+<p>(4.009e-007s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(3.598e-007s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ibeta
+ and ibetac
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.29</p>
+<p> </p>
+<p>(5.354e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(4.137e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ibeta_inv
+ and ibetac_inv
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.44</p>
+<p> </p>
+<p>(2.220e-005s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(1.538e-005s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ ibeta_inva,
+ ibetac_inva,
+ ibeta_invb
+ and ibetac_invb
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.25</p>
+<p> </p>
+<p>(7.009e-005s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(5.607e-005s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ gamma_p
+ and gamma_q
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.26</p>
+<p> </p>
+<p>(3.116e-006s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(2.464e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ gamma_p_inv
+ and gamma_q_inv
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.27</p>
+<p> </p>
+<p>(1.178e-005s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(9.291e-006s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ gamma_p_inva
+ and gamma_q_inva
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p>1.20</p>
+<p> </p>
+<p>(2.765e-005s)</p>
+<p>
+ </p>
+ </td>
+<td>
+ <p>
+ </p>
+<p><span class="bold"><strong>1.00</strong></span></p>
+<p> </p>
+<p>(2.311e-005s)</p>
+<p>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break">
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="comp_compilers.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../perf.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="comparisons.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,87 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Policies</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../index.html" title="Math Toolkit">
+<link rel="up" href="../index.html" title="Math Toolkit">
+<link rel="prev" href="using_udt/archetypes.html" title="Conceptual Archetypes and Testing">
+<link rel="next" href="policy/pol_overview.html" title="Policy Overview">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="using_udt/archetypes.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="policy/pol_overview.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="math_toolkit.policy"></a> Policies
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"> Policy Overview</span></dt>
+<dt><span class="section"> Policy Tutorial</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="policy/pol_tutorial/what_is_a_policy.html">
+ So Just What is a Policy Anyway?</a></span></dt>
+<dt><span class="section"><a href="policy/pol_tutorial/policy_tut_defaults.html">
+ Policies Have Sensible Defaults</a></span></dt>
+<dt><span class="section"><a href="policy/pol_tutorial/policy_usage.html"> So
+ How are Policies Used Anyway?</a></span></dt>
+<dt><span class="section"><a href="policy/pol_tutorial/changing_policy_defaults.html">
+ Changing the Policy Defaults</a></span></dt>
+<dt><span class="section"><a href="policy/pol_tutorial/ad_hoc_dist_policies.html">
+ Setting Policies for Distributions on an Ad Hoc Basis</a></span></dt>
+<dt><span class="section"><a href="policy/pol_tutorial/ad_hoc_sf_policies.html">
+ Changing the Policy on an Ad Hoc Basis for the Special Functions</a></span></dt>
+<dt><span class="section"><a href="policy/pol_tutorial/namespace_policies.html">
+ Setting Policies at Namespace or Translation Unit Scope</a></span></dt>
+<dt><span class="section"><a href="policy/pol_tutorial/user_def_err_pol.html">
+ Calling User Defined Error Handlers</a></span></dt>
+<dt><span class="section"><a href="policy/pol_tutorial/understand_dis_quant.html">
+ Understanding Quantiles of Discrete Distributions</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Policy Reference</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="policy/pol_ref/error_handling_policies.html">
+ Error Handling Policies</a></span></dt>
+<dt><span class="section"><a href="policy/pol_ref/internal_promotion.html"> Internal
+ Promotion Policies</a></span></dt>
+<dt><span class="section"><a href="policy/pol_ref/assert_undefined.html"> Mathematically
+ Undefined Function Policies</a></span></dt>
+<dt><span class="section"><a href="policy/pol_ref/discrete_quant_ref.html"> Discrete
+ Quantile Policies</a></span></dt>
+<dt><span class="section"><a href="policy/pol_ref/precision_pol.html"> Precision
+ Policies</a></span></dt>
+<dt><span class="section"><a href="policy/pol_ref/iteration_pol.html"> Iteration
+ Limits Policies</a></span></dt>
+<dt><span class="section"><a href="policy/pol_ref/policy_defaults.html"> Using
+ macros to Change the Policy Defaults</a></span></dt>
+<dt><span class="section"><a href="policy/pol_ref/namespace_pol.html"> Setting
+ Polices at Namespace Scope</a></span></dt>
+<dt><span class="section"><a href="policy/pol_ref/pol_ref_ref.html"> Policy Class
+ Reference</a></span></dt>
+</dl></dd>
+</dl></div>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="using_udt/archetypes.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="policy/pol_overview.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_overview.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_overview.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,131 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Policy Overview</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../policy.html" title="Policies">
+<link rel="prev" href="../policy.html" title="Policies">
+<link rel="next" href="pol_tutorial.html" title="Policy Tutorial">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../policy.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../policy.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="pol_tutorial.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.policy.pol_overview"></a> Policy Overview
+</h3></div></div></div>
+<p>
+ </p>
+<p>
+ 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 <a href="pol_tutorial.html" title="Policy Tutorial">policy
+ tutorial</a> and the <a href="pol_ref.html" title="Policy Reference">policy
+ reference</a>.
+ </p>
+<p>
+ </p>
+<p>
+ Generally speaking unless you find that the <a href="pol_tutorial/policy_tut_defaults.html" title="Policies Have Sensible Defaults">default
+ policy behaviour</a> when encountering 'bad' argument values does not
+ meet your needs, you should not need to worry about policies.
+ </p>
+<p>
+ </p>
+<p>
+ Policies are a compile-time mechanism that allow you to change error-handling
+ or calculation precision either program wide, or at the call site.
+ </p>
+<p>
+ </p>
+<p>
+ Although the policy mechanism itself is rather complicated, in practice
+ it is easy to use, and very flexible.
+ </p>
+<p>
+ </p>
+<p>
+ Using policies you can control:
+ </p>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+<a href="pol_ref/error_handling_policies.html" title="Error Handling Policies">How
+ results from 'bad' arguments are handled</a>, including those that
+ cannot be fully evaluated.
+ </li>
+<li>
+ How <a href="pol_ref/internal_promotion.html" title="Internal Promotion Policies">accuracy
+ is controlled by internal promotion</a> to use more precise types.
+ </li>
+<li>
+ What working precision
+ should be used to calculate results.
+ </li>
+<li>
+ What to do when a <a href="pol_ref/assert_undefined.html" title="Mathematically Undefined Function Policies">mathematically
+ undefined function</a> is used: Should this raise a run-time or compile-time
+ error?
+ </li>
+<li>
+ Whether <a href="pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">discrete
+ functions</a>, like the binomial, should return real or only integral
+ values, and how they are rounded.
+ </li>
+<li>
+ 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.
+ </li>
+</ul></div>
+<p>
+ </p>
+<p>
+ You can control policies:
+ </p>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Using macros
+ to change any default policy: the is the prefered method for installation
+ wide policies.
+ </li>
+<li>
+ At your chosen <a href="pol_ref/namespace_pol.html" title="Setting Polices at Namespace Scope">namespace
+ scope</a> for distributions and/or functions: this is the prefered
+ method for project, namespace, or translation unit scope policies.
+ </li>
+<li>
+ In an ad-hoc manner <a href="pol_tutorial/ad_hoc_sf_policies.html" title="Changing the Policy on an Ad Hoc Basis for the Special Functions">by
+ passing a specific policy to a special function</a>, or to a <a href="pol_tutorial/ad_hoc_dist_policies.html" title="Setting Policies for Distributions on an Ad Hoc Basis">statistical
+ distribution</a>.
+ </li>
+</ul></div>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../policy.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../policy.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="pol_tutorial.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,60 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Policy Reference</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../policy.html" title="Policies">
+<link rel="prev" href="pol_tutorial/understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">
+<link rel="next" href="pol_ref/error_handling_policies.html" title="Error Handling Policies">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="pol_tutorial/understand_dis_quant.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../policy.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="pol_ref/error_handling_policies.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.policy.pol_ref"></a> Policy Reference
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="pol_ref/error_handling_policies.html">
+ Error Handling Policies</a></span></dt>
+<dt><span class="section"><a href="pol_ref/internal_promotion.html"> Internal
+ Promotion Policies</a></span></dt>
+<dt><span class="section"><a href="pol_ref/assert_undefined.html"> Mathematically
+ Undefined Function Policies</a></span></dt>
+<dt><span class="section"><a href="pol_ref/discrete_quant_ref.html"> Discrete
+ Quantile Policies</a></span></dt>
+<dt><span class="section"><a href="pol_ref/precision_pol.html"> Precision
+ Policies</a></span></dt>
+<dt><span class="section"><a href="pol_ref/iteration_pol.html"> Iteration
+ Limits Policies</a></span></dt>
+<dt><span class="section"><a href="pol_ref/policy_defaults.html"> Using
+ macros to Change the Policy Defaults</a></span></dt>
+<dt><span class="section"><a href="pol_ref/namespace_pol.html"> Setting
+ Polices at Namespace Scope</a></span></dt>
+<dt><span class="section"><a href="pol_ref/pol_ref_ref.html"> Policy Class
+ Reference</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="pol_tutorial/understand_dis_quant.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../policy.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="pol_ref/error_handling_policies.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/assert_undefined.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/assert_undefined.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,88 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Mathematically Undefined Function Policies</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_ref.html" title="Policy Reference">
+<link rel="prev" href="internal_promotion.html" title="Internal Promotion Policies">
+<link rel="next" href="discrete_quant_ref.html" title="Discrete Quantile Policies">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="internal_promotion.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="discrete_quant_ref.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_ref.assert_undefined"></a><a href="assert_undefined.html" title="Mathematically Undefined Function Policies"> Mathematically
+ Undefined Function Policies</a>
+</h4></div></div></div>
+<p>
+ There are some functions that are generic (they are present for all the
+ statistical distributions supported) but which may be mathematically undefined
+ for certain distributions, but defined for others.
+ </p>
+<p>
+ For example, the Cauchy distribution does not have a mean, so what should
+ </p>
+<pre class="programlisting">
+<span class="identifier">mean</span><span class="special">(</span><span class="identifier">cauchy</span><span class="special">&lt;&gt;());</span>
+</pre>
+<p>
+ return, and should such an expression even compile at all?
+ </p>
+<p>
+ The default behaviour is for all such functions to not compile at all -
+ in fact they will raise a <a href="http://www.boost.org/libs/static_assert/index.html" target="_top">static
+ assertion</a> - but by changing the policy we can have them return
+ the result of a domain error instead (which may well throw an exception,
+ depending on the error handling policy).
+ </p>
+<p>
+ This behaviour is controlled by the <code class="computeroutput"><span class="identifier">assert_undefined</span><span class="special">&lt;&gt;</span></code> policy:
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">policies</span> <span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">bool</span> <span class="identifier">b</span><span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">assert_undefined</span><span class="special">;</span>
+
+<span class="special">}}}</span> <span class="comment">//namespaces
+</span></pre>
+<p>
+ For example:
+ </p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">cauchy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+
+<span class="comment">// This will not compile, cauchy has no mean!
+</span><span class="keyword">double</span> <span class="identifier">m1</span> <span class="special">=</span> <span class="identifier">mean</span><span class="special">(</span><span class="identifier">cauchy</span><span class="special">());</span>
+
+<span class="comment">// This will compile, but raises a domain error!
+</span><span class="keyword">double</span> <span class="identifier">m2</span> <span class="special">=</span> <span class="identifier">mean</span><span class="special">(</span><span class="identifier">cauchy_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">assert_undefined</span><span class="special">&lt;</span><span class="keyword">false</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="special">&gt;());</span>
+</pre>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="internal_promotion.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="discrete_quant_ref.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/discrete_quant_ref.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/discrete_quant_ref.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,321 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Discrete Quantile Policies</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_ref.html" title="Policy Reference">
+<link rel="prev" href="assert_undefined.html" title="Mathematically Undefined Function Policies">
+<link rel="next" href="precision_pol.html" title="Precision Policies">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="assert_undefined.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="precision_pol.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_ref.discrete_quant_ref"></a><a href="discrete_quant_ref.html" title="Discrete Quantile Policies"> Discrete
+ Quantile Policies</a>
+</h4></div></div></div>
+<p>
+ If a statistical distribution is <span class="emphasis"><em>discrete</em></span> then the
+ random variable can only have integer values - this leaves us with a problem
+ when calculating quantiles - we can either ignore the discreteness of the
+ distribution and return a real value, or we can round to an integer. As
+ it happens, computing integer values can be substantially faster than calculating
+ a real value, so there are definite advantages to returning an integer,
+ but we do then need to decide how best to round the result. The <code class="computeroutput"><span class="identifier">discrete_quantile</span></code> policy defines how
+ discrete quantiles work, and how integer results are rounded:
+ </p>
+<pre class="programlisting">
+<span class="keyword">enum</span> <span class="identifier">discrete_quantile_policy_type</span>
+<span class="special">{</span>
+ <span class="identifier">real</span><span class="special">,</span>
+ <span class="identifier">integer_round_outwards</span><span class="special">,</span> <span class="comment">// default
+</span> <span class="identifier">integer_round_inwards</span><span class="special">,</span>
+ <span class="identifier">integer_round_down</span><span class="special">,</span>
+ <span class="identifier">integer_round_up</span><span class="special">,</span>
+ <span class="identifier">integer_round_nearest</span>
+<span class="special">};</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">discrete_quantile_policy_type</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">discrete_quantile</span><span class="special">;</span>
+</pre>
+<p>
+ The values that <code class="computeroutput"><span class="identifier">discrete_quantile</span></code>
+ can take have the following meanings:
+ </p>
+<a name="math_toolkit.policy.pol_ref.discrete_quant_ref.real"></a><h6>
+<a name="id766478"></a>
+ real
+ </h6>
+<p>
+ Ignores the discreteness of the distribution, and returns a real-valued
+ result. For example:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">negative_binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span>
+ <span class="keyword">double</span><span class="special">,</span>
+ <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">discrete_quantile</span><span class="special">&lt;</span><span class="identifier">integer_round_inwards</span><span class="special">&gt;</span> <span class="special">&gt;</span>
+ <span class="special">&gt;</span> <span class="identifier">dist_type</span><span class="special">;</span>
+
+<span class="comment">// Lower quantile:
+</span><span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">dist_type</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">),</span> <span class="number">0.05</span><span class="special">);</span>
+<span class="comment">// Upper quantile:
+</span><span class="keyword">double</span> <span class="identifier">y</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist_type</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">),</span> <span class="number">0.05</span><span class="special">));</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Results in <code class="computeroutput"><span class="identifier">x</span> <span class="special">=</span>
+ <span class="number">27.3898</span></code> and <code class="computeroutput"><span class="identifier">y</span>
+ <span class="special">=</span> <span class="number">68.1584</span></code>.
+ </p>
+<a name="math_toolkit.policy.pol_ref.discrete_quant_ref.integer_round_outwards"></a><h6>
+<a name="id766971"></a>
+ integer_round_outwards
+ </h6>
+<p>
+ This is the default policy: an integer value is returned so that:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Lower quantiles (where the probability is less than 0.5) are rounded
+ down.
+ </li>
+<li>
+ Upper quantiles (where the probability is greater than 0.5) are rounded
+ up.
+ </li>
+</ul></div>
+<p>
+ This is normally the safest rounding policy, since it ensures that both
+ one and two sided intervals are guaranteed to have <span class="emphasis"><em>at least</em></span>
+ the requested coverage. For example:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">negative_binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+
+<span class="comment">// Lower quantile rounded down:
+</span><span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">),</span> <span class="number">0.05</span><span class="special">);</span>
+<span class="comment">// Upper quantile rounded up:
+</span><span class="keyword">double</span> <span class="identifier">y</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">),</span> <span class="number">0.05</span><span class="special">));</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Results in <code class="computeroutput"><span class="identifier">x</span> <span class="special">=</span>
+ <span class="number">27</span></code> (rounded down from 27.3898) and
+ <code class="computeroutput"><span class="identifier">y</span> <span class="special">=</span>
+ <span class="number">69</span></code> (rounded up from 68.1584).
+ </p>
+<p>
+ The variables x and y are now defined so that:
+ </p>
+<pre class="programlisting">
+<span class="identifier">cdf</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="number">20</span><span class="special">),</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">&lt;=</span> <span class="number">0.05</span>
+<span class="identifier">cdf</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="number">20</span><span class="special">),</span> <span class="identifier">y</span><span class="special">)</span> <span class="special">&gt;=</span> <span class="number">0.95</span>
+</pre>
+<p>
+ In other words we guarantee <span class="emphasis"><em>at least 90% coverage in the central
+ region overall</em></span>, and also <span class="emphasis"><em>no more than 5% coverage
+ in each tail</em></span>.
+ </p>
+<a name="math_toolkit.policy.pol_ref.discrete_quant_ref.integer_round_inwards"></a><h6>
+<a name="id767498"></a>
+ integer_round_inwards
+ </h6>
+<p>
+ This is the opposite of <span class="emphasis"><em>integer_round_outwards</em></span>: an
+ integer value is returned so that:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Lower quantiles (where the probability is less than 0.5) are rounded
+ <span class="emphasis"><em>up</em></span>.
+ </li>
+<li>
+ Upper quantiles (where the probability is greater than 0.5) are rounded
+ <span class="emphasis"><em>down</em></span>.
+ </li>
+</ul></div>
+<p>
+ For example:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">negative_binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span>
+ <span class="keyword">double</span><span class="special">,</span>
+ <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">discrete_quantile</span><span class="special">&lt;</span><span class="identifier">integer_round_inwards</span><span class="special">&gt;</span> <span class="special">&gt;</span>
+ <span class="special">&gt;</span> <span class="identifier">dist_type</span><span class="special">;</span>
+
+<span class="comment">// Lower quantile rounded up:
+</span><span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">dist_type</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">),</span> <span class="number">0.05</span><span class="special">);</span>
+<span class="comment">// Upper quantile rounded down:
+</span><span class="keyword">double</span> <span class="identifier">y</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist_type</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">),</span> <span class="number">0.05</span><span class="special">));</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Results in <code class="computeroutput"><span class="identifier">x</span> <span class="special">=</span>
+ <span class="number">28</span></code> (rounded up from 27.3898) and
+ <code class="computeroutput"><span class="identifier">y</span> <span class="special">=</span>
+ <span class="number">68</span></code> (rounded down from 68.1584).
+ </p>
+<p>
+ The variables x and y are now defined so that:
+ </p>
+<pre class="programlisting">
+<span class="identifier">cdf</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="number">20</span><span class="special">),</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">&gt;=</span> <span class="number">0.05</span>
+<span class="identifier">cdf</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="number">20</span><span class="special">),</span> <span class="identifier">y</span><span class="special">)</span> <span class="special">&lt;=</span> <span class="number">0.95</span>
+</pre>
+<p>
+ In other words we guarantee <span class="emphasis"><em>at no more than 90% coverage in the
+ central region overall</em></span>, and also <span class="emphasis"><em>at least 5% coverage
+ in each tail</em></span>.
+ </p>
+<a name="math_toolkit.policy.pol_ref.discrete_quant_ref.integer_round_down"></a><h6>
+<a name="id768161"></a>
+ integer_round_down
+ </h6>
+<p>
+ Always rounds down to an integer value, no matter whether it's an upper
+ or a lower quantile.
+ </p>
+<a name="math_toolkit.policy.pol_ref.discrete_quant_ref.integer_round_up"></a><h6>
+<a name="id768192"></a>
+ integer_round_up
+ </h6>
+<p>
+ Always rounds up to an integer value, no matter whether it's an upper or
+ a lower quantile.
+ </p>
+<a name="math_toolkit.policy.pol_ref.discrete_quant_ref.integer_round_nearest"></a><h6>
+<a name="id768224"></a>
+ integer_round_nearest
+ </h6>
+<p>
+ Always rounds to the nearest integer value, no matter whether it's an upper
+ or a lower quantile. This will produce the requested coverage <span class="emphasis"><em>in
+ the average case</em></span>, but for any specific example may results in
+ either significantly more or less coverage than the requested amount. For
+ example:
+ </p>
+<p>
+ For example:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">negative_binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span>
+ <span class="keyword">double</span><span class="special">,</span>
+ <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">discrete_quantile</span><span class="special">&lt;</span><span class="identifier">integer_round_nearest</span><span class="special">&gt;</span> <span class="special">&gt;</span>
+ <span class="special">&gt;</span> <span class="identifier">dist_type</span><span class="special">;</span>
+
+<span class="comment">// Lower quantile rounded up:
+</span><span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">dist_type</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">),</span> <span class="number">0.05</span><span class="special">);</span>
+<span class="comment">// Upper quantile rounded down:
+</span><span class="keyword">double</span> <span class="identifier">y</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist_type</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">),</span> <span class="number">0.05</span><span class="special">));</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Results in <code class="computeroutput"><span class="identifier">x</span> <span class="special">=</span>
+ <span class="number">27</span></code> (rounded from 27.3898) and <code class="computeroutput"><span class="identifier">y</span> <span class="special">=</span> <span class="number">68</span></code> (rounded from 68.1584).
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="assert_undefined.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="precision_pol.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/error_handling_policies.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/error_handling_policies.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,697 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Error Handling Policies</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_ref.html" title="Policy Reference">
+<link rel="prev" href="../pol_ref.html" title="Policy Reference">
+<link rel="next" href="internal_promotion.html" title="Internal Promotion Policies">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="internal_promotion.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_ref.error_handling_policies"></a><a href="error_handling_policies.html" title="Error Handling Policies">
+ Error Handling Policies</a>
+</h4></div></div></div>
+<p>
+ There are two orthogonal aspects to error handling:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ What to do (if anything) with the error.
+ </li>
+<li>
+ What kind of error is being raised.
+ </li>
+</ul></div>
+<a name="math_toolkit.policy.pol_ref.error_handling_policies.available_actions_when_an_error_is_raised"></a><h5>
+<a name="id761014"></a>
+ <a href="error_handling_policies.html#math_toolkit.policy.pol_ref.error_handling_policies.available_actions_when_an_error_is_raised">Available
+ Actions When an Error is Raised</a>
+ </h5>
+<p>
+ What to do with the error is encapsulated by an enumerated type:
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">policies</span> <span class="special">{</span>
+
+<span class="keyword">enum</span> <span class="identifier">error_policy_type</span>
+<span class="special">{</span>
+ <span class="identifier">throw_on_error</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="comment">// throw an exception.
+</span> <span class="identifier">errno_on_error</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="comment">// set ::errno &amp; return 0, NaN, infinity or best guess.
+</span> <span class="identifier">ignore_error</span> <span class="special">=</span> <span class="number">2</span><span class="special">,</span> <span class="comment">// return 0, NaN, infinity or best guess.
+</span> <span class="identifier">user_error</span> <span class="special">=</span> <span class="number">3</span> <span class="comment">// call a user-defined error handler.
+</span><span class="special">};</span>
+
+<span class="special">}}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The various enumerated values have the following meanings:
+ </p>
+<a name="math_toolkit.policy.pol_ref.error_handling_policies.throw_on_error"></a><h6>
+<a name="id761268"></a>
+ throw_on_error
+ </h6>
+<p>
+ Will throw one of the following exceptions, depending upon the type of
+ the error:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Error Type
+ </p>
+ </th>
+<th>
+ <p>
+ Exception
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ Domain Error
+ </p>
+ </td>
+<td>
+ <p>
+ std::domain_error
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Pole Error
+ </p>
+ </td>
+<td>
+ <p>
+ std::domain_error
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Overflow Error
+ </p>
+ </td>
+<td>
+ <p>
+ std::overflow_error
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Underflow Error
+ </p>
+ </td>
+<td>
+ <p>
+ std::underflow_error
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Denorm Error
+ </p>
+ </td>
+<td>
+ <p>
+ std::underflow_error
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Evaluation Error
+ </p>
+ </td>
+<td>
+ <p>
+ boost::math::evaluation_error
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.policy.pol_ref.error_handling_policies.errno_on_error"></a><h6>
+<a name="id761450"></a>
+ errno_on_error
+ </h6>
+<p>
+ Will set global <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
+ to one of the following values depending upon the error type, and then
+ return the same value as if the error had been ignored:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Error Type
+ </p>
+ </th>
+<th>
+ <p>
+ errno value
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ Domain Error
+ </p>
+ </td>
+<td>
+ <p>
+ EDOM
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Pole Error
+ </p>
+ </td>
+<td>
+ <p>
+ EDOM
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Overflow Error
+ </p>
+ </td>
+<td>
+ <p>
+ ERANGE
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Underflow Error
+ </p>
+ </td>
+<td>
+ <p>
+ ERANGE
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Denorm Error
+ </p>
+ </td>
+<td>
+ <p>
+ ERANGE
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Evaluation Error
+ </p>
+ </td>
+<td>
+ <p>
+ EDOM
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.policy.pol_ref.error_handling_policies.ignore_error"></a><h6>
+<a name="id761649"></a>
+ ignore_error
+ </h6>
+<p>
+ Will return a one of the values below depending on the error type (<code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
+ is NOT changed)::
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Error Type
+ </p>
+ </th>
+<th>
+ <p>
+ Returned Value
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ Domain Error
+ </p>
+ </td>
+<td>
+ <p>
+ std::numeric_limits&lt;T&gt;::quiet_NaN()
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Pole Error
+ </p>
+ </td>
+<td>
+ <p>
+ std::numeric_limits&lt;T&gt;::quiet_NaN()
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Overflow Error
+ </p>
+ </td>
+<td>
+ <p>
+ std::numeric_limits&lt;T&gt;::infinity()
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Underflow Error
+ </p>
+ </td>
+<td>
+ <p>
+ 0
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Denorm Error
+ </p>
+ </td>
+<td>
+ <p>
+ The denormalised value.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Evaluation Error
+ </p>
+ </td>
+<td>
+ <p>
+ The best guess as to the result: which may be significantly in
+ error.
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.policy.pol_ref.error_handling_policies.user_error"></a><h6>
+<a name="id761850"></a>
+ user_error
+ </h6>
+<p>
+ Will call a user defined error handler: these are forward declared in boost/math/policies/error_handling.hpp,
+ but the actual definitions must be provided by the user:
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">policies</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_domain_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_pole_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_overflow_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_underflow_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_denorm_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_evaluation_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+
+<span class="special">}}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ Note that the strings <span class="emphasis"><em>function</em></span> and <span class="emphasis"><em>message</em></span>
+ may contain "%1%" format specifiers designed to be used in conjunction
+ with Boost.Format. If these strings are to be presented to the program's
+ end-user then the "%1%" format specifier should be replaced with
+ the name of type T in the <span class="emphasis"><em>function</em></span> string, and if
+ there is a %1% specifier in the <span class="emphasis"><em>message</em></span> string then
+ it should be replaced with the value of <span class="emphasis"><em>val</em></span>.
+ </p>
+<p>
+ There is more information on user-defined error handlers in the <a href="../pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">tutorial
+ here</a>.
+ </p>
+<a name="math_toolkit.policy.pol_ref.error_handling_policies.kinds_of_error_raised"></a><h5>
+<a name="id762789"></a>
+ <a href="error_handling_policies.html#math_toolkit.policy.pol_ref.error_handling_policies.kinds_of_error_raised">Kinds
+ of Error Raised</a>
+ </h5>
+<p>
+ There are five kinds of error reported by this library, which are summarised
+ in the following table:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Error Type
+ </p>
+ </th>
+<th>
+ <p>
+ Policy Class
+ </p>
+ </th>
+<th>
+ <p>
+ Description
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ Domain Error
+ </p>
+ </td>
+<td>
+ <p>
+ boost::math::policies::domain_error&lt;<span class="emphasis"><em>action</em></span>&gt;
+ </p>
+ </td>
+<td>
+ <p>
+ Raised when more or more arguments are outside the defined range
+ of the function.
+ </p>
+ <p>
+ Defaults to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">throw_on_error</span><span class="special">&gt;</span></code>
+ </p>
+ <p>
+ When the action is set to <span class="emphasis"><em>throw_on_error</em></span> then
+ throws <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Pole Error
+ </p>
+ </td>
+<td>
+ <p>
+ boost::math::policies::pole_error&lt;<span class="emphasis"><em>action</em></span>&gt;
+ </p>
+ </td>
+<td>
+ <p>
+ Raised when more or more arguments would cause the function to
+ be evaluated at a pole.
+ </p>
+ <p>
+ Defaults to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">pole_error</span><span class="special">&lt;</span><span class="identifier">throw_on_error</span><span class="special">&gt;</span></code>
+ </p>
+ <p>
+ When the action is <span class="emphasis"><em>throw_on_error</em></span> then throw
+ a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Overflow Error
+ </p>
+ </td>
+<td>
+ <p>
+ boost::math::policies::overflow_error&lt;<span class="emphasis"><em>action</em></span>&gt;
+ </p>
+ </td>
+<td>
+ <p>
+ Raised when the result of the function is outside the representable
+ range of the floating point type used.
+ </p>
+ <p>
+ Defaults to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">overflow_error</span><span class="special">&lt;</span><span class="identifier">throw_on_error</span><span class="special">&gt;</span></code>.
+ </p>
+ <p>
+ When the action is <span class="emphasis"><em>throw_on_error</em></span> then throws
+ a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">overflow_error</span></code>.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Underflow Error
+ </p>
+ </td>
+<td>
+ <p>
+ boost::math::policies::underflow_error&lt;<span class="emphasis"><em>action</em></span>&gt;
+ </p>
+ </td>
+<td>
+ <p>
+ Raised when the result of the function is too small to be represented
+ in the floating point type used.
+ </p>
+ <p>
+ Defaults to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">underflow_error</span><span class="special">&lt;</span><span class="identifier">ignore_error</span><span class="special">&gt;</span></code>
+ </p>
+ <p>
+ When the specified action is <span class="emphasis"><em>throw_on_error</em></span>
+ then throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">underflow_error</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Denorm Error
+ </p>
+ </td>
+<td>
+ <p>
+ boost::math::policies::denorm_error&lt;<span class="emphasis"><em>action</em></span>&gt;
+ </p>
+ </td>
+<td>
+ <p>
+ Raised when the result of the function is a denormalised value.
+ </p>
+ <p>
+ Defaults to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">denorm_error</span><span class="special">&lt;</span><span class="identifier">ignore_error</span><span class="special">&gt;</span></code>
+ </p>
+ <p>
+ When the action is <span class="emphasis"><em>throw_on_error</em></span> then throws
+ a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">underflow_error</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Evaluation Error
+ </p>
+ </td>
+<td>
+ <p>
+ boost::math::policies::evaluation_error&lt;<span class="emphasis"><em>action</em></span>&gt;
+ </p>
+ </td>
+<td>
+ <p>
+ Raised when the result of the function is well defined and finite,
+ but we were unable to compute it. Typically this occurs when an
+ iterative method fails to converge. Of course ideally this error
+ should never be raised: feel free to report it as a bug if it is!
+ </p>
+ <p>
+ Defaults to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">evaluation_error</span><span class="special">&lt;</span><span class="identifier">throw_on_error</span><span class="special">&gt;</span></code>
+ </p>
+ <p>
+ When the action is <span class="emphasis"><em>throw_on_error</em></span> then throws
+ <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">evaluation_error</span></code>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.policy.pol_ref.error_handling_policies.examples"></a><h5>
+<a name="id763630"></a>
+ Examples
+ </h5>
+<p>
+ Suppose we want a call to <code class="computeroutput"><span class="identifier">tgamma</span></code>
+ to behave in a C-compatible way and set global <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code> rather than throw an exception,
+ we can achieve this at the call site using:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+
+<span class="comment">// Define a policy:
+</span><span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span>
+ <span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span>
+ <span class="identifier">pole_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span>
+ <span class="identifier">overflow_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span>
+ <span class="identifier">policies</span><span class="special">::</span><span class="identifier">evaluation_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;</span>
+ <span class="special">&gt;</span> <span class="identifier">my_policy</span><span class="special">;</span>
+
+<span class="comment">// call the function:
+</span><span class="keyword">double</span> <span class="identifier">t1</span> <span class="special">=</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">some_value</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">());</span>
+
+<span class="comment">// Alternatively we could use make_policy and define everything at the call site:
+</span><span class="keyword">double</span> <span class="identifier">t2</span> <span class="special">=</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">some_value</span><span class="special">,</span> <span class="identifier">make_policy</span><span class="special">(</span>
+ <span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;(),</span>
+ <span class="identifier">pole_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;(),</span>
+ <span class="identifier">overflow_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;(),</span>
+ <span class="identifier">policies</span><span class="special">::</span><span class="identifier">evaluation_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;()</span>
+ <span class="special">));</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Suppose we want a statistical distribution to return infinities, rather
+ than throw exceptions, then we can use:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">normal</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+
+<span class="comment">// Define a policy:
+</span><span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span>
+ <span class="identifier">overflow_error</span><span class="special">&lt;</span><span class="identifier">ignore_error</span><span class="special">&gt;</span>
+ <span class="special">&gt;</span> <span class="identifier">my_policy</span><span class="special">;</span>
+
+<span class="comment">// Define the distribution:
+</span><span class="keyword">typedef</span> <span class="identifier">normal_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">&gt;</span> <span class="identifier">my_norm</span><span class="special">;</span>
+
+<span class="comment">// Get a quantile:
+</span><span class="keyword">double</span> <span class="identifier">q</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">my_norm</span><span class="special">(),</span> <span class="number">0.05</span><span class="special">);</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="internal_promotion.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/internal_promotion.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/internal_promotion.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,178 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Internal Promotion Policies</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_ref.html" title="Policy Reference">
+<link rel="prev" href="error_handling_policies.html" title="Error Handling Policies">
+<link rel="next" href="assert_undefined.html" title="Mathematically Undefined Function Policies">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="error_handling_policies.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="assert_undefined.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_ref.internal_promotion"></a><a href="internal_promotion.html" title="Internal Promotion Policies"> Internal
+ Promotion Policies</a>
+</h4></div></div></div>
+<p>
+ Normally when evaluating a function at say <code class="computeroutput"><span class="keyword">float</span></code>
+ precision, maximal accuracy is assured by conducting the calculation at
+ <code class="computeroutput"><span class="keyword">double</span></code> precision internally,
+ and then rounding the result. There are two policies that effect whether
+ internal promotion takes place or not:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Policy
+ </p>
+ </th>
+<th>
+ <p>
+ Meaning
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">promote_float</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ Indicates whether <code class="computeroutput"><span class="keyword">float</span></code>
+ arguments should be promoted to <code class="computeroutput"><span class="keyword">double</span></code>
+ precision internally: defaults to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">promote_float</span><span class="special">&lt;</span><span class="keyword">true</span><span class="special">&gt;</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">promote_double</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ Indicates whether <code class="computeroutput"><span class="keyword">double</span></code>
+ arguments should be promoted to <code class="computeroutput"><span class="keyword">long</span>
+ <span class="keyword">double</span></code> precision internally:
+ defaults to <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">promote_double</span><span class="special">&lt;</span><span class="keyword">true</span><span class="special">&gt;</span></code>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.policy.pol_ref.internal_promotion.examples"></a><h5>
+<a name="id764959"></a>
+ Examples
+ </h5>
+<p>
+ Suppose we want <code class="computeroutput"><span class="identifier">tgamma</span></code>
+ to be evaluated without internal promotion to <code class="computeroutput"><span class="keyword">long</span>
+ <span class="keyword">double</span></code>, then we could use:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+
+<span class="comment">// Define a policy:
+</span><span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span>
+ <span class="identifier">promote_double</span><span class="special">&lt;</span><span class="keyword">false</span><span class="special">&gt;</span>
+ <span class="special">&gt;</span> <span class="identifier">my_policy</span><span class="special">;</span>
+
+<span class="comment">// Call the function:
+</span><span class="keyword">double</span> <span class="identifier">t1</span> <span class="special">=</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">some_value</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">());</span>
+
+<span class="comment">// Alternatively we could use make_policy and define everything at the call site:
+</span><span class="keyword">double</span> <span class="identifier">t2</span> <span class="special">=</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">some_value</span><span class="special">,</span> <span class="identifier">make_policy</span><span class="special">(</span><span class="identifier">promote_double</span><span class="special">&lt;</span><span class="keyword">false</span><span class="special">&gt;()));</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Alternatively, suppose we want a distribution to perform calculations without
+ promoting <code class="computeroutput"><span class="keyword">float</span></code> to <code class="computeroutput"><span class="keyword">double</span></code>, then we could use:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">normal</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+
+<span class="comment">// Define a policy:
+</span><span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span>
+ <span class="identifier">promote_float</span><span class="special">&lt;</span><span class="keyword">false</span><span class="special">&gt;</span>
+ <span class="special">&gt;</span> <span class="identifier">my_policy</span><span class="special">;</span>
+
+<span class="comment">// Define the distribution:
+</span><span class="keyword">typedef</span> <span class="identifier">normal_distribution</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">&gt;</span> <span class="identifier">my_norm</span><span class="special">;</span>
+
+<span class="comment">// Get a quantile:
+</span><span class="keyword">float</span> <span class="identifier">q</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">my_norm</span><span class="special">(),</span> <span class="number">0.05f</span><span class="special">);</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="error_handling_policies.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="assert_undefined.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/iteration_pol.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/iteration_pol.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,63 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Iteration Limits Policies</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_ref.html" title="Policy Reference">
+<link rel="prev" href="precision_pol.html" title="Precision Policies">
+<link rel="next" href="policy_defaults.html" title="Using macros to Change the Policy Defaults">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="precision_pol.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="policy_defaults.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_ref.iteration_pol"></a><a href="iteration_pol.html" title="Iteration Limits Policies"> Iteration
+ Limits Policies</a>
+</h4></div></div></div>
+<p>
+ There are two policies that effect the iterative algorithms used to implement
+ the special functions in this library:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">unsigned</span> <span class="keyword">long</span> <span class="identifier">limit</span> <span class="special">=</span> <span class="identifier">BOOST_MATH_MAX_SERIES_ITERATION_POLICY</span><span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">max_series_iterations</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">unsigned</span> <span class="keyword">long</span> <span class="identifier">limit</span> <span class="special">=</span> <span class="identifier">BOOST_MATH_MAX_ROOT_ITERATION_POLICY</span><span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">max_root_iterations</span><span class="special">;</span>
+</pre>
+<p>
+ The class <code class="computeroutput"><span class="identifier">max_series_iterations</span></code>
+ determines the maximum number of iterations permitted in a series evaluation,
+ before the special function gives up and returns the result of evaluation_error.
+ </p>
+<p>
+ The class <code class="computeroutput"><span class="identifier">max_root_iterations</span></code>
+ 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.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="precision_pol.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="policy_defaults.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/namespace_pol.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/namespace_pol.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,182 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Setting Polices at Namespace Scope</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_ref.html" title="Policy Reference">
+<link rel="prev" href="policy_defaults.html" title="Using macros to Change the Policy Defaults">
+<link rel="next" href="pol_ref_ref.html" title="Policy Class Reference">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="policy_defaults.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="pol_ref_ref.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_ref.namespace_pol"></a><a href="namespace_pol.html" title="Setting Polices at Namespace Scope"> Setting
+ Polices at Namespace Scope</a>
+</h4></div></div></div>
+<p>
+ Sometimes what you really want to do is bring all the special functions,
+ or all the distributions into a specific namespace-scope, along with a
+ specific policy to use with them. There are two macros defined to assist
+ with that:
+ </p>
+<pre class="programlisting">
+<span class="identifier">BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS</span><span class="special">(</span><span class="identifier">Policy</span><span class="special">)</span>
+</pre>
+<p>
+ and:
+ </p>
+<pre class="programlisting">
+<span class="identifier">BOOST_MATH_DECLARE_DISTRIBUTIONS</span><span class="special">(</span><span class="identifier">Type</span><span class="special">,</span> <span class="identifier">Policy</span><span class="special">)</span>
+</pre>
+<p>
+ You can use either of these macros after including any special function
+ or distribution header. For example:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">namespace</span> <span class="identifier">myspace</span><span class="special">{</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+
+<span class="comment">// Define a policy that does not throw on overflow:
+</span><span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">overflow_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">my_policy</span><span class="special">;</span>
+
+<span class="comment">// Define the special functions in this scope to use the policy:
+</span><span class="identifier">BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS</span><span class="special">(</span><span class="identifier">my_policy</span><span class="special">)</span>
+
+<span class="special">}</span>
+
+<span class="comment">//
+</span><span class="comment">// Now we can use myspace::tgamma etc.
+</span><span class="comment">// They will automatically use "my_policy":
+</span><span class="comment">//
+</span><span class="keyword">double</span> <span class="identifier">t</span> <span class="special">=</span> <span class="identifier">myspace</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="number">30.0</span><span class="special">);</span> <span class="comment">// will not throw on overflow
+</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ In this example, using BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS results in
+ a set of thin inline forwarding functions being defined:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">inline</span> <span class="identifier">T</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">a</span><span class="special">){</span> <span class="keyword">return</span> <span class="special">::</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">mypolicy</span><span class="special">());</span> <span class="special">}</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">inline</span> <span class="identifier">T</span> <span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">a</span><span class="special">)</span> <span class="special">(</span> <span class="keyword">return</span> <span class="special">::</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">mypolicy</span><span class="special">());</span> <span class="special">}</span>
+</pre>
+<p>
+ and so on. Note that while a forwarding function is defined for all the
+ special functions, however, unless you include the specific header for
+ the special function you use (or boost/math/special_functions.hpp to include
+ everything), you will get linker errors from functions that are forward
+ declared, but not defined.
+ </p>
+<p>
+ We can do the same thing with the distributions, but this time we need
+ to specify the floating-point type to use:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">cauchy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">namespace</span> <span class="identifier">myspace</span><span class="special">{</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+
+<span class="comment">// Define a policy to use, in this case we want all the distribution
+</span><span class="comment">// accessor functions to compile, even if they are mathematically
+</span><span class="comment">// undefined:
+</span><span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">assert_undefined</span><span class="special">&lt;</span><span class="keyword">false</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">my_policy</span><span class="special">;</span>
+
+<span class="identifier">BOOST_MATH_DECLARE_DISTRIBUTIONS</span><span class="special">(</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">)</span>
+
+<span class="special">}</span>
+
+<span class="comment">// Now we can use myspace::cauchy etc, which will use policy
+</span><span class="comment">// myspace::mypolicy:
+</span><span class="comment">//
+</span><span class="comment">// This compiles but raises a domain error at runtime:
+</span><span class="comment">//
+</span><span class="keyword">void</span> <span class="identifier">test_cauchy</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="keyword">try</span>
+ <span class="special">{</span>
+ <span class="keyword">double</span> <span class="identifier">d</span> <span class="special">=</span> <span class="identifier">mean</span><span class="special">(</span><span class="identifier">myspace</span><span class="special">::</span><span class="identifier">cauchy</span><span class="special">());</span>
+ <span class="special">}</span>
+ <span class="keyword">catch</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span><span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="special">}</span>
+<span class="special">}</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ In this example the result of BOOST_MATH_DECLARE_DISTRIBUTIONS is to declare
+ a typedef for each distribution like this:
+ </p>
+<pre class="programlisting">
+<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">cauchy_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">&gt;</span> <span class="identifier">cauchy</span><span class="special">;</span>
+<span class="identifier">tyepdef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">gamma_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">&gt;</span> <span class="identifier">gamma</span><span class="special">;</span>
+</pre>
+<p>
+ and so on. The name given to each typedef is the name of the distribution
+ with the "_distribution" suffix removed.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="policy_defaults.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="pol_ref_ref.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/pol_ref_ref.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/pol_ref_ref.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,246 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Policy Class Reference</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_ref.html" title="Policy Reference">
+<link rel="prev" href="namespace_pol.html" title="Setting Polices at Namespace Scope">
+<link rel="next" href="../../perf.html" title="Performance">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="namespace_pol.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../../perf.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_ref.pol_ref_ref"></a><a href="pol_ref_ref.html" title="Policy Class Reference"> Policy Class
+ Reference</a>
+</h4></div></div></div>
+<p>
+ There's very little to say here, the <code class="computeroutput"><span class="identifier">policy</span></code>
+ class is just a rag-bag compile-time container for a collection of policies:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">policies</span><span class="special">/</span><span class="identifier">policy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span>
+<span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+<span class="keyword">namespace</span> <span class="identifier">policies</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">A1</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A2</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A3</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A4</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A5</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A6</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A7</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A8</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A9</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A10</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A11</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">policy</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="emphasis"><em>computed-from-template-arguments</em></span> <span class="identifier">domain_error_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="emphasis"><em>computed-from-template-arguments</em></span> <span class="identifier">pole_error_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="emphasis"><em>computed-from-template-arguments</em></span> <span class="identifier">overflow_error_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="emphasis"><em>computed-from-template-arguments</em></span> <span class="identifier">underflow_error_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="emphasis"><em>computed-from-template-arguments</em></span> <span class="identifier">denorm_error_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="emphasis"><em>computed-from-template-arguments</em></span> <span class="identifier">evaluation_error_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="emphasis"><em>computed-from-template-arguments</em></span> <span class="identifier">precision_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="emphasis"><em>computed-from-template-arguments</em></span> <span class="identifier">promote_float_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="emphasis"><em>computed-from-template-arguments</em></span> <span class="identifier">promote_double_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="emphasis"><em>computed-from-template-arguments</em></span> <span class="identifier">discrete_quantile_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="emphasis"><em>computed-from-template-arguments</em></span> <span class="identifier">assert_undefined_type</span><span class="special">;</span>
+<span class="special">};</span>
+
+<span class="keyword">template</span> <span class="special">&lt;...</span><span class="identifier">argument</span> <span class="identifier">list</span><span class="special">...&gt;</span>
+<span class="keyword">typename</span> <span class="identifier">normalise</span><span class="special">&lt;</span><span class="identifier">policy</span><span class="special">&lt;&gt;,</span> <span class="identifier">A1</span><span class="special">&gt;::</span><span class="identifier">type</span> <span class="identifier">make_policy</span><span class="special">(...</span><span class="identifier">argument</span> <span class="identifier">list</span><span class="special">..);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A1</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A2</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A3</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A4</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A5</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A6</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A7</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A8</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A9</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A10</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A11</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">normalise</span>
+<span class="special">{</span>
+ <span class="keyword">typedef</span> computed-from-template-arguments <span class="identifier">type</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ The member typedefs of class <code class="computeroutput"><span class="identifier">policy</span></code>
+ are intended for internal use but are documented briefly here for the sake
+ of completeness.
+ </p>
+<pre class="programlisting">
+<span class="identifier">policy</span><span class="special">&lt;...&gt;::</span><span class="identifier">domain_error_type</span>
+</pre>
+<p>
+ Specifies how domain errors are handled, will be an instance of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">domain_error</span><span class="special">&lt;&gt;</span></code>
+ with the template argument to <code class="computeroutput"><span class="identifier">domain_error</span></code>
+ one of the <code class="computeroutput"><span class="identifier">error_policy_type</span></code>
+ enumerated values.
+ </p>
+<pre class="programlisting">
+<span class="identifier">policy</span><span class="special">&lt;...&gt;::</span><span class="identifier">pole_error_type</span>
+</pre>
+<p>
+ Specifies how pole-errors are handled, will be an instance of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">pole_error</span><span class="special">&lt;&gt;</span></code>
+ with the template argument to <code class="computeroutput"><span class="identifier">pole_error</span></code>
+ one of the <code class="computeroutput"><span class="identifier">error_policy_type</span></code>
+ enumerated values.
+ </p>
+<pre class="programlisting">
+<span class="identifier">policy</span><span class="special">&lt;...&gt;::</span><span class="identifier">overflow_error_type</span>
+</pre>
+<p>
+ Specifies how overflow errors are handled, will be an instance of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">overflow_error</span><span class="special">&lt;&gt;</span></code>
+ with the template argument to <code class="computeroutput"><span class="identifier">overflow_error</span></code>
+ one of the <code class="computeroutput"><span class="identifier">error_policy_type</span></code>
+ enumerated values.
+ </p>
+<pre class="programlisting">
+<span class="identifier">policy</span><span class="special">&lt;...&gt;::</span><span class="identifier">underflow_error_type</span>
+</pre>
+<p>
+ Specifies how underflow errors are handled, will be an instance of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">underflow_error</span><span class="special">&lt;&gt;</span></code>
+ with the template argument to <code class="computeroutput"><span class="identifier">underflow_error</span></code>
+ one of the <code class="computeroutput"><span class="identifier">error_policy_type</span></code>
+ enumerated values.
+ </p>
+<pre class="programlisting">
+<span class="identifier">policy</span><span class="special">&lt;...&gt;::</span><span class="identifier">denorm_error_type</span>
+</pre>
+<p>
+ Specifies how denorm errors are handled, will be an instance of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">denorm_error</span><span class="special">&lt;&gt;</span></code>
+ with the template argument to <code class="computeroutput"><span class="identifier">denorm_error</span></code>
+ one of the <code class="computeroutput"><span class="identifier">error_policy_type</span></code>
+ enumerated values.
+ </p>
+<pre class="programlisting">
+<span class="identifier">policy</span><span class="special">&lt;...&gt;::</span><span class="identifier">evaluation_error_type</span>
+</pre>
+<p>
+ Specifies how evaluation errors are handled, will be an instance of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">evaluation_error</span><span class="special">&lt;&gt;</span></code>
+ with the template argument to <code class="computeroutput"><span class="identifier">evaluation_error</span></code>
+ one of the <code class="computeroutput"><span class="identifier">error_policy_type</span></code>
+ enumerated values.
+ </p>
+<pre class="programlisting">
+<span class="identifier">policy</span><span class="special">&lt;...&gt;::</span><span class="identifier">precision_type</span>
+</pre>
+<p>
+ Specifies the internal precision to use in binary digits (uses zero to
+ represent whatever the default precision is). Will be an instance of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">digits2</span><span class="special">&lt;</span><span class="identifier">N</span><span class="special">&gt;</span></code>
+ which in turn inherits from <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">int_</span><span class="special">&lt;</span><span class="identifier">N</span><span class="special">&gt;</span></code>.
+ </p>
+<pre class="programlisting">
+<span class="identifier">policy</span><span class="special">&lt;...&gt;::</span><span class="identifier">promote_float_type</span>
+</pre>
+<p>
+ Specifies whether or not to promote <code class="computeroutput"><span class="keyword">float</span></code>
+ arguments to <code class="computeroutput"><span class="keyword">double</span></code> precision
+ internally. Will be an instance of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">promote_float</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span></code> which in turn inherits from <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">bool_</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span></code>.
+ </p>
+<pre class="programlisting">
+<span class="identifier">policy</span><span class="special">&lt;...&gt;::</span><span class="identifier">promote_double_type</span>
+</pre>
+<p>
+ Specifies whether or not to promote <code class="computeroutput"><span class="keyword">double</span></code>
+ arguments to <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>
+ precision internally. Will be an instance of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">promote_float</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span></code> which in turn inherits from <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">bool_</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span></code>.
+ </p>
+<pre class="programlisting">
+<span class="identifier">policy</span><span class="special">&lt;...&gt;::</span><span class="identifier">discrete_quantile_type</span>
+</pre>
+<p>
+ Specifies how discrete quantiles are evaluated, will be an instance of
+ <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">discrete_quantile</span><span class="special">&lt;&gt;</span></code>
+ instantiated with one of the <code class="computeroutput"><span class="identifier">discrete_quantile_policy_type</span></code>
+ enumerated type.
+ </p>
+<pre class="programlisting">
+<span class="identifier">policy</span><span class="special">&lt;...&gt;::</span><span class="identifier">assert_undefined_type</span>
+</pre>
+<p>
+ Specifies whether mathematically-undefined properties are asserted as compile-time
+ errors, or treated as runtime errors instead. Will be an instance of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">assert_undefined</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span></code>
+ which in turn inherits from <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">bool_</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">&gt;</span></code>.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;...</span><span class="identifier">argument</span> <span class="identifier">list</span><span class="special">...&gt;</span>
+<span class="keyword">typename</span> <span class="identifier">normalise</span><span class="special">&lt;</span><span class="identifier">policy</span><span class="special">&lt;&gt;,</span> <span class="identifier">A1</span><span class="special">&gt;::</span><span class="identifier">type</span> <span class="identifier">make_policy</span><span class="special">(...</span><span class="identifier">argument</span> <span class="identifier">list</span><span class="special">..);</span>
+</pre>
+<p>
+ <code class="computeroutput"><span class="identifier">make_policy</span></code> is a helper
+ function that converts a list of policies into a normalised <code class="computeroutput"><span class="identifier">policy</span></code> class.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A1</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A2</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A3</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A4</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A5</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A6</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A7</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A8</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A9</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A10</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">,</span>
+ <span class="keyword">class</span> <span class="identifier">A11</span> <span class="special">=</span> <span class="identifier">default_policy</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">normalise</span>
+<span class="special">{</span>
+ <span class="keyword">typedef</span> computed-from-template-arguments <span class="identifier">type</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ The <code class="computeroutput"><span class="identifier">normalise</span></code> class template
+ converts one instantiation of the <code class="computeroutput"><span class="identifier">policy</span></code>
+ class into a normalised form. This is used internally to reduce code bloat:
+ so that instantiating a special function on <code class="computeroutput"><span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span><span class="identifier">B</span><span class="special">&gt;</span></code>
+ or <code class="computeroutput"><span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">,</span><span class="identifier">A</span><span class="special">&gt;</span></code> actually both generate the same code
+ internally.
+ </p>
+<p>
+ Further more, <code class="computeroutput"><span class="identifier">normalise</span></code>
+ can be used to combine a policy with one or more policies: for example
+ many of the special functions will use this to set policies which they
+ don't make use of to their default values, before forwarding to the actual
+ implementation. In this way code bloat is reduced, since the actual implementation
+ depends only on the policy types that they actually use.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="namespace_pol.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../../perf.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/policy_defaults.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/policy_defaults.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,236 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Using macros to Change the Policy Defaults</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_ref.html" title="Policy Reference">
+<link rel="prev" href="iteration_pol.html" title="Iteration Limits Policies">
+<link rel="next" href="namespace_pol.html" title="Setting Polices at Namespace Scope">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="iteration_pol.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="namespace_pol.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_ref.policy_defaults"></a><a href="policy_defaults.html" title="Using macros to Change the Policy Defaults"> Using
+ macros to Change the Policy Defaults</a>
+</h4></div></div></div>
+<p>
+ You can use the various macros below to change any (or all) of the policies.
+ </p>
+<p>
+ You can make a local change by placing a macro definition <span class="bold"><strong>before</strong></span>
+ a function or distribution #include.
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ There is a danger of One-Definition-Rule violations if you add ad-hock
+ macros to more than one source files: these must be set the same in
+ <span class="bold"><strong>every translation unit</strong></span>.
+ </p></td></tr>
+</table></div>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ If you place it after the #include it will have no effect, (and it will
+ affect only any other following #includes). This is probably not what
+ you intend!
+ </p></td></tr>
+</table></div>
+<p>
+ If you want to alter the defaults for any or all of the policies for <span class="bold"><strong>all</strong></span> functions and distributions, installation-wide,
+ then you can do so by defining various macros in boost/math/tools/user.hpp.
+ </p>
+<a name="math_toolkit.policy.pol_ref.policy_defaults.boost_math_domain_error_policy"></a><h6>
+<a name="id770057"></a>
+ BOOST_MATH_DOMAIN_ERROR_POLICY
+ </h6>
+<p>
+ Defines what happens when a domain error occurs, if not defined then defaults
+ to <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, but
+ can be set to any of the enumerated actions for error handing: <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, <code class="computeroutput"><span class="identifier">errno_on_error</span></code>,
+ <code class="computeroutput"><span class="identifier">ignore_error</span></code> or <code class="computeroutput"><span class="identifier">user_error</span></code>.
+ </p>
+<a name="math_toolkit.policy.pol_ref.policy_defaults.boost_math_pole_error_policy"></a><h6>
+<a name="id770150"></a>
+ BOOST_MATH_POLE_ERROR_POLICY
+ </h6>
+<p>
+ Defines what happens when a pole error occurs, if not defined then defaults
+ to <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, but
+ can be set to any of the enumerated actions for error handing: <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, <code class="computeroutput"><span class="identifier">errno_on_error</span></code>,
+ <code class="computeroutput"><span class="identifier">ignore_error</span></code> or <code class="computeroutput"><span class="identifier">user_error</span></code>.
+ </p>
+<a name="math_toolkit.policy.pol_ref.policy_defaults.boost_math_overflow_error_policy"></a><h6>
+<a name="id770242"></a>
+ BOOST_MATH_OVERFLOW_ERROR_POLICY
+ </h6>
+<p>
+ Defines what happens when an overflow error occurs, if not defined then
+ defaults to <code class="computeroutput"><span class="identifier">throw_on_error</span></code>,
+ but can be set to any of the enumerated actions for error handing: <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, <code class="computeroutput"><span class="identifier">errno_on_error</span></code>,
+ <code class="computeroutput"><span class="identifier">ignore_error</span></code> or <code class="computeroutput"><span class="identifier">user_error</span></code>.
+ </p>
+<a name="math_toolkit.policy.pol_ref.policy_defaults.boost_math_evaluation_error_policy"></a><h6>
+<a name="id770335"></a>
+ BOOST_MATH_EVALUATION_ERROR_POLICY
+ </h6>
+<p>
+ Defines what happens when an internal evaluation error occurs, if not defined
+ then defaults to <code class="computeroutput"><span class="identifier">throw_on_error</span></code>,
+ but can be set to any of the enumerated actions for error handing: <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, <code class="computeroutput"><span class="identifier">errno_on_error</span></code>,
+ <code class="computeroutput"><span class="identifier">ignore_error</span></code> or <code class="computeroutput"><span class="identifier">user_error</span></code>.
+ </p>
+<a name="math_toolkit.policy.pol_ref.policy_defaults.boost_math_underflow_error_policy"></a><h6>
+<a name="id770428"></a>
+ BOOST_MATH_UNDERFLOW_ERROR_POLICY
+ </h6>
+<p>
+ Defines what happens when an overflow error occurs, if not defined then
+ defaults to <code class="computeroutput"><span class="identifier">ignore_error</span></code>,
+ but can be set to any of the enumerated actions for error handing: <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, <code class="computeroutput"><span class="identifier">errno_on_error</span></code>,
+ <code class="computeroutput"><span class="identifier">ignore_error</span></code> or <code class="computeroutput"><span class="identifier">user_error</span></code>.
+ </p>
+<a name="math_toolkit.policy.pol_ref.policy_defaults.boost_math_denorm_error_policy"></a><h6>
+<a name="id770521"></a>
+ BOOST_MATH_DENORM_ERROR_POLICY
+ </h6>
+<p>
+ Defines what happens when a denormalisation error occurs, if not defined
+ then defaults to <code class="computeroutput"><span class="identifier">ignore_error</span></code>,
+ but can be set to any of the enumerated actions for error handing: <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, <code class="computeroutput"><span class="identifier">errno_on_error</span></code>,
+ <code class="computeroutput"><span class="identifier">ignore_error</span></code> or <code class="computeroutput"><span class="identifier">user_error</span></code>.
+ </p>
+<a name="math_toolkit.policy.pol_ref.policy_defaults.boost_math_digits10_policy"></a><h6>
+<a name="id770613"></a>
+ BOOST_MATH_DIGITS10_POLICY
+ </h6>
+<p>
+ Defines how many decimal digits to use in internal computations: defaults
+ to <code class="computeroutput"><span class="number">0</span></code> - meaning use all available
+ digits - but can be set to some other decimal value. Since setting this
+ is likely to have a substantial impact on accuracy, it's not generally
+ recommended that you change this from the default.
+ </p>
+<a name="math_toolkit.policy.pol_ref.policy_defaults.boost_math_promote_float_policy"></a><h6>
+<a name="id770662"></a>
+ BOOST_MATH_PROMOTE_FLOAT_POLICY
+ </h6>
+<p>
+ Determines whether <code class="computeroutput"><span class="keyword">float</span></code> types
+ get promoted to <code class="computeroutput"><span class="keyword">double</span></code> internally
+ to ensure maximum precision in the result, defaults to <code class="computeroutput"><span class="keyword">true</span></code>,
+ but can be set to <code class="computeroutput"><span class="keyword">false</span></code> to
+ turn promotion of <code class="computeroutput"><span class="keyword">float</span></code>'s
+ off.
+ </p>
+<a name="math_toolkit.policy.pol_ref.policy_defaults.boost_math_promote_double_policy"></a><h6>
+<a name="id770754"></a>
+ BOOST_MATH_PROMOTE_DOUBLE_POLICY
+ </h6>
+<p>
+ Determines whether <code class="computeroutput"><span class="keyword">double</span></code>
+ types get promoted to <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code> internally to ensure maximum precision
+ in the result, defaults to <code class="computeroutput"><span class="keyword">true</span></code>,
+ but can be set to <code class="computeroutput"><span class="keyword">false</span></code> to
+ turn promotion of <code class="computeroutput"><span class="keyword">double</span></code>'s
+ off.
+ </p>
+<a name="math_toolkit.policy.pol_ref.policy_defaults.boost_math_discrete_quantile_policy"></a><h6>
+<a name="id770853"></a>
+ BOOST_MATH_DISCRETE_QUANTILE_POLICY
+ </h6>
+<p>
+ Determines how discrete quantiles return their results: either as an integer,
+ or as a real value, can be set to one of the enumerated values: <code class="computeroutput"><span class="identifier">real</span></code>, <code class="computeroutput"><span class="identifier">integer_round_outwards</span></code>,
+ <code class="computeroutput"><span class="identifier">integer_round_inwards</span></code>,
+ <code class="computeroutput"><span class="identifier">integer_round_down</span></code>, <code class="computeroutput"><span class="identifier">integer_round_up</span></code>, <code class="computeroutput"><span class="identifier">integer_round_nearest</span></code>.
+ Defaults to <code class="computeroutput"><span class="identifier">integer_round_outwards</span></code>.
+ </p>
+<a name="math_toolkit.policy.pol_ref.policy_defaults.boost_math_assert_undefined_policy"></a><h6>
+<a name="id770969"></a>
+ BOOST_MATH_ASSERT_UNDEFINED_POLICY
+ </h6>
+<p>
+ Determines whether functions that are mathematically undefined for a specific
+ distribution compile or raise a static (i.e. compile-time) assertion. Defaults
+ to <code class="computeroutput"><span class="keyword">true</span></code>: meaning that any
+ mathematically undefined function will not compile. When set to <code class="computeroutput"><span class="keyword">false</span></code> then the function will compile but
+ return the result of a domain error: this can be useful for some generic
+ code, that needs to work with all distributions and determine at runtime
+ whether or not a particular property is well defined.
+ </p>
+<a name="math_toolkit.policy.pol_ref.policy_defaults.boost_math_max_series_iteration_policy"></a><h6>
+<a name="id771034"></a>
+ BOOST_MATH_MAX_SERIES_ITERATION_POLICY
+ </h6>
+<p>
+ Determines how many series iterations a special function is permitted to
+ perform before it gives up and returns an evaluation_error:
+ Defaults to 1000000.
+ </p>
+<a name="math_toolkit.policy.pol_ref.policy_defaults.boost_math_max_root_iteration_policy"></a><h6>
+<a name="id771076"></a>
+ BOOST_MATH_MAX_ROOT_ITERATION_POLICY
+ </h6>
+<p>
+ 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.
+ </p>
+<a name="math_toolkit.policy.pol_ref.policy_defaults.example"></a><h6>
+<a name="id771118"></a>
+ Example
+ </h6>
+<p>
+ Suppose we want overflow errors to set <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code> and return an infinity, discrete
+ quantiles to return a real-valued result (rather than round to integer),
+ and for mathematically undefined functions to compile, but return a domain
+ error. Then we could add the following to boost/math/tools/user.hpp:
+ </p>
+<pre class="programlisting">
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_OVERFLOW_ERROR_POLICY</span> <span class="identifier">errno_on_error</span>
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DISCRETE_QUANTILE_POLICY</span> <span class="identifier">real</span>
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_ASSERT_UNDEFINED_POLICY</span> <span class="keyword">false</span>
+</pre>
+<p>
+ or we could place these definitions <span class="bold"><strong>before</strong></span>
+ </p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">normal</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">normal_distribution</span><span class="special">;</span>
+</pre>
+<p>
+ in a source .cpp file.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="iteration_pol.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="namespace_pol.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/precision_pol.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_ref/precision_pol.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,158 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Precision Policies</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_ref.html" title="Policy Reference">
+<link rel="prev" href="discrete_quant_ref.html" title="Discrete Quantile Policies">
+<link rel="next" href="iteration_pol.html" title="Iteration Limits Policies">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="discrete_quant_ref.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="iteration_pol.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_ref.precision_pol"></a><a href="precision_pol.html" title="Precision Policies"> Precision
+ Policies</a>
+</h4></div></div></div>
+<p>
+ There are two equivalent policies that effect the <span class="emphasis"><em>working precision</em></span>
+ used to calculate results, these policies both default to 0 - meaning calculate
+ to the maximum precision available in the type being used - but can be
+ set to other values to cause lower levels of precision to be used.
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">policies</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">int</span> <span class="identifier">N</span><span class="special">&gt;</span>
+<span class="identifier">digits10</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">int</span> <span class="identifier">N</span><span class="special">&gt;</span>
+<span class="identifier">digits2</span><span class="special">;</span>
+
+<span class="special">}}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ As you would expect, <span class="emphasis"><em>digits10</em></span> specifies the number
+ of decimal digits to use, and <span class="emphasis"><em>digits2</em></span> the number of
+ binary digits. Internally, whichever is used, the precision is always converted
+ to <span class="emphasis"><em>binary digits</em></span>.
+ </p>
+<p>
+ These policies are specified at compile-time, because many of the special
+ functions use compile-time-dispatch to select which approximation to use
+ based on the precision requested and the numeric type being used.
+ </p>
+<p>
+ For example we could calculate <code class="computeroutput"><span class="identifier">tgamma</span></code>
+ to approximately 5 decimal digits using:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">digits10</span><span class="special">&lt;</span><span class="number">5</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">pol</span><span class="special">;</span>
+
+<span class="keyword">double</span> <span class="identifier">t</span> <span class="special">=</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="number">12</span><span class="special">,</span> <span class="identifier">pol</span><span class="special">());</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Or again using <span class="emphasis"><em>make_policy</em></span>:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+
+<span class="keyword">double</span> <span class="identifier">t</span> <span class="special">=</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="number">12</span><span class="special">,</span> <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">digits10</span><span class="special">&lt;</span><span class="number">5</span><span class="special">&gt;</span> <span class="special">&gt;());</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ And for a quantile of a distribution to approximately 25-bit precision:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">normal</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+
+<span class="keyword">double</span> <span class="identifier">q</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span>
+ <span class="identifier">normal_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">digits2</span><span class="special">&lt;</span><span class="number">25</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="special">&gt;(),</span>
+ <span class="number">0.05</span><span class="special">);</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="discrete_quant_ref.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="iteration_pol.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,60 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Policy Tutorial</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../policy.html" title="Policies">
+<link rel="prev" href="pol_overview.html" title="Policy Overview">
+<link rel="next" href="pol_tutorial/what_is_a_policy.html" title="So Just What is a Policy Anyway?">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="pol_overview.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../policy.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="pol_tutorial/what_is_a_policy.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.policy.pol_tutorial"></a> Policy Tutorial
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="pol_tutorial/what_is_a_policy.html">
+ So Just What is a Policy Anyway?</a></span></dt>
+<dt><span class="section"><a href="pol_tutorial/policy_tut_defaults.html">
+ Policies Have Sensible Defaults</a></span></dt>
+<dt><span class="section"><a href="pol_tutorial/policy_usage.html"> So
+ How are Policies Used Anyway?</a></span></dt>
+<dt><span class="section"><a href="pol_tutorial/changing_policy_defaults.html">
+ Changing the Policy Defaults</a></span></dt>
+<dt><span class="section"><a href="pol_tutorial/ad_hoc_dist_policies.html">
+ Setting Policies for Distributions on an Ad Hoc Basis</a></span></dt>
+<dt><span class="section"><a href="pol_tutorial/ad_hoc_sf_policies.html">
+ Changing the Policy on an Ad Hoc Basis for the Special Functions</a></span></dt>
+<dt><span class="section"><a href="pol_tutorial/namespace_policies.html">
+ Setting Policies at Namespace or Translation Unit Scope</a></span></dt>
+<dt><span class="section"><a href="pol_tutorial/user_def_err_pol.html">
+ Calling User Defined Error Handlers</a></span></dt>
+<dt><span class="section"><a href="pol_tutorial/understand_dis_quant.html">
+ Understanding Quantiles of Discrete Distributions</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="pol_overview.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../policy.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="pol_tutorial/what_is_a_policy.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/ad_hoc_dist_policies.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/ad_hoc_dist_policies.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,113 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Setting Policies for Distributions on an Ad Hoc Basis</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
+<link rel="prev" href="changing_policy_defaults.html" title="Changing the Policy Defaults">
+<link rel="next" href="ad_hoc_sf_policies.html" title="Changing the Policy on an Ad Hoc Basis for the Special Functions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="changing_policy_defaults.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ad_hoc_sf_policies.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_tutorial.ad_hoc_dist_policies"></a><a href="ad_hoc_dist_policies.html" title="Setting Policies for Distributions on an Ad Hoc Basis">
+ Setting Policies for Distributions on an Ad Hoc Basis</a>
+</h4></div></div></div>
+<p>
+ All of the statistical distributions in this library are class templates
+ that accept two template parameters, both with sensible defaults, for example:
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policy</span> <span class="special">=</span> <span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">&lt;&gt;</span> <span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">fisher_f_distribution</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">fisher_f_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">fisher_f</span><span class="special">;</span>
+
+<span class="special">}}</span>
+</pre>
+<p>
+ This policy gets used by all the accessor functions that accept a distribution
+ as an argument, and forwarded to all the functions called by these. So
+ if you use the shorthand-typedef for the distribution, then you get <code class="computeroutput"><span class="keyword">double</span></code> precision arithmetic and all the
+ default policies.
+ </p>
+<p>
+ However, say for example we wanted to evaluate the quantile of the binomial
+ distribution at float precision, without internal promotion to double,
+ and with the result rounded to the <span class="emphasis"><em>nearest</em></span> integer,
+ then here's how it can be done:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="comment">//
+</span><span class="comment">// Begin by defining a policy type, that gives the
+</span><span class="comment">// behaviour we want:
+</span><span class="comment">//
+</span><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span>
+ <span class="identifier">promote_float</span><span class="special">&lt;</span><span class="keyword">false</span><span class="special">&gt;,</span>
+ <span class="identifier">discrete_quantile</span><span class="special">&lt;</span><span class="identifier">integer_round_nearest</span><span class="special">&gt;</span>
+<span class="special">&gt;</span> <span class="identifier">mypolicy</span><span class="special">;</span>
+<span class="comment">//
+</span><span class="comment">// Then define a distribution that uses it:
+</span><span class="comment">//
+</span><span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">binomial_distribution</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">,</span> <span class="identifier">mypolicy</span><span class="special">&gt;</span> <span class="identifier">mybinom</span><span class="special">;</span>
+<span class="comment">//
+</span><span class="comment">// And now use it to get the quantile:
+</span><span class="comment">//
+</span><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"quantile is: "</span> <span class="special">&lt;&lt;</span>
+ <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">mybinom</span><span class="special">(</span><span class="number">200</span><span class="special">,</span> <span class="number">0.25</span><span class="special">),</span> <span class="number">0.05</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Which outputs:
+ </p>
+<pre class="programlisting">quantile is: 40</pre>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="changing_policy_defaults.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ad_hoc_sf_policies.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/ad_hoc_sf_policies.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/ad_hoc_sf_policies.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,181 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Changing the Policy on an Ad Hoc Basis for the Special Functions</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
+<link rel="prev" href="ad_hoc_dist_policies.html" title="Setting Policies for Distributions on an Ad Hoc Basis">
+<link rel="next" href="namespace_policies.html" title="Setting Policies at Namespace or Translation Unit Scope">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ad_hoc_dist_policies.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="namespace_policies.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_tutorial.ad_hoc_sf_policies"></a><a href="ad_hoc_sf_policies.html" title="Changing the Policy on an Ad Hoc Basis for the Special Functions">
+ Changing the Policy on an Ad Hoc Basis for the Special Functions</a>
+</h4></div></div></div>
+<p>
+ All of the special functions in this library come in two overloaded forms,
+ one with a final "policy" parameter, and one without. For example:
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policy</span><span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Policy</span><span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">&gt;</span>
+<span class="identifier">RealType</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">RealType</span><span class="special">);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ Normally, the second version is just a forwarding wrapper to the first
+ like this:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">&gt;</span>
+<span class="keyword">inline</span> <span class="identifier">RealType</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">x</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">return</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">&lt;&gt;());</span>
+<span class="special">}</span>
+</pre>
+<p>
+ So calling a special function with a specific policy is just a matter of
+ defining the policy type to use and passing it as the final parameter.
+ For example, suppose we want <code class="computeroutput"><span class="identifier">tgamma</span></code>
+ to behave in a C-compatible fashion and set <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code> when an error occurs, and never
+ throw an exception:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="comment">//
+</span><span class="comment">// Define the policy to use:
+</span><span class="comment">//
+</span><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span>
+ <span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span>
+ <span class="identifier">pole_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span>
+ <span class="identifier">overflow_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span>
+ <span class="identifier">evaluation_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;</span>
+<span class="special">&gt;</span> <span class="identifier">c_policy</span><span class="special">;</span>
+<span class="comment">//
+</span><span class="comment">// Now use the policy when calling tgamma:
+</span><span class="comment">//
+</span><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of tgamma(30000) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="number">30000</span><span class="special">,</span> <span class="identifier">c_policy</span><span class="special">())</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"errno = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">errno</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of tgamma(-10) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(-</span><span class="number">10</span><span class="special">,</span> <span class="identifier">c_policy</span><span class="special">())</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"errno = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">errno</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ which outputs:
+ </p>
+<pre class="programlisting">Result of tgamma(30000) is: 1.#INF
+errno = 34
+Result of tgamma(-10) is: 1.#QNAN
+errno = 33
+</pre>
+<p>
+ Alternatively, for ad hoc use, we can use the <code class="computeroutput"><span class="identifier">make_policy</span></code>
+ helper function to create a policy for us: this usage is more verbose,
+ so is probably only preferred when a policy is going to be used once only:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+ <span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of tgamma(30000) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span>
+ <span class="number">30000</span><span class="special">,</span>
+ <span class="identifier">make_policy</span><span class="special">(</span>
+ <span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;(),</span>
+ <span class="identifier">pole_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;(),</span>
+ <span class="identifier">overflow_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;(),</span>
+ <span class="identifier">evaluation_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;()</span>
+ <span class="special">)</span>
+ <span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="comment">// Check errno was set:
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"errno = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">errno</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="comment">// and again with evaluation at a pole:
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of tgamma(-10) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span>
+ <span class="special">-</span><span class="number">10</span><span class="special">,</span>
+ <span class="identifier">make_policy</span><span class="special">(</span>
+ <span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;(),</span>
+ <span class="identifier">pole_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;(),</span>
+ <span class="identifier">overflow_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;(),</span>
+ <span class="identifier">evaluation_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;()</span>
+ <span class="special">)</span>
+ <span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="comment">// Check errno was set:
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"errno = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">errno</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ad_hoc_dist_policies.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="namespace_policies.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/changing_policy_defaults.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/changing_policy_defaults.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,343 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Changing the Policy Defaults</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
+<link rel="prev" href="policy_usage.html" title="So How are Policies Used Anyway?">
+<link rel="next" href="ad_hoc_dist_policies.html" title="Setting Policies for Distributions on an Ad Hoc Basis">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="policy_usage.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ad_hoc_dist_policies.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_tutorial.changing_policy_defaults"></a><a href="changing_policy_defaults.html" title="Changing the Policy Defaults">
+ Changing the Policy Defaults</a>
+</h4></div></div></div>
+<p>
+ The default policies used by the library are changed by the usual configuration
+ macro method.
+ </p>
+<p>
+ For example, passing <code class="computeroutput"><span class="special">-</span><span class="identifier">DBOOST_MATH_DOMAIN_ERROR_POLICY</span><span class="special">=</span><span class="identifier">errno_on_error</span></code>
+ to your compiler will cause domain errors to set <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code> and return a NaN rather than the
+ usual default behaviour of throwing a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code>
+ exception.
+ </p>
+<div class="tip"><table border="0" summary="Tip">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../../doc/html/images/tip.png"></td>
+<th align="left">Tip</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ For Microsoft Visual Studio,you can add to the Project Property Page,
+ C/C++, Preprocessor, Preprocessor definitions like:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">BOOST_MATH_ASSERT_UNDEFINED_POLICY</span><span class="special">=</span><span class="number">0</span>
+<span class="identifier">BOOST_MATH_OVERFLOW_ERROR_POLICY</span><span class="special">=</span><span class="identifier">errno_on_error</span></pre>
+<p>
+ </p>
+<p>
+ This may be helpful to avoid complications with pre-compiled headers
+ that may mean that the equivalent definitions in source code:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_ASSERT_UNDEFINED_POLICY</span> <span class="keyword">false</span>
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_OVERFLOW_ERROR_POLICY</span> <span class="identifier">errno_on_error</span></pre>
+<p>
+ </p>
+<p>
+ may be ignored.
+ </p>
+<p>
+ The compiler command line shows:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="special">/</span><span class="identifier">D</span> <span class="string">"BOOST_MATH_ASSERT_UNDEFINED_POLICY=0"</span>
+<span class="special">/</span><span class="identifier">D</span> <span class="string">"BOOST_MATH_OVERFLOW_ERROR_POLICY=errno_on_error"</span></pre>
+<p>
+ </p>
+</td></tr>
+</table></div>
+<p>
+ There is however a very important caveat to this:
+ </p>
+<div class="important"><table border="0" summary="Important">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../../../../doc/html/images/important.png"></td>
+<th align="left">Important</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ <span class="bold"><strong><span class="emphasis"><em>Default policies changed by setting configuration
+ macros must be changed uniformly in every translation unit in the program.</em></span></strong></span>
+ </p>
+<p>
+ Failure to follow this rule may result in violations of the "One
+ Definition Rule (ODR)" and result in unpredictable program behaviour.
+ </p>
+</td></tr>
+</table></div>
+<p>
+ That means there are only two safe ways to use these macros:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Edit them in boost/math/tools/user.hpp,
+ so that the defaults are set on an installation-wide basis. Unfortunately
+ this may not be convenient if you are using a pre-installed Boost distribution
+ (on Linux for example).
+ </li>
+<li>
+ Set the defines in your project's Makefile or build environment, so that
+ they are set uniformly across all translation units.
+ </li>
+</ul></div>
+<p>
+ What you should <span class="bold"><strong>not</strong></span> do is:
+ </p>
+<div class="itemizedlist"><ul type="disc"><li>
+ Set the defines in the source file using <code class="computeroutput"><span class="preprocessor">#define</span></code>
+ as doing so almost certainly will break your program, unless you're absolutely
+ certain that the program is restricted to a single translation unit.
+ </li></ul></div>
+<p>
+ And, yes, you will find examples in our test programs where we break this
+ rule: but only because we know there will always be a single translation
+ unit only: <span class="emphasis"><em>don't say that you weren't warned!</em></span>
+ </p>
+<p>
+ </p>
+<p>
+ The following example demonstrates the effect of setting the macro BOOST_MATH_DOMAIN_ERROR_POLICY
+ when an invalid argument is encountered. For the purposes of this example,
+ we'll pass a negative degrees of freedom parameter to the student's t
+ distribution.
+ </p>
+<p>
+ </p>
+<p>
+ Since we know that this is a single file program we could just add:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">ignore_error</span>
+</pre>
+<p>
+ </p>
+<p>
+ to the top of the source file to change the default policy to one that
+ simply returns a NaN when a domain error occurs. Alternatively we could
+ use:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">errno_on_error</span>
+</pre>
+<p>
+ </p>
+<p>
+ To ensure the <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
+ is set when a domain error occurs as well as returning a NaN.
+ </p>
+<p>
+ </p>
+<p>
+ This is safe provided the program consists of a single translation unit
+ <span class="emphasis"><em>and</em></span> we place the define <span class="emphasis"><em>before</em></span>
+ any #includes. Note that should we add the define after the includes
+ then it will have no effect! A warning such as:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">warning C4005: 'BOOST_MATH_OVERFLOW_ERROR_POLICY' : macro redefinition</pre>
+<p>
+ </p>
+<p>
+ is a certain sign that it will <span class="emphasis"><em>not</em></span> have the desired
+ effect.
+ </p>
+<p>
+ </p>
+<p>
+ We'll begin our sample program with the needed includes:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="comment">// Boost
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">students_t</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">students_t</span><span class="special">;</span> <span class="comment">// Probability of students_t(df, t).
+</span>
+<span class="comment">// std
+</span><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">stdexcept</span><span class="special">&gt;</span>
+ <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Next we'll define the program's main() to call the student's t distribution
+ with an invalid degrees of freedom parameter, the program is set up to
+ handle either an exception or a NaN:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Example error handling using Student's t function. "</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"BOOST_MATH_DOMAIN_ERROR_POLICY is set to: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">BOOST_STRINGIZE</span><span class="special">(</span><span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+
+ <span class="keyword">double</span> <span class="identifier">degrees_of_freedom</span> <span class="special">=</span> <span class="special">-</span><span class="number">1</span><span class="special">;</span> <span class="comment">// A bad argument!
+</span> <span class="keyword">double</span> <span class="identifier">t</span> <span class="special">=</span> <span class="number">10</span><span class="special">;</span>
+
+ <span class="keyword">try</span>
+ <span class="special">{</span>
+ <span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
+ <span class="identifier">students_t</span> <span class="identifier">dist</span><span class="special">(</span><span class="identifier">degrees_of_freedom</span><span class="special">);</span> <span class="comment">// exception is thrown here if enabled
+</span> <span class="keyword">double</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">t</span><span class="special">);</span>
+ <span class="comment">// test for error reported by other means:
+</span> <span class="keyword">if</span><span class="special">((</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">isnan</span><span class="special">)(</span><span class="identifier">p</span><span class="special">))</span>
+ <span class="special">{</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"cdf returned a NaN!"</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"errno is set to: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">errno</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="keyword">else</span>
+ <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Probability of Student's t is "</span> <span class="special">&lt;&lt;</span> <span class="identifier">p</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
+ <span class="special">}</span>
+ <span class="keyword">catch</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span><span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span>
+ <span class="string">"\n"</span><span class="string">"Message from thrown exception was:\n "</span> <span class="special">&lt;&lt;</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="special">}</span>
+
+ <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
+<span class="special">}</span> <span class="comment">// int main()</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Here's what the program output looks like with a default build (one that
+ does throw exceptions):
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Example error handling using Student's t function.
+BOOST_MATH_DOMAIN_ERROR_POLICY is set to: throw_on_error
+
+Message from thrown exception was:
+ Error in function boost::math::students_t_distribution&lt;double&gt;::students_t_distribution:
+ Degrees of freedom argument is -1, but must be &gt; 0 !
+</pre>
+<p>
+ </p>
+<p>
+ Alternatively let's build with:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">ignore_error</span>
+</pre>
+<p>
+ </p>
+<p>
+ Now the program output is:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Example error handling using Student's t function.
+BOOST_MATH_DOMAIN_ERROR_POLICY is set to: ignore_error
+cdf returned a NaN!
+errno is set to: 0
+</pre>
+<p>
+ </p>
+<p>
+ And finally let's build with:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">errno_on_error</span>
+</pre>
+<p>
+ </p>
+<p>
+ Which gives the output:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Example error handling using Student's t function.
+BOOST_MATH_DOMAIN_ERROR_POLICY is set to: errno_on_error
+cdf returned a NaN!
+errno is set to: 33
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="policy_usage.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ad_hoc_dist_policies.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/namespace_policies.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/namespace_policies.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,501 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Setting Policies at Namespace or Translation Unit Scope</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
+<link rel="prev" href="ad_hoc_sf_policies.html" title="Changing the Policy on an Ad Hoc Basis for the Special Functions">
+<link rel="next" href="user_def_err_pol.html" title="Calling User Defined Error Handlers">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ad_hoc_sf_policies.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="user_def_err_pol.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_tutorial.namespace_policies"></a><a href="namespace_policies.html" title="Setting Policies at Namespace or Translation Unit Scope">
+ Setting Policies at Namespace or Translation Unit Scope</a>
+</h4></div></div></div>
+<p>
+ Sometimes what you want to do is just change a set of policies within the
+ current scope: the one thing you should not do in this situation is use
+ the configuration macros, as this can lead to "One Definition Rule"
+ violations. Instead this library provides a pair of macros especially for
+ this purpose.
+ </p>
+<p>
+ Let's consider the special functions first: we can declare a set of forwarding
+ functions that all use a specific policy using the macro BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS(<span class="emphasis"><em>Policy</em></span>).
+ This macro should be used either inside a unique namespace set aside for
+ the purpose, or an unnamed namespace if you just want the functions visible
+ in global scope for the current file only.
+ </p>
+<p>
+ </p>
+<p>
+ Suppose we want <code class="computeroutput"><span class="identifier">C</span><span class="special">::</span><span class="identifier">foo</span><span class="special">()</span></code>
+ to behave in a C-compatible way and set <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code> on error rather than throwing
+ any exceptions.
+ </p>
+<p>
+ </p>
+<p>
+ We'll begin by including the needed header:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Open up the "C" namespace that we'll use for our functions,
+ and define the policy type we want: in this case one that sets ::errno
+ rather than throwing exceptions. Any policies we don't specify here will
+ inherit the defaults:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">C</span><span class="special">{</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span>
+ <span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span>
+ <span class="identifier">pole_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span>
+ <span class="identifier">overflow_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span>
+ <span class="identifier">evaluation_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;</span>
+<span class="special">&gt;</span> <span class="identifier">c_policy</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ All we need do now is invoke the BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS
+ macro passing our policy type as the single argument:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS</span><span class="special">(</span><span class="identifier">c_policy</span><span class="special">)</span>
+
+<span class="special">}</span> <span class="comment">// close namespace C</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ We now have a set of forwarding functions defined in namespace C that
+ all look something like this:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">&gt;</span>
+<span class="keyword">inline</span> <span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">::</span><span class="identifier">promote_args</span><span class="special">&lt;</span><span class="identifier">RT</span><span class="special">&gt;::</span><span class="identifier">type</span>
+ <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">RT</span> <span class="identifier">z</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">c_policy</span><span class="special">());</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ So that when we call <code class="computeroutput"><span class="identifier">C</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span></code> we really end up calling <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">C</span><span class="special">::</span><span class="identifier">c_policy</span><span class="special">())</span></code>:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of tgamma(30000) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">C</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="number">30000</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"errno = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">errno</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of tgamma(-10) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">C</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(-</span><span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"errno = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">errno</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Which outputs:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Result of C::tgamma(30000) is: 1.#INF
+errno = 34
+Result of C::tgamma(-10) is: 1.#QNAN
+errno = 33
+</pre>
+<p>
+ </p>
+<p>
+ This mechanism is particularly useful when we want to define a project-wide
+ policy, and don't want to modify the Boost source or set - possibly fragile
+ and easy to forget - project wide build macros.
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ The same mechanism works well at file scope as well, by using an unnamed
+ namespace, we can ensure that these declarations don't conflict with any
+ alternate policies present in other translation units:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">namespace</span> <span class="special">{</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span>
+ <span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span>
+ <span class="identifier">pole_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span>
+ <span class="identifier">overflow_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span>
+ <span class="identifier">evaluation_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;</span>
+<span class="special">&gt;</span> <span class="identifier">c_policy</span><span class="special">;</span>
+
+<span class="identifier">BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS</span><span class="special">(</span><span class="identifier">c_policy</span><span class="special">)</span>
+
+<span class="special">}</span> <span class="comment">// close unnamed namespace
+</span>
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of tgamma(30000) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="number">30000</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"errno = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">errno</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of tgamma(-10) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">tgamma</span><span class="special">(-</span><span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"errno = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">errno</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Handling the statistical distributions is very similar except that now
+ the macro BOOST_MATH_DECLARE_DISTRIBUTIONS accepts two parameters: the
+ floating point type to use, and the policy type to apply. For example:
+ </p>
+<pre class="programlisting">
+<span class="identifier">BOOST_MATH_DECLARE_DISTRIBUTIONS</span><span class="special">(</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">mypolicy</span><span class="special">)</span>
+</pre>
+<p>
+ Results a set of typedefs being defined like this:
+ </p>
+<pre class="programlisting">
+<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">normal_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">mypolicy</span><span class="special">&gt;</span> <span class="identifier">normal</span><span class="special">;</span>
+</pre>
+<p>
+ The name of each typedef is the same as the name of the distribution class
+ template, but without the "_distribution" suffix.
+ </p>
+<p>
+ </p>
+<p>
+ Suppose we want a set of distributions to behave as follows:
+ </p>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Return infinity on overflow, rather than throwing an exception.
+ </li>
+<li>
+ Don't perform any promotion from double to long double internally.
+ </li>
+<li>
+ Return the closest integer result from the quantiles of discrete distributions.
+ </li>
+</ul></div>
+<p>
+ </p>
+<p>
+ We'll begin by including the needed header:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Open up an appropriate namespace for our distributions, and define the
+ policy type we want. Any policies we don't specify here will inherit
+ the defaults:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">my_distributions</span><span class="special">{</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span>
+ <span class="comment">// return infinity and set errno rather than throw:
+</span> <span class="identifier">overflow_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span>
+ <span class="comment">// Don't promote double -&gt; long double internally:
+</span> <span class="identifier">promote_double</span><span class="special">&lt;</span><span class="keyword">false</span><span class="special">&gt;,</span>
+ <span class="comment">// Return the closest integer result for discrete quantiles:
+</span> <span class="identifier">discrete_quantile</span><span class="special">&lt;</span><span class="identifier">integer_round_nearest</span><span class="special">&gt;</span>
+<span class="special">&gt;</span> <span class="identifier">my_policy</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ All we need do now is invoke the BOOST_MATH_DECLARE_DISTRIBUTIONS macro
+ passing the floating point and policy types as arguments:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">BOOST_MATH_DECLARE_DISTRIBUTIONS</span><span class="special">(</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">)</span>
+
+<span class="special">}</span> <span class="comment">// close namespace my_namespace</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ We now have a set of typedefs defined in namespace my_namespace that
+ all look something like this:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">normal_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">&gt;</span> <span class="identifier">normal</span><span class="special">;</span>
+<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">cauchy_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">&gt;</span> <span class="identifier">cauchy</span><span class="special">;</span>
+<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">gamma_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">&gt;</span> <span class="identifier">gamma</span><span class="special">;</span>
+<span class="comment">// etc
+</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ So that when we use my_namespace::normal we really end up using <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">normal_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">&gt;</span></code>:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="comment">//
+</span> <span class="comment">// Start with something we know will overflow:
+</span> <span class="comment">//
+</span> <span class="identifier">my_distributions</span><span class="special">::</span><span class="identifier">normal</span> <span class="identifier">norm</span><span class="special">(</span><span class="number">10</span><span class="special">,</span> <span class="number">2</span><span class="special">);</span>
+ <span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of quantile(norm, 0) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">norm</span><span class="special">,</span> <span class="number">0</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"errno = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">errno</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of quantile(norm, 1) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">norm</span><span class="special">,</span> <span class="number">1</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"errno = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">errno</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="comment">//
+</span> <span class="comment">// Now try a discrete distribution:
+</span> <span class="comment">//
+</span> <span class="identifier">my_distributions</span><span class="special">::</span><span class="identifier">binomial</span> <span class="identifier">binom</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of quantile(binom, 0.05) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom</span><span class="special">,</span> <span class="number">0.05</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of quantile(complement(binom, 0.05)) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">binom</span><span class="special">,</span> <span class="number">0.05</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Which outputs:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Result of quantile(norm, 0) is: -1.#INF
+errno = 34
+Result of quantile(norm, 1) is: 1.#INF
+errno = 34
+Result of quantile(binom, 0.05) is: 1
+Result of quantile(complement(binom, 0.05)) is: 8
+</pre>
+<p>
+ </p>
+<p>
+ This mechanism is particularly useful when we want to define a project-wide
+ policy, and don't want to modify the Boost source or set - possibly fragile
+ and easy to forget - project wide build macros.
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ There is an important limitation to note: you can not use the macros
+ BOOST_MATH_DECLARE_DISTRIBUTIONS and BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS
+ <span class="emphasis"><em>in the same namespace</em></span>, as doing so creates ambiguities
+ between functions and distributions of the same name.
+ </p></td></tr>
+</table></div>
+<p>
+ As before, the same mechanism works well at file scope as well: by using
+ an unnamed namespace, we can ensure that these declarations don't conflict
+ with any alternate policies present in other translation units:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">namespace</span> <span class="special">{</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span>
+ <span class="comment">// return infinity and set errno rather than throw:
+</span> <span class="identifier">overflow_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span>
+ <span class="comment">// Don't promote double -&gt; long double internally:
+</span> <span class="identifier">promote_double</span><span class="special">&lt;</span><span class="keyword">false</span><span class="special">&gt;,</span>
+ <span class="comment">// Return the closest integer result for discrete quantiles:
+</span> <span class="identifier">discrete_quantile</span><span class="special">&lt;</span><span class="identifier">integer_round_nearest</span><span class="special">&gt;</span>
+<span class="special">&gt;</span> <span class="identifier">my_policy</span><span class="special">;</span>
+
+<span class="identifier">BOOST_MATH_DECLARE_DISTRIBUTIONS</span><span class="special">(</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">)</span>
+
+<span class="special">}</span> <span class="comment">// close namespace my_namespace
+</span>
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="comment">//
+</span> <span class="comment">// Start with something we know will overflow:
+</span> <span class="comment">//
+</span> <span class="identifier">normal</span> <span class="identifier">norm</span><span class="special">(</span><span class="number">10</span><span class="special">,</span> <span class="number">2</span><span class="special">);</span>
+ <span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of quantile(norm, 0) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">norm</span><span class="special">,</span> <span class="number">0</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"errno = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">errno</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of quantile(norm, 1) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">norm</span><span class="special">,</span> <span class="number">1</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"errno = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">errno</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="comment">//
+</span> <span class="comment">// Now try a discrete distribution:
+</span> <span class="comment">//
+</span> <span class="identifier">binomial</span> <span class="identifier">binom</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of quantile(binom, 0.05) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom</span><span class="special">,</span> <span class="number">0.05</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of quantile(complement(binom, 0.05)) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">binom</span><span class="special">,</span> <span class="number">0.05</span><span class="special">))</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span>
+
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ad_hoc_sf_policies.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="user_def_err_pol.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/policy_tut_defaults.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/policy_tut_defaults.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,126 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Policies Have Sensible Defaults</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
+<link rel="prev" href="what_is_a_policy.html" title="So Just What is a Policy Anyway?">
+<link rel="next" href="policy_usage.html" title="So How are Policies Used Anyway?">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="what_is_a_policy.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="policy_usage.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_tutorial.policy_tut_defaults"></a><a href="policy_tut_defaults.html" title="Policies Have Sensible Defaults">
+ Policies Have Sensible Defaults</a>
+</h4></div></div></div>
+<p>
+ Most of the time you can just ignore the policy framework, the defaults
+ for the various policies are as follows, if these work OK for you then
+ you can stop reading now!
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">Domain Error</span></dt>
+<dd><p>
+ Throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code> exception.
+ </p></dd>
+<dt><span class="term">Pole Error</span></dt>
+<dd><p>
+ Occurs when a function is evaluated at a pole: throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code> exception.
+ </p></dd>
+<dt><span class="term">Overflow Error</span></dt>
+<dd><p>
+ Throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">overflow_error</span></code> exception.
+ </p></dd>
+<dt><span class="term">Underflow</span></dt>
+<dd><p>
+ Ignores the underflow, and returns zero.
+ </p></dd>
+<dt><span class="term">Denormalised Result</span></dt>
+<dd><p>
+ Ignores the fact that the result is denormalised, and returns it.
+ </p></dd>
+<dt><span class="term">Internal Evaluation Error</span></dt>
+<dd><p>
+ Throws a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">evaluation_error</span></code> exception.
+ </p></dd>
+<dt><span class="term">Promotion of float to double</span></dt>
+<dd><p>
+ Does occur by default - gives full float precision results.
+ </p></dd>
+<dt><span class="term">Promotion of double to long double</span></dt>
+<dd><p>
+ Does occur by default if long double offers more precision than double.
+ </p></dd>
+<dt><span class="term">Precision of Approximation Used</span></dt>
+<dd><p>
+ By default uses an approximation that will result in the lowest level
+ of error for the type of the result.
+ </p></dd>
+<dt><span class="term">Behaviour of Discrete Quantiles</span></dt>
+<dd>
+<p>
+ The quantile function will by default return an integer result that
+ has been <span class="emphasis"><em>rounded outwards</em></span>. 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 <span class="emphasis"><em>at least</em></span> the requested coverage will be present
+ in the central region, and <span class="emphasis"><em>no more than</em></span> the requested
+ coverage will be present in the tails.
+ </p>
+<p>
+ This behaviour can be changed so that the quantile functions are rounded
+ differently, or even return a real-valued result using Policies.
+ It is strongly recommended that you read the tutorial <a href="understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">Understanding
+ Quantiles of Discrete Distributions</a> before using the quantile
+ function on a discrete distribution. The <a href="../pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">reference
+ docs</a> describe how to change the rounding policy for these distributions.
+ </p>
+</dd>
+</dl>
+</div>
+<p>
+ What's more, if you define your own policy type, then it automatically
+ inherits the defaults for any policies not explicitly set, so given:
+ </p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+<span class="comment">//
+</span><span class="comment">// Define a policy that sets ::errno on overflow, and does
+</span><span class="comment">// not promote double to long double internally:
+</span><span class="comment">//
+</span><span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span> <span class="identifier">promote_double</span><span class="special">&lt;</span><span class="keyword">false</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">mypolicy</span><span class="special">;</span>
+</pre>
+<p>
+ then <code class="computeroutput"><span class="identifier">mypolicy</span></code> defines a
+ policy where only the overflow error handling and <code class="computeroutput"><span class="keyword">double</span></code>-promotion
+ policies differ from the defaults.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="what_is_a_policy.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="policy_usage.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/policy_usage.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/policy_usage.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,67 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>So How are Policies Used Anyway?</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
+<link rel="prev" href="policy_tut_defaults.html" title="Policies Have Sensible Defaults">
+<link rel="next" href="changing_policy_defaults.html" title="Changing the Policy Defaults">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="policy_tut_defaults.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="changing_policy_defaults.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_tutorial.policy_usage"></a><a href="policy_usage.html" title="So How are Policies Used Anyway?"> So
+ How are Policies Used Anyway?</a>
+</h4></div></div></div>
+<p>
+ The details follow later, but basically policies can be set by either:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Defining some macros that change the default behaviour: <span class="bold"><strong>this
+ is the recommended method for setting installation-wide policies</strong></span>.
+ </li>
+<li>
+ By instantiating a distribution object with an explicit policy: this
+ is mainly reserved for ad hoc policy changes.
+ </li>
+<li>
+ By passing a policy to a special function as an optional final argument:
+ this is mainly reserved for ad hoc policy changes.
+ </li>
+<li>
+ By using some helper macros to define a set of functions or distributions
+ in the current namespace that use a specific policy: <span class="bold"><strong>this
+ is the recommended method for setting policies on a project- or translation-unit-wide
+ basis</strong></span>.
+ </li>
+</ul></div>
+<p>
+ The following sections introduce these methods in more detail.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="policy_tut_defaults.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="changing_policy_defaults.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/understand_dis_quant.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/understand_dis_quant.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,445 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Understanding Quantiles of Discrete Distributions</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
+<link rel="prev" href="user_def_err_pol.html" title="Calling User Defined Error Handlers">
+<link rel="next" href="../pol_ref.html" title="Policy Reference">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="user_def_err_pol.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_tutorial.understand_dis_quant"></a><a href="understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">
+ Understanding Quantiles of Discrete Distributions</a>
+</h4></div></div></div>
+<p>
+ Discrete distributions present us with a problem when calculating the quantile:
+ we are starting from a continuous real-valued variable - the probability
+ - but the result (the value of the random variable) should really be discrete.
+ </p>
+<p>
+ Consider for example a Binomial distribution, with a sample size of 50,
+ and a success fraction of 0.5. There are a variety of ways we can plot
+ a discrete distribution, but if we plot the PDF as a step-function then
+ it looks something like this:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/binomial_pdf.png" alt="binomial_pdf"></span>
+ </p>
+<p>
+ Now lets suppose that the user asks for a the quantile that corresponds
+ to a probability of 0.05, if we zoom in on the CDF for that region here's
+ what we see:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/binomial_quantile_1.png" alt="binomial_quantile_1"></span>
+ </p>
+<p>
+ As can be seen there is no random variable that corresponds to a probability
+ of exactly 0.05, so we're left with two choices as shown in the figure:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ We could round the result down to 18.
+ </li>
+<li>
+ We could round the result up to 19.
+ </li>
+</ul></div>
+<p>
+ In fact there's actually a third choice as well: we could "pretend"
+ that the distribution was continuous and return a real valued result: in
+ this case we would calculate a result of approximately 18.701 (this accurately
+ reflects the fact that the result is nearer to 19 than 18).
+ </p>
+<p>
+ By using policies we can offer any of the above as options, but that still
+ leaves the question: <span class="emphasis"><em>What is actually the right thing to do?</em></span>
+ </p>
+<p>
+ And in particular: <span class="emphasis"><em>What policy should we use by default?</em></span>
+ </p>
+<p>
+ In coming to an answer we should realise that:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Calculating an integer result is often much faster than calculating a
+ real-valued result: in fact in our tests it was up to 20 times faster.
+ </li>
+<li>
+ Normally people calculate quantiles so that they can perform a test of
+ some kind: <span class="emphasis"><em>"If the random variable is less than N then
+ we can reject our null-hypothesis with 90% confidence."</em></span>
+</li>
+</ul></div>
+<p>
+ So there is a genuine benefit to calculating an integer result as well
+ as it being "the right thing to do" from a philosophical point
+ of view. What's more if someone asks for a quantile at 0.05, then we can
+ normally assume that they are asking for <span class="emphasis"><em><span class="bold"><strong>at
+ least</strong></span> 95% of the probability to the right of the value chosen,
+ and <span class="bold"><strong>no more than</strong></span> 5% of the probability
+ to the left of the value chosen.</em></span>
+ </p>
+<p>
+ In the above binomial example we would therefore round the result down
+ to 18.
+ </p>
+<p>
+ The converse applies to upper-quantiles: If the probability is greater
+ than 0.5 we would want to round the quantile up, <span class="emphasis"><em>so that <span class="bold"><strong>at least</strong></span> the requested probability is to the left
+ of the value returned, and <span class="bold"><strong>no more than</strong></span>
+ 1 - the requested probability is to the right of the value returned.</em></span>
+ </p>
+<p>
+ Likewise for two-sided intervals, we would round lower quantiles down,
+ and upper quantiles up. This ensures that we have <span class="emphasis"><em>at least the
+ requested probability in the central region</em></span> and <span class="emphasis"><em>no
+ more than 1 minus the requested probability in the tail areas.</em></span>
+ </p>
+<p>
+ For example, taking our 50 sample binomial distribution with a success
+ fraction of 0.5, if we wanted a two sided 90% confidence interval, then
+ we would ask for the 0.05 and 0.95 quantiles with the results <span class="emphasis"><em>rounded
+ outwards</em></span> so that <span class="emphasis"><em>at least 90% of the probability</em></span>
+ is in the central area:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/binomial_pdf_3.png" alt="binomial_pdf_3"></span>
+ </p>
+<p>
+ So far so good, but there is in fact a trap waiting for the unwary here:
+ </p>
+<pre class="programlisting">
+<span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.05</span><span class="special">);</span>
+</pre>
+<p>
+ returns 18 as the result, which is what we would expect from the graph
+ above, and indeed there is no x greater than 18 for which:
+ </p>
+<pre class="programlisting">
+<span class="identifier">cdf</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">&lt;=</span> <span class="number">0.05</span><span class="special">;</span>
+</pre>
+<p>
+ However:
+ </p>
+<pre class="programlisting">
+<span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.95</span><span class="special">);</span>
+</pre>
+<p>
+ returns 31, and indeed while there is no x less than 31 for which:
+ </p>
+<pre class="programlisting">
+<span class="identifier">cdf</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">&gt;=</span> <span class="number">0.95</span><span class="special">;</span>
+</pre>
+<p>
+ We might naively expect that for this symmetrical distribution the result
+ would be 32 (since 32 = 50 - 18), but we need to remember that the cdf
+ of the binomial is <span class="emphasis"><em>inclusive</em></span> of the random variable.
+ So while the left tail area <span class="emphasis"><em>includes</em></span> the quantile
+ returned, the right tail area always excludes an upper quantile value:
+ since that "belongs" to the central area.
+ </p>
+<p>
+ Look at the graph above to see what's going on here: the lower quantile
+ of 18 belongs to the left tail, so any value &lt;= 18 is in the left tail.
+ The upper quantile of 31 on the other hand belongs to the central area,
+ so the tail area actually starts at 32, so any value &gt; 31 is in the
+ right tail.
+ </p>
+<p>
+ Therefore if U and L are the upper and lower quantiles respectively, then
+ a random variable X is in the tail area - where we would reject the null
+ hypothesis if:
+ </p>
+<pre class="programlisting">
+<span class="identifier">X</span> <span class="special">&lt;=</span> <span class="identifier">L</span> <span class="special">||</span> <span class="identifier">X</span> <span class="special">&gt;</span> <span class="identifier">U</span>
+</pre>
+<p>
+ And the a variable X is inside the central region if:
+ </p>
+<pre class="programlisting">
+<span class="identifier">L</span> <span class="special">&lt;</span> <span class="identifier">X</span> <span class="special">&lt;=</span> <span class="identifier">U</span>
+</pre>
+<p>
+ The moral here is to <span class="emphasis"><em>always be very careful with your comparisons
+ when dealing with a discrete distribution</em></span>, and if in doubt,
+ <span class="emphasis"><em>base your comparisons on CDF's instead</em></span>.
+ </p>
+<a name="math_toolkit.policy.pol_tutorial.understand_dis_quant.other_rounding_policies_are_available"></a><h6>
+<a name="id757520"></a>
+ <a href="understand_dis_quant.html#math_toolkit.policy.pol_tutorial.understand_dis_quant.other_rounding_policies_are_available">Other
+ Rounding Policies are Available</a>
+ </h6>
+<p>
+ As you would expect from a section on policies, you won't be surprised
+ to know that other rounding options are available:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">integer_round_outwards</span></dt>
+<dd>
+<p>
+ This is the default policy as described above: lower quantiles are
+ rounded down (probability &lt; 0.5), and upper quantiles (probability
+ &gt; 0.5) are rounded up.
+ </p>
+<p>
+ This gives <span class="emphasis"><em>no more than</em></span> the requested probability
+ in the tails, and <span class="emphasis"><em>at least</em></span> the requested probability
+ in the central area.
+ </p>
+</dd>
+<dt><span class="term">integer_round_inwards</span></dt>
+<dd>
+<p>
+ This is the exact opposite of the default policy: lower quantiles are
+ rounded up (probability &lt; 0.5), and upper quantiles (probability
+ &gt; 0.5) are rounded down.
+ </p>
+<p>
+ This gives <span class="emphasis"><em>at least</em></span> the requested probability
+ in the tails, and <span class="emphasis"><em>no more than</em></span> the requested probability
+ in the central area.
+ </p>
+</dd>
+<dt><span class="term">integer_round_down</span></dt>
+<dd><p>
+ This policy will always round the result down no matter whether it
+ is an upper or lower quantile
+ </p></dd>
+<dt><span class="term">integer_round_up</span></dt>
+<dd><p>
+ This policy will always round the result up no matter whether it is
+ an upper or lower quantile
+ </p></dd>
+<dt><span class="term">integer_round_nearest</span></dt>
+<dd><p>
+ This policy will always round the result to the nearest integer no
+ matter whether it is an upper or lower quantile
+ </p></dd>
+<dt><span class="term">real</span></dt>
+<dd><p>
+ This policy will return a real valued result for the quantile of a
+ discrete distribution: this is generally much slower than finding an
+ integer result but does allow for more sophisticated rounding policies.
+ </p></dd>
+</dl>
+</div>
+<p>
+ </p>
+<p>
+ To understand how the rounding policies for the discrete distributions
+ can be used, we'll use the 50-sample binomial distribution with a success
+ fraction of 0.5 once again, and calculate all the possible quantiles
+ at 0.05 and 0.95.
+ </p>
+<p>
+ </p>
+<p>
+ Begin by including the needed headers:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Next we'll bring the needed declarations into scope, and define distribution
+ types for all the available rounding policies:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">binomial_distribution</span><span class="special">&lt;</span>
+ <span class="keyword">double</span><span class="special">,</span>
+ <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">discrete_quantile</span><span class="special">&lt;</span><span class="identifier">integer_round_outwards</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="special">&gt;</span>
+ <span class="identifier">binom_round_outwards</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">binomial_distribution</span><span class="special">&lt;</span>
+ <span class="keyword">double</span><span class="special">,</span>
+ <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">discrete_quantile</span><span class="special">&lt;</span><span class="identifier">integer_round_inwards</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="special">&gt;</span>
+ <span class="identifier">binom_round_inwards</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">binomial_distribution</span><span class="special">&lt;</span>
+ <span class="keyword">double</span><span class="special">,</span>
+ <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">discrete_quantile</span><span class="special">&lt;</span><span class="identifier">integer_round_down</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="special">&gt;</span>
+ <span class="identifier">binom_round_down</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">binomial_distribution</span><span class="special">&lt;</span>
+ <span class="keyword">double</span><span class="special">,</span>
+ <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">discrete_quantile</span><span class="special">&lt;</span><span class="identifier">integer_round_up</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="special">&gt;</span>
+ <span class="identifier">binom_round_up</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">binomial_distribution</span><span class="special">&lt;</span>
+ <span class="keyword">double</span><span class="special">,</span>
+ <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">discrete_quantile</span><span class="special">&lt;</span><span class="identifier">integer_round_nearest</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="special">&gt;</span>
+ <span class="identifier">binom_round_nearest</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">binomial_distribution</span><span class="special">&lt;</span>
+ <span class="keyword">double</span><span class="special">,</span>
+ <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">discrete_quantile</span><span class="special">&lt;</span><span class="identifier">real</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="special">&gt;</span>
+ <span class="identifier">binom_real_quantile</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Now let's set to work calling those quantiles:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span>
+ <span class="string">"Testing rounding policies for a 50 sample binomial distribution,\n"</span>
+ <span class="string">"with a success fraction of 0.5.\n\n"</span>
+ <span class="string">"Lower quantiles are calculated at p = 0.05\n\n"</span>
+ <span class="string">"Upper quantiles at p = 0.95.\n\n"</span><span class="special">;</span>
+
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">25</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"Policy"</span><span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"Lower Quantile"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"Upper Quantile"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+
+ <span class="comment">// Test integer_round_outwards:
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">25</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"integer_round_outwards"</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_outwards</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.05</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_outwards</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.95</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+
+ <span class="comment">// Test integer_round_inwards:
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">25</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"integer_round_inwards"</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_inwards</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.05</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_inwards</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.95</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+
+ <span class="comment">// Test integer_round_down:
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">25</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"integer_round_down"</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_down</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.05</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_down</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.95</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+
+ <span class="comment">// Test integer_round_up:
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">25</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"integer_round_up"</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_up</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.05</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_up</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.95</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+
+ <span class="comment">// Test integer_round_nearest:
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">25</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"integer_round_nearest"</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_nearest</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.05</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_nearest</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.95</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+
+ <span class="comment">// Test real:
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">25</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="string">"real"</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_real_quantile</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.05</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_real_quantile</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.95</span><span class="special">)</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Which produces the program output:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Testing rounding policies for a 50 sample binomial distribution,
+with a success fraction of 0.5.
+
+Lower quantiles are calculated at p = 0.05
+
+Upper quantiles at p = 0.95.
+
+Testing rounding policies for a 50 sample binomial distribution,
+with a success fraction of 0.5.
+
+Lower quantiles are calculated at p = 0.05
+
+Upper quantiles at p = 0.95.
+
+ Policy Lower Quantile Upper Quantile
+ integer_round_outwards 18 31
+ integer_round_inwards 19 30
+ integer_round_down 18 30
+ integer_round_up 19 31
+ integer_round_nearest 19 30
+ real 18.701 30.299
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="user_def_err_pol.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../pol_ref.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/user_def_err_pol.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/user_def_err_pol.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,657 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Calling User Defined Error Handlers</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
+<link rel="prev" href="namespace_policies.html" title="Setting Policies at Namespace or Translation Unit Scope">
+<link rel="next" href="understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="namespace_policies.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="understand_dis_quant.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_tutorial.user_def_err_pol"></a><a href="user_def_err_pol.html" title="Calling User Defined Error Handlers">
+ Calling User Defined Error Handlers</a>
+</h4></div></div></div>
+<p>
+ </p>
+<p>
+ Suppose we want our own user-defined error handlers rather than the any
+ of the default ones supplied by the library to be used. If we set the
+ policy for a specific type of error to <code class="computeroutput"><span class="identifier">user_error</span></code>
+ then the library will call a user-supplied error handler. These are forward
+ declared, but not defined in boost/math/policies/error_handling.hpp like
+ this:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">policy</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_domain_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_pole_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_overflow_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_underflow_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_denorm_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_evaluation_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+
+<span class="special">}}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ </p>
+<p>
+ So out first job is to include the header we want to use, and then provide
+ definitions for the user-defined error handlers we want to use:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">policies</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_domain_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special">&lt;&lt;</span> <span class="string">"Domain Error."</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">quiet_NaN</span><span class="special">();</span>
+<span class="special">}</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_pole_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special">&lt;&lt;</span> <span class="string">"Pole Error."</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">quiet_NaN</span><span class="special">();</span>
+<span class="special">}</span>
+
+
+<span class="special">}}}</span> <span class="comment">// namespaces</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Now we'll need to define a suitable policy that will call these handlers,
+ and define some forwarding functions that make use of the policy:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">namespace</span><span class="special">{</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span>
+ <span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">user_error</span><span class="special">&gt;,</span>
+ <span class="identifier">pole_error</span><span class="special">&lt;</span><span class="identifier">user_error</span><span class="special">&gt;</span>
+<span class="special">&gt;</span> <span class="identifier">user_error_policy</span><span class="special">;</span>
+
+<span class="identifier">BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS</span><span class="special">(</span><span class="identifier">user_error_policy</span><span class="special">)</span>
+
+<span class="special">}</span> <span class="comment">// close unnamed namespace</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ We now have a set of forwarding functions defined in an unnamed namespace
+ that all look something like this:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">&gt;</span>
+<span class="keyword">inline</span> <span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">::</span><span class="identifier">promote_args</span><span class="special">&lt;</span><span class="identifier">RT</span><span class="special">&gt;::</span><span class="identifier">type</span>
+ <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">RT</span> <span class="identifier">z</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">user_error_policy</span><span class="special">());</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ So that when we call <code class="computeroutput"><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span></code> we really end up calling <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">user_error_policy</span><span class="special">())</span></code>,
+ and any errors will get directed to our own error handlers:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of erf_inv(-10) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">erf_inv</span><span class="special">(-</span><span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of tgamma(-10) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">tgamma</span><span class="special">(-</span><span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+<span class="special">}</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Which outputs:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Domain Error.
+Result of erf_inv(-10) is: 1.#QNAN
+Pole Error.
+Result of tgamma(-10) is: 1.#QNAN
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ The previous example was all well and good, but the custom error handlers
+ didn't really do much of any use. In this example we'll implement all
+ the custom handlers and show how the information provided to them can
+ be used to generate nice formatted error messages.
+ </p>
+<p>
+ </p>
+<p>
+ Each error handler has the general form:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_</span><span class="emphasis"><em>error_type</em></span><span class="special">(</span>
+ <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+</pre>
+<p>
+ </p>
+<p>
+ and accepts three arguments:
+ </p>
+<p>
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">const char* function</span></dt>
+<dd><p>
+ The name of the function that raised the error, this string contains
+ one or more %1% format specifiers that should be replaced by the
+ name of type T.
+ </p></dd>
+<dt><span class="term">const char* message</span></dt>
+<dd><p>
+ A message associated with the error, normally this contains a %1%
+ format specifier that should be replaced with the value of <span class="emphasis"><em>value</em></span>:
+ however note that overflow and underflow messages do not contain
+ this %1% specifier (since the value of <span class="emphasis"><em>value</em></span>
+ is immaterial in these cases).
+ </p></dd>
+<dt><span class="term">const T&amp; value</span></dt>
+<dd><p>
+ The value that caused the error: either an argument to the function
+ if this is a domain or pole error, the tentative result if this is
+ a denorm or evaluation error, or zero or infinity for underflow or
+ overflow errors.
+ </p></dd>
+</dl>
+</div>
+<p>
+ </p>
+<p>
+ As before we'll include the headers we need first:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Next we'll implement the error handlers for each type of error, starting
+ with domain errors:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">policies</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_domain_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">)</span>
+<span class="special">{</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ We'll begin with a bit of defensive programming:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">if</span><span class="special">(</span><span class="identifier">function</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
+ <span class="identifier">function</span> <span class="special">=</span> <span class="string">"Unknown function with arguments of type %1%"</span><span class="special">;</span>
+<span class="keyword">if</span><span class="special">(</span><span class="identifier">message</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
+ <span class="identifier">message</span> <span class="special">=</span> <span class="string">"Cause unknown with bad argument %1%"</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Next we'll format the name of the function with the name of type T:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span><span class="special">(</span><span class="string">"Error in function "</span><span class="special">);</span>
+<span class="identifier">msg</span> <span class="special">+=</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="identifier">function</span><span class="special">)</span> <span class="special">%</span> <span class="keyword">typeid</span><span class="special">(</span><span class="identifier">T</span><span class="special">).</span><span class="identifier">name</span><span class="special">()).</span><span class="identifier">str</span><span class="special">();</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Then likewise format the error message with the value of parameter <span class="emphasis"><em>val</em></span>,
+ making sure we output all the digits of <span class="emphasis"><em>val</em></span>:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">msg</span> <span class="special">+=</span> <span class="string">": \n"</span><span class="special">;</span>
+<span class="keyword">int</span> <span class="identifier">prec</span> <span class="special">=</span> <span class="number">2</span> <span class="special">+</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">digits</span> <span class="special">*</span> <span class="number">30103UL</span><span class="special">)</span> <span class="special">/</span> <span class="number">100000UL</span><span class="special">;</span>
+<span class="identifier">msg</span> <span class="special">+=</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="identifier">message</span><span class="special">)</span> <span class="special">%</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">io</span><span class="special">::</span><span class="identifier">group</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">(</span><span class="identifier">prec</span><span class="special">),</span> <span class="identifier">val</span><span class="special">)).</span><span class="identifier">str</span><span class="special">();</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Now we just have to do something with the message, we could throw an
+ exception, but for the purposes of this example we'll just dump the message
+ to std::cerr:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special">&lt;&lt;</span> <span class="identifier">msg</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Finally the only sensible value we can return from a domain error is
+ a NaN:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+ <span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">quiet_NaN</span><span class="special">();</span>
+<span class="special">}</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Pole errors are essentially a special case of domain errors, so in this
+ example we'll just return the result of a domain error:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_pole_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">return</span> <span class="identifier">user_domain_error</span><span class="special">(</span><span class="identifier">function</span><span class="special">,</span> <span class="identifier">message</span><span class="special">,</span> <span class="identifier">val</span><span class="special">);</span>
+<span class="special">}</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Overflow errors are very similar to domain errors, except that there's
+ no %1% format specifier in the <span class="emphasis"><em>message</em></span> parameter:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_overflow_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">if</span><span class="special">(</span><span class="identifier">function</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
+ <span class="identifier">function</span> <span class="special">=</span> <span class="string">"Unknown function with arguments of type %1%"</span><span class="special">;</span>
+ <span class="keyword">if</span><span class="special">(</span><span class="identifier">message</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
+ <span class="identifier">message</span> <span class="special">=</span> <span class="string">"Result of function is too large to represent"</span><span class="special">;</span>
+
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span><span class="special">(</span><span class="string">"Error in function "</span><span class="special">);</span>
+ <span class="identifier">msg</span> <span class="special">+=</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="identifier">function</span><span class="special">)</span> <span class="special">%</span> <span class="keyword">typeid</span><span class="special">(</span><span class="identifier">T</span><span class="special">).</span><span class="identifier">name</span><span class="special">()).</span><span class="identifier">str</span><span class="special">();</span>
+
+ <span class="identifier">msg</span> <span class="special">+=</span> <span class="string">": \n"</span><span class="special">;</span>
+ <span class="identifier">msg</span> <span class="special">+=</span> <span class="identifier">message</span><span class="special">;</span>
+
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special">&lt;&lt;</span> <span class="identifier">msg</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+
+ <span class="comment">// Value passed to the function is an infinity, just return it:
+</span> <span class="keyword">return</span> <span class="identifier">val</span><span class="special">;</span>
+<span class="special">}</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Underflow errors are much the same as overflow:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_underflow_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">if</span><span class="special">(</span><span class="identifier">function</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
+ <span class="identifier">function</span> <span class="special">=</span> <span class="string">"Unknown function with arguments of type %1%"</span><span class="special">;</span>
+ <span class="keyword">if</span><span class="special">(</span><span class="identifier">message</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
+ <span class="identifier">message</span> <span class="special">=</span> <span class="string">"Result of function is too small to represent"</span><span class="special">;</span>
+
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span><span class="special">(</span><span class="string">"Error in function "</span><span class="special">);</span>
+ <span class="identifier">msg</span> <span class="special">+=</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="identifier">function</span><span class="special">)</span> <span class="special">%</span> <span class="keyword">typeid</span><span class="special">(</span><span class="identifier">T</span><span class="special">).</span><span class="identifier">name</span><span class="special">()).</span><span class="identifier">str</span><span class="special">();</span>
+
+ <span class="identifier">msg</span> <span class="special">+=</span> <span class="string">": \n"</span><span class="special">;</span>
+ <span class="identifier">msg</span> <span class="special">+=</span> <span class="identifier">message</span><span class="special">;</span>
+
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special">&lt;&lt;</span> <span class="identifier">msg</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+
+ <span class="comment">// Value passed to the function is zero, just return it:
+</span> <span class="keyword">return</span> <span class="identifier">val</span><span class="special">;</span>
+<span class="special">}</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Denormalised results are much the same as underflow:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_denorm_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">if</span><span class="special">(</span><span class="identifier">function</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
+ <span class="identifier">function</span> <span class="special">=</span> <span class="string">"Unknown function with arguments of type %1%"</span><span class="special">;</span>
+ <span class="keyword">if</span><span class="special">(</span><span class="identifier">message</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
+ <span class="identifier">message</span> <span class="special">=</span> <span class="string">"Result of function is denormalised"</span><span class="special">;</span>
+
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span><span class="special">(</span><span class="string">"Error in function "</span><span class="special">);</span>
+ <span class="identifier">msg</span> <span class="special">+=</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="identifier">function</span><span class="special">)</span> <span class="special">%</span> <span class="keyword">typeid</span><span class="special">(</span><span class="identifier">T</span><span class="special">).</span><span class="identifier">name</span><span class="special">()).</span><span class="identifier">str</span><span class="special">();</span>
+
+ <span class="identifier">msg</span> <span class="special">+=</span> <span class="string">": \n"</span><span class="special">;</span>
+ <span class="identifier">msg</span> <span class="special">+=</span> <span class="identifier">message</span><span class="special">;</span>
+
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special">&lt;&lt;</span> <span class="identifier">msg</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+
+ <span class="comment">// Value passed to the function is denormalised, just return it:
+</span> <span class="keyword">return</span> <span class="identifier">val</span><span class="special">;</span>
+<span class="special">}</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Which leaves us with evaluation errors, these occur when an internal
+ error occurs that prevents the function being fully evaluated. The parameter
+ <span class="emphasis"><em>val</em></span> contains the closest approximation to the result
+ found so far:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">user_evaluation_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">if</span><span class="special">(</span><span class="identifier">function</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
+ <span class="identifier">function</span> <span class="special">=</span> <span class="string">"Unknown function with arguments of type %1%"</span><span class="special">;</span>
+ <span class="keyword">if</span><span class="special">(</span><span class="identifier">message</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
+ <span class="identifier">message</span> <span class="special">=</span> <span class="string">"An internal evaluation error occured with "</span>
+ <span class="string">"the best value calculated so far of %1%"</span><span class="special">;</span>
+
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span><span class="special">(</span><span class="string">"Error in function "</span><span class="special">);</span>
+ <span class="identifier">msg</span> <span class="special">+=</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="identifier">function</span><span class="special">)</span> <span class="special">%</span> <span class="keyword">typeid</span><span class="special">(</span><span class="identifier">T</span><span class="special">).</span><span class="identifier">name</span><span class="special">()).</span><span class="identifier">str</span><span class="special">();</span>
+
+ <span class="identifier">msg</span> <span class="special">+=</span> <span class="string">": \n"</span><span class="special">;</span>
+ <span class="keyword">int</span> <span class="identifier">prec</span> <span class="special">=</span> <span class="number">2</span> <span class="special">+</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">digits</span> <span class="special">*</span> <span class="number">30103UL</span><span class="special">)</span> <span class="special">/</span> <span class="number">100000UL</span><span class="special">;</span>
+ <span class="identifier">msg</span> <span class="special">+=</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="identifier">message</span><span class="special">)</span> <span class="special">%</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">io</span><span class="special">::</span><span class="identifier">group</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">(</span><span class="identifier">prec</span><span class="special">),</span> <span class="identifier">val</span><span class="special">)).</span><span class="identifier">str</span><span class="special">();</span>
+
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special">&lt;&lt;</span> <span class="identifier">msg</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+
+ <span class="comment">// What do we return here? This is generally a fatal error,
+</span> <span class="comment">// that should never occur, just return a NaN for the purposes
+</span> <span class="comment">// of the example:
+</span> <span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">quiet_NaN</span><span class="special">();</span>
+<span class="special">}</span>
+
+<span class="special">}}}</span> <span class="comment">// namespaces</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Now we'll need to define a suitable policy that will call these handlers,
+ and define some forwarding functions that make use of the policy:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">namespace</span><span class="special">{</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+
+<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span>
+ <span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">user_error</span><span class="special">&gt;,</span>
+ <span class="identifier">pole_error</span><span class="special">&lt;</span><span class="identifier">user_error</span><span class="special">&gt;,</span>
+ <span class="identifier">overflow_error</span><span class="special">&lt;</span><span class="identifier">user_error</span><span class="special">&gt;,</span>
+ <span class="identifier">underflow_error</span><span class="special">&lt;</span><span class="identifier">user_error</span><span class="special">&gt;,</span>
+ <span class="identifier">denorm_error</span><span class="special">&lt;</span><span class="identifier">user_error</span><span class="special">&gt;,</span>
+ <span class="identifier">evaluation_error</span><span class="special">&lt;</span><span class="identifier">user_error</span><span class="special">&gt;</span>
+<span class="special">&gt;</span> <span class="identifier">user_error_policy</span><span class="special">;</span>
+
+<span class="identifier">BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS</span><span class="special">(</span><span class="identifier">user_error_policy</span><span class="special">)</span>
+
+<span class="special">}</span> <span class="comment">// close unnamed namespace</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ We now have a set of forwarding functions defined in an unnamed namespace
+ that all look something like this:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">&gt;</span>
+<span class="keyword">inline</span> <span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">::</span><span class="identifier">promote_args</span><span class="special">&lt;</span><span class="identifier">RT</span><span class="special">&gt;::</span><span class="identifier">type</span>
+ <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">RT</span> <span class="identifier">z</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">user_error_policy</span><span class="special">());</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ So that when we call <code class="computeroutput"><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span></code> we really end up calling <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">user_error_policy</span><span class="special">())</span></code>,
+ and any errors will get directed to our own error handlers:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="comment">// Raise a domain error:
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of erf_inv(-10) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">erf_inv</span><span class="special">(-</span><span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="comment">// Raise a pole error:
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of tgamma(-10) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">tgamma</span><span class="special">(-</span><span class="number">10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="comment">// Raise an overflow error:
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of tgamma(3000) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="number">3000</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="comment">// Raise an underflow error:
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Result of tgamma(-190.5) is: "</span>
+ <span class="special">&lt;&lt;</span> <span class="identifier">tgamma</span><span class="special">(-</span><span class="number">190.5</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+ <span class="comment">// Unfortunately we can't predicably raise a denormalised
+</span> <span class="comment">// result, nor can we raise an evaluation error in this example
+</span> <span class="comment">// since these should never really occur!
+</span><span class="special">}</span></pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ Which outputs:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">Error in function boost::math::erf_inv&lt;double&gt;(double, double):
+Argument outside range [-1, 1] in inverse erf function (got p=-10).
+Result of erf_inv(-10) is: 1.#QNAN
+
+Error in function boost::math::tgamma&lt;long double&gt;(long double):
+Evaluation of tgamma at a negative integer -10.
+Result of tgamma(-10) is: 1.#QNAN
+
+Error in function boost::math::tgamma&lt;long double&gt;(long double):
+Result of tgamma is too large to represent.
+Error in function boost::math::tgamma&lt;double&gt;(double):
+Result of function is too large to represent
+Result of tgamma(3000) is: 1.#INF
+
+Error in function boost::math::tgamma&lt;long double&gt;(long double):
+Result of tgamma is too large to represent.
+Error in function boost::math::tgamma&lt;long double&gt;(long double):
+Result of tgamma is too small to represent.
+Result of tgamma(-190.5) is: 0
+</pre>
+<p>
+ </p>
+<p>
+ Notice how some of the calls result in an error handler being called
+ more than once, or for more than one handler to be called: this is an
+ artefact of the fact that many functions are implemented in terms of
+ one or more sub-routines each of which may have it's own error handling.
+ For example <code class="computeroutput"><span class="identifier">tgamma</span><span class="special">(-</span><span class="number">190.5</span><span class="special">)</span></code>
+ is implemented in terms of <code class="computeroutput"><span class="identifier">tgamma</span><span class="special">(</span><span class="number">190.5</span><span class="special">)</span></code> - which overflows - the reflection formula
+ for <code class="computeroutput"><span class="identifier">tgamma</span></code> then notices
+ that it's dividing by infinity and underflows.
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="namespace_policies.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="understand_dis_quant.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/what_is_a_policy.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/policy/pol_tutorial/what_is_a_policy.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,84 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>So Just What is a Policy Anyway?</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
+<link rel="prev" href="../pol_tutorial.html" title="Policy Tutorial">
+<link rel="next" href="policy_tut_defaults.html" title="Policies Have Sensible Defaults">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="policy_tut_defaults.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.policy.pol_tutorial.what_is_a_policy"></a><a href="what_is_a_policy.html" title="So Just What is a Policy Anyway?">
+ So Just What is a Policy Anyway?</a>
+</h4></div></div></div>
+<p>
+ A policy is a compile-time mechanism for customising the behaviour of a
+ special function, or a statistical distribution. With Policies you can
+ control:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ What action to take when an error occurs.
+ </li>
+<li>
+ What happens when you call a function that is mathematically undefined
+ (for example if you ask for the mean of a Cauchy distribution).
+ </li>
+<li>
+ What happens when you ask for a quantile of a discrete distribution.
+ </li>
+<li>
+ Whether the library is allowed to internally promote <code class="computeroutput"><span class="keyword">float</span></code>
+ to <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">double</span></code> to <code class="computeroutput"><span class="keyword">long</span>
+ <span class="keyword">double</span></code> in order to improve precision.
+ </li>
+<li>
+ What precision to use when calculating the result.
+ </li>
+</ul></div>
+<p>
+ Some of these policies could arguably be runtime variables, but then we
+ couldn't use compile-time dispatch internally to select the best evaluation
+ method for the given policies.
+ </p>
+<p>
+ For this reason a Policy is a <span class="emphasis"><em>type</em></span>: in fact it's an
+ instance of the class template <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">&lt;&gt;</span></code>. This class is just a compile-time-container
+ of user-selected policies (sometimes called a type-list):
+ </p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
+<span class="comment">//
+</span><span class="comment">// Define a policy that sets ::errno on overflow, and does
+</span><span class="comment">// not promote double to long double internally:
+</span><span class="comment">//
+</span><span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">domain_error</span><span class="special">&lt;</span><span class="identifier">errno_on_error</span><span class="special">&gt;,</span> <span class="identifier">promote_double</span><span class="special">&lt;</span><span class="keyword">false</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">mypolicy</span><span class="special">;</span>
+</pre>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="policy_tut_defaults.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,147 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Special Functions</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../index.html" title="Math Toolkit">
+<link rel="up" href="../index.html" title="Math Toolkit">
+<link rel="prev" href="dist/future.html" title="Extras/Future Directions">
+<link rel="next" href="special/sf_gamma.html" title="Gamma Functions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="dist/future.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="special/sf_gamma.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="math_toolkit.special"></a> Special Functions
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"> Gamma Functions</span></dt>
+<dd><dl>
+<dt><span class="section"> Gamma</span></dt>
+<dt><span class="section"> Log Gamma</span></dt>
+<dt><span class="section"> Digamma</span></dt>
+<dt><span class="section"><a href="special/sf_gamma/gamma_ratios.html"> Ratios
+ of Gamma Functions</a></span></dt>
+<dt><span class="section"><a href="special/sf_gamma/igamma.html"> Incomplete Gamma
+ Functions</a></span></dt>
+<dt><span class="section"><a href="special/sf_gamma/igamma_inv.html"> Incomplete
+ Gamma Function Inverses</a></span></dt>
+<dt><span class="section"><a href="special/sf_gamma/gamma_derivatives.html"> Derivative
+ of the Incomplete Gamma Function</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="special/factorials.html"> Factorials and Binomial
+ Coefficients</a></span></dt>
+<dd><dl>
+<dt><span class="section"> Factorial</span></dt>
+<dt><span class="section"><a href="special/factorials/sf_double_factorial.html">
+ Double Factorial</a></span></dt>
+<dt><span class="section"><a href="special/factorials/sf_rising_factorial.html">
+ Rising Factorial</a></span></dt>
+<dt><span class="section"><a href="special/factorials/sf_falling_factorial.html">
+ Falling Factorial</a></span></dt>
+<dt><span class="section"><a href="special/factorials/sf_binomial.html"> Binomial
+ Coefficients</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Beta Functions</span></dt>
+<dd><dl>
+<dt><span class="section"> Beta</span></dt>
+<dt><span class="section"><a href="special/sf_beta/ibeta_function.html"> Incomplete
+ Beta Functions</a></span></dt>
+<dt><span class="section"><a href="special/sf_beta/ibeta_inv_function.html"> The
+ Incomplete Beta Function Inverses</a></span></dt>
+<dt><span class="section"><a href="special/sf_beta/beta_derivative.html"> Derivative
+ of the Incomplete Beta Function</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Error Functions</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="special/sf_erf/error_function.html"> Error
+ Functions</a></span></dt>
+<dt><span class="section"><a href="special/sf_erf/error_inv.html"> Error Function
+ Inverses</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Polynomials</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="special/sf_poly/legendre.html"> Legendre (and
+ Associated) Polynomials</a></span></dt>
+<dt><span class="section"><a href="special/sf_poly/laguerre.html"> Laguerre (and
+ Associated) Polynomials</a></span></dt>
+<dt><span class="section"> Hermite Polynomials</span></dt>
+<dt><span class="section"> Spherical Harmonics</span></dt>
+</dl></dd>
+<dt><span class="section"> Bessel Functions</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="special/bessel/bessel_over.html"> Bessel Function
+ Overview</a></span></dt>
+<dt><span class="section"><a href="special/bessel/bessel.html"> Bessel Functions
+ of the First and Second Kinds</a></span></dt>
+<dt><span class="section"><a href="special/bessel/mbessel.html"> Modified Bessel
+ Functions of the First and Second Kinds</a></span></dt>
+<dt><span class="section"><a href="special/bessel/sph_bessel.html"> Spherical
+ Bessel Functions of the First and Second Kinds</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Elliptic Integrals</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="special/ellint/ellint_intro.html"> Elliptic
+ Integral Overview</a></span></dt>
+<dt><span class="section"><a href="special/ellint/ellint_carlson.html"> Elliptic
+ Integrals - Carlson Form</a></span></dt>
+<dt><span class="section"><a href="special/ellint/ellint_1.html"> Elliptic Integrals
+ of the First Kind - Legendre Form</a></span></dt>
+<dt><span class="section"><a href="special/ellint/ellint_2.html"> Elliptic Integrals
+ of the Second Kind - Legendre Form</a></span></dt>
+<dt><span class="section"><a href="special/ellint/ellint_3.html"> Elliptic Integrals
+ of the Third Kind - Legendre Form</a></span></dt>
+</dl></dd>
+<dt><span class="section"><a href="special/powers.html"> Logs, Powers, Roots and
+ Exponentials</a></span></dt>
+<dd><dl>
+<dt><span class="section"> log1p</span></dt>
+<dt><span class="section"> expm1</span></dt>
+<dt><span class="section"> cbrt</span></dt>
+<dt><span class="section"> sqrt1pm1</span></dt>
+<dt><span class="section"> powm1</span></dt>
+<dt><span class="section"> hypot</span></dt>
+</dl></dd>
+<dt><span class="section"><a href="special/sinc.html"> Sinus Cardinal and Hyperbolic
+ Sinus Cardinal Functions</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="special/sinc/sinc_overview.html"> Sinus Cardinal
+ and Hyperbolic Sinus Cardinal Functions Overview</a></span></dt>
+<dt><span class="section">sinc_pi</span></dt>
+<dt><span class="section">sinhc_pi</span></dt>
+</dl></dd>
+<dt><span class="section"> Inverse Hyperbolic Functions</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="special/inv_hyper/inv_hyper_over.html"> Inverse
+ Hyperbolic Functions Overview</a></span></dt>
+<dt><span class="section"> acosh</span></dt>
+<dt><span class="section"> asinh</span></dt>
+<dt><span class="section"> atanh</span></dt>
+</dl></dd>
+<dt><span class="section"><a href="special/fpclass.html"> Floating Point Classification:
+ Infinities and NaN's</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="dist/future.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="special/sf_gamma.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/bessel.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/bessel.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,58 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Bessel Functions</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../special.html" title="Special Functions">
+<link rel="prev" href="sf_poly/sph_harm.html" title="Spherical Harmonics">
+<link rel="next" href="bessel/bessel_over.html" title="Bessel Function Overview">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_poly/sph_harm.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="bessel/bessel_over.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.special.bessel"></a> Bessel Functions
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="bessel/bessel_over.html"> Bessel Function
+ Overview</a></span></dt>
+<dt><span class="section"><a href="bessel/bessel.html"> Bessel Functions
+ of the First and Second Kinds</a></span></dt>
+<dt><span class="section"><a href="bessel/mbessel.html"> Modified Bessel
+ Functions of the First and Second Kinds</a></span></dt>
+<dt><span class="section"><a href="bessel/sph_bessel.html"> Spherical
+ Bessel Functions of the First and Second Kinds</a></span></dt>
+</dl></div>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_poly/sph_harm.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="bessel/bessel_over.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/bessel/bessel.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/bessel/bessel.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,669 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Bessel Functions of the First and Second Kinds</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../bessel.html" title="Bessel Functions">
+<link rel="prev" href="bessel_over.html" title="Bessel Function Overview">
+<link rel="next" href="mbessel.html" title="Modified Bessel Functions of the First and Second Kinds">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="bessel_over.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../bessel.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="mbessel.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.bessel.bessel"></a><a href="bessel.html" title="Bessel Functions of the First and Second Kinds"> Bessel Functions
+ of the First and Second Kinds</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.bessel.bessel.synopsis"></a><h5>
+<a name="id669290"></a>
+ Synopsis
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">cyl_bessel_j</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">cyl_bessel_j</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">cyl_neumann</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">cyl_neumann</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<a name="math_toolkit.special.bessel.bessel.description"></a><h5>
+<a name="id669800"></a>
+ Description
+ </h5>
+<p>
+ The functions cyl_bessel_j
+ and cyl_neumann
+ return the result of the Bessel functions of the first and second kinds
+ respectively:
+ </p>
+<p>
+ cyl_bessel_j(v, x) = J<sub>v</sub>(x)
+ </p>
+<p>
+ cyl_neumann(v, x) = Y<sub>v</sub>(x) = N<sub>v</sub>(x)
+ </p>
+<p>
+ where:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel2.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel3.png"></span>
+ </p>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when T1 and T2 are different types.
+ The functions are also optimised for the relatively common case that T1
+ is an integer.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ The functions return the result of domain_error
+ whenever the result is undefined or complex. For cyl_bessel_j
+ this occurs when <code class="computeroutput"><span class="identifier">x</span> <span class="special">&lt;</span>
+ <span class="number">0</span></code> and v is not an integer, or when
+ <code class="computeroutput"><span class="identifier">x</span> <span class="special">==</span>
+ <span class="number">0</span></code> and <code class="computeroutput"><span class="identifier">v</span>
+ <span class="special">!=</span> <span class="number">0</span></code>.
+ For cyl_neumann
+ this occurs when <code class="computeroutput"><span class="identifier">x</span> <span class="special">&lt;=</span>
+ <span class="number">0</span></code>.
+ </p>
+<p>
+ The following graph illustrates the cyclic nature of J<sub>v</sub>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/bessel_jn.png" alt="bessel_jn"></span>
+ </p>
+<p>
+ The following graph shows the behaviour of Y<sub>v</sub>: this is also cyclic for
+ large <span class="emphasis"><em>x</em></span>, but tends to -&#8734; for small <span class="emphasis"><em>x</em></span>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/bessel_yv.png" alt="bessel_yv"></span>
+ </p>
+<a name="math_toolkit.special.bessel.bessel.testing"></a><h5>
+<a name="id670172"></a>
+ Testing
+ </h5>
+<p>
+ There are two sets of test values: spot values calculated using functions.wolfram.com, and a
+ much larger set of tests computed using a simplified version of this implementation
+ (with all the special case handling removed).
+ </p>
+<a name="math_toolkit.special.bessel.bessel.accuracy"></a><h5>
+<a name="id670211"></a>
+ Accuracy
+ </h5>
+<p>
+ The following tables show how the accuracy of these functions varies on
+ various platforms, along with comparisons to the GSL-1.9
+ and Cephes libraries.
+ Note that the cyclic nature of these functions means that they have an
+ infinite number of irrational roots: in general these functions have arbitrarily
+ large <span class="emphasis"><em>relative</em></span> errors when the arguments are sufficiently
+ close to a root. Of course the absolute error in such cases is always small.
+ Note that only results for the widest floating-point type on the system
+ are given as narrower types have <a href="../../backgrounders/relative_error.html#zero_error">effectively
+ zero error</a>. All values are relative errors in units of epsilon.
+ </p>
+<div class="table">
+<a name="id670268"></a><p class="title"><b>Table 29. Errors Rates in cyl_bessel_j</b></p>
+<div class="table-contents"><table class="table" summary="Errors Rates in cyl_bessel_j">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ J<sub>0</sub> and J<sub>1</sub>
+ </p>
+ </th>
+<th>
+ <p>
+ J<sub>v</sub>
+ </p>
+ </th>
+<th>
+ <p>
+ J<sub>v</sub> (large values of x &gt; 1000)
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32 / Visual C++ 8.0
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2.5 Mean=1.1
+ </p>
+ <p>
+ GSL Peak=6.6
+ </p>
+ <p>
+ Cephes Peak=2.5
+ Mean=1.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=11 Mean=2.2
+ </p>
+ <p>
+ GSL Peak=11
+ </p>
+ <p>
+ Cephes Peak=17
+ Mean=2.5
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=413 Mean=110
+ </p>
+ <p>
+ GSL Peak=6x10<sup>11</sup>
+ </p>
+ <p>
+ Cephes Peak=2x10<sup>5</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux IA64 / G++ 3.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=7 Mean=3
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=117 Mean=10
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2x10<sup>4</sup> Mean=6x10<sup>3</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ SUSE Linux AMD64 / G++ 4.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=7 Mean=3
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=400 Mean=40
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2x10<sup>4</sup> Mean=1x10<sup>4</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HP-UX / HP aCC 6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=14 Mean=6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=29 Mean=3
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2700 Mean=450
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id670572"></a><p class="title"><b>Table 30. Errors Rates in cyl_neumann</b></p>
+<div class="table-contents"><table class="table" summary="Errors Rates in cyl_neumann">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ J<sub>0</sub> and J<sub>1</sub>
+ </p>
+ </th>
+<th>
+ <p>
+ J<sub>n</sub> (integer orders)
+ </p>
+ </th>
+<th>
+ <p>
+ J<sub>v</sub> (fractional orders)
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32 / Visual C++ 8.0
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=330 Mean=54
+ </p>
+ <p>
+ GSL Peak=34 Mean=9
+ </p>
+ <p>
+ Cephes Peak=330
+ Mean=54
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=923 Mean=83
+ </p>
+ <p>
+ GSL Peak=500 Mean=54
+ </p>
+ <p>
+ Cephes Peak=923
+ Mean=83
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=561 Mean=36
+ </p>
+ <p>
+ GSL Peak=1.4x10<sup>6</sup> Mean=7x10<sup>4</sup>
+ </p>
+ <p>
+ Cephes Peak=+INF
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux IA64 / G++ 3.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=470 Mean=56
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=843 Mean=51
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=741 Mean=51
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ SUSE Linux AMD64 / G++ 4.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1300 Mean=424
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2x10<sup>4</sup> Mean=8x10<sup>3</sup>
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1x10<sup>5</sup> Mean=6x10<sup>3</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HP-UX / HP aCC 6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=180 Mean=63
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=340 Mean=150
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2x10<sup>4</sup> Mean=1200
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><p>
+ Note that for large <span class="emphasis"><em>x</em></span> these functions are largely
+ dependent on the accuracy of the <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">sin</span></code>
+ and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cos</span></code> functions.
+ </p>
+<p>
+ Comparison to GSL and Cephes
+ is interesting: both Cephes
+ and this library optimise the integer order case - leading to identical
+ results - simply using the general case is for the most part slightly more
+ accurate though, as noted by the better accuracy of GSL in the integer
+ argument cases. This implementation tends to perform much better when the
+ arguments become large, Cephes
+ in particular produces some remarkably inaccurate results with some of
+ the test data (no significant figures correct), and even GSL performs badly
+ with some inputs to J<sub>v</sub>. Note that by way of double-checking these results,
+ the worst performing Cephes
+ and GSL cases were recomputed using functions.wolfram.com,
+ and the result checked against our test data: no errors in the test data
+ were found.
+ </p>
+<a name="math_toolkit.special.bessel.bessel.implementation"></a><h5>
+<a name="id671001"></a>
+ Implementation
+ </h5>
+<p>
+ The implementation is mostly about filtering off various special cases:
+ </p>
+<p>
+ When <span class="emphasis"><em>x</em></span> is negative, then the order <span class="emphasis"><em>v</em></span>
+ must be an integer or the result is a domain error. If the order is an
+ integer then the function is odd for odd orders and even for even orders,
+ so we reflect to <span class="emphasis"><em>x &gt; 0</em></span>.
+ </p>
+<p>
+ When the order <span class="emphasis"><em>v</em></span> is negative then the reflection formulae
+ can be used to move to <span class="emphasis"><em>v &gt; 0</em></span>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel9.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel10.png"></span>
+ </p>
+<p>
+ Note that if the order is an integer, then these formulae reduce to:
+ </p>
+<p>
+ J<sub>-n</sub> = (-1)<sup>n</sup>J<sub>n</sub>
+ </p>
+<p>
+ Y<sub>-n</sub> = (-1)<sup>n</sup>Y<sub>n</sub>
+ </p>
+<p>
+ However, in general, a negative order implies that we will need to compute
+ both J and Y.
+ </p>
+<p>
+ When <span class="emphasis"><em>x</em></span> is large compared to the order <span class="emphasis"><em>v</em></span>
+ then the asymptotic expansions for large <span class="emphasis"><em>x</em></span> in M. Abramowitz
+ and I.A. Stegun, <span class="emphasis"><em>Handbook of Mathematical Functions</em></span>
+ 9.2.19 are used (these were found to be more reliable than those in A&amp;S
+ 9.2.5).
+ </p>
+<p>
+ When the order <span class="emphasis"><em>v</em></span> is an integer the method first relates
+ the result to J<sub>0</sub>, J<sub>1</sub>, Y<sub>0</sub> and Y<sub>1</sub> using either forwards or backwards recurrence
+ (Miller's algorithm) depending upon which is stable. The values for J<sub>0</sub>,
+ J<sub>1</sub>, Y<sub>0</sub> and Y<sub>1</sub> are calculated using the rational minimax approximations on
+ root-bracketing intervals for small <span class="emphasis"><em>|x|</em></span> and Hankel
+ asymptotic expansion for large <span class="emphasis"><em>|x|</em></span>. The coefficients
+ are from:
+ </p>
+<p>
+ W.J. Cody, <span class="emphasis"><em>ALGORITHM 715: SPECFUN - A Portable FORTRAN Package
+ of Special Function Routines and Test Drivers</em></span>, ACM Transactions
+ on Mathematical Software, vol 19, 22 (1993).
+ </p>
+<p>
+ and
+ </p>
+<p>
+ J.F. Hart et al, <span class="emphasis"><em>Computer Approximations</em></span>, John Wiley
+ &amp; Sons, New York, 1968.
+ </p>
+<p>
+ These approximations are accurate to around 19 decimal digits: therefore
+ these methods are not used when type T has more than 64 binary digits.
+ </p>
+<p>
+ When <span class="emphasis"><em>x</em></span> is small, J<sub>x</sub> is best computed directly from
+ the series:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel2.png"></span>
+ </p>
+<p>
+ In the general case we compute J<sub>v</sub> and Y<sub>v</sub> simultaneously.
+ </p>
+<p>
+ To get the initial values, let &#956; = &#957; - floor(&#957; + 1/2), then &#956; is the fractional
+ part of &#957; such that |&#956;| &lt;= 1/2 (we need this for convergence later). The
+ idea is to calculate J<sub>&#956;</sub>(x), J<sub>&#956;+1</sub>(x), Y<sub>&#956;</sub>(x), Y<sub>&#956;+1</sub>(x) and use them to obtain
+ J<sub>&#957;</sub>(x), Y<sub>&#957;</sub>(x).
+ </p>
+<p>
+ The algorithm is called Steed's method, which needs two continued fractions
+ as well as the Wronskian:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel8.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel11.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel12.png"></span>
+ </p>
+<p>
+ See: F.S. Acton, <span class="emphasis"><em>Numerical Methods that Work</em></span>, The
+ Mathematical Association of America, Washington, 1997.
+ </p>
+<p>
+ The continued fractions are computed using the modified Lentz's method
+ (W.J. Lentz, <span class="emphasis"><em>Generating Bessel functions in Mie scattering calculations
+ using continued fractions</em></span>, Applied Optics, vol 15, 668 (1976)).
+ Their convergence rates depend on <span class="emphasis"><em>x</em></span>, therefore we
+ need different strategies for large <span class="emphasis"><em>x</em></span> and small <span class="emphasis"><em>x</em></span>.
+ </p>
+<p>
+ <span class="emphasis"><em>x &gt; v</em></span>, CF1 needs O(<span class="emphasis"><em>x</em></span>) iterations
+ to converge, CF2 converges rapidly
+ </p>
+<p>
+ <span class="emphasis"><em>x &lt;= v</em></span>, CF1 converges rapidly, CF2 fails to converge
+ when <span class="emphasis"><em>x</em></span> <code class="literal">-&gt;</code> 0
+ </p>
+<p>
+ When <span class="emphasis"><em>x</em></span> is large (<span class="emphasis"><em>x</em></span> &gt; 2), both
+ continued fractions converge (CF1 may be slow for really large <span class="emphasis"><em>x</em></span>).
+ J<sub>&#956;</sub>, J<sub>&#956;+1</sub>, Y<sub>&#956;</sub>, Y<sub>&#956;+1</sub> can be calculated by
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel13.png"></span>
+ </p>
+<p>
+ where
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel14.png"></span>
+ </p>
+<p>
+ J<sub>&#957;</sub> and Y<sub>&#956;</sub> are then calculated using backward (Miller's algorithm) and forward
+ recurrence respectively.
+ </p>
+<p>
+ When <span class="emphasis"><em>x</em></span> is small (<span class="emphasis"><em>x</em></span> &lt;= 2),
+ CF2 convergence may fail (but CF1 works very well). The solution here is
+ Temme's series:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel15.png"></span>
+ </p>
+<p>
+ where
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel16.png"></span>
+ </p>
+<p>
+ g<sub>k</sub> and h<sub>k</sub>
+are also computed by recursions (involving gamma functions), but
+ the formulas are a little complicated, readers are refered to N.M. Temme,
+ <span class="emphasis"><em>On the numerical evaluation of the ordinary Bessel function of
+ the second kind</em></span>, Journal of Computational Physics, vol 21, 343
+ (1976). Note Temme's series converge only for |&#956;| &lt;= 1/2.
+ </p>
+<p>
+ As the previous case, Y<sub>&#957;</sub> is calculated from the forward recurrence, so is
+ Y<sub>&#957;+1</sub>. With these two values and f<sub>&#957;</sub>, the Wronskian yields J<sub>&#957;</sub>(x) directly without
+ backward recurrence.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="bessel_over.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../bessel.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="mbessel.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/bessel/bessel_over.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/bessel/bessel_over.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,209 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Bessel Function Overview</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../bessel.html" title="Bessel Functions">
+<link rel="prev" href="../bessel.html" title="Bessel Functions">
+<link rel="next" href="bessel.html" title="Bessel Functions of the First and Second Kinds">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../bessel.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../bessel.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="bessel.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.bessel.bessel_over"></a><a href="bessel_over.html" title="Bessel Function Overview"> Bessel Function
+ Overview</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.bessel.bessel_over.ordinary_bessel_functions"></a><h5>
+<a name="id668300"></a>
+ <a href="bessel_over.html#math_toolkit.special.bessel.bessel_over.ordinary_bessel_functions">Ordinary
+ Bessel Functions</a>
+ </h5>
+<p>
+ Bessel Functions are solutions to Bessel's ordinary differential equation:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel1.png"></span>
+ </p>
+<p>
+ where &#957; is the <span class="emphasis"><em>order</em></span> of the equation, and may be an
+ arbitrary real or complex number, although integer orders are the most
+ common occurrence.
+ </p>
+<p>
+ This library supports either integer or real orders.
+ </p>
+<p>
+ Since this is a second order differential equation, there must be two linearly
+ independent solutions, the first of these is denoted J<sub>v</sub>
+and known as a Bessel
+ function of the first kind:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel2.png"></span>
+ </p>
+<p>
+ This function is implemented in this library as cyl_bessel_j.
+ </p>
+<p>
+ The second solution is denoted either Y<sub>v</sub> or N<sub>v</sub>
+and is known as either a Bessel
+ Function of the second kind, or as a Neumann function:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel3.png"></span>
+ </p>
+<p>
+ This function is implemented in this library as cyl_neumann.
+ </p>
+<p>
+ The Bessel functions satisfy the recurrence relations:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel4.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel5.png"></span>
+ </p>
+<p>
+ Have the derivatives:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel6.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel7.png"></span>
+ </p>
+<p>
+ Have the Wronskian relation:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel8.png"></span>
+ </p>
+<p>
+ and the reflection formulae:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel9.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/bessel10.png"></span>
+ </p>
+<a name="math_toolkit.special.bessel.bessel_over.modified_bessel_functions"></a><h5>
+<a name="id668717"></a>
+ <a href="bessel_over.html#math_toolkit.special.bessel.bessel_over.modified_bessel_functions">Modified
+ Bessel Functions</a>
+ </h5>
+<p>
+ The Bessel functions are valid for complex argument <span class="emphasis"><em>x</em></span>,
+ and an important special case is the situation where <span class="emphasis"><em>x</em></span>
+ is purely imaginary: giving a real valued result. In this case the functions
+ are the two linearly independent solutions to the modified Bessel equation:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel1.png"></span>
+ </p>
+<p>
+ The solutions are known as the modified Bessel functions of the first and
+ second kind (or occasionally as the hyperbolic Bessel functions of the
+ first and second kind). They are denoted I<sub>v</sub> and K<sub>v</sub>
+respectively:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel2.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel3.png"></span>
+ </p>
+<p>
+ These functions are implemented in this library as cyl_bessel_i
+ and cyl_bessel_k
+ respectively.
+ </p>
+<p>
+ The modified Bessel functions satisfy the recurrence relations:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel4.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel5.png"></span>
+ </p>
+<p>
+ Have the derivatives:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel6.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel7.png"></span>
+ </p>
+<p>
+ Have the Wronskian relation:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel8.png"></span>
+ </p>
+<p>
+ and the reflection formulae:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel9.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel10.png"></span>
+ </p>
+<a name="math_toolkit.special.bessel.bessel_over.spherical_bessel_functions"></a><h5>
+<a name="id669115"></a>
+ <a href="bessel_over.html#math_toolkit.special.bessel.bessel_over.spherical_bessel_functions">Spherical
+ Bessel Functions</a>
+ </h5>
+<p>
+ When solving the Helmholtz equation in spherical coordinates by separation
+ of variables, the radial equation has the form:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/sbessel1.png"></span>
+ </p>
+<p>
+ The two linearly independent solutions to this equation are called the
+ spherical Bessel functions j<sub>n</sub> and y<sub>n</sub>, and are related to the ordinary Bessel
+ functions J<sub>n</sub> and Y<sub>n</sub> by:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/sbessel2.png"></span>
+ </p>
+<p>
+ The spherical Bessel function of the second kind y<sub>n</sub>
+is also known as the
+ spherical Neumann function n<sub>n</sub>.
+ </p>
+<p>
+ These functions are implemented in this library as sph_bessel
+ and sph_neumann.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../bessel.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../bessel.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="bessel.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/bessel/mbessel.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/bessel/mbessel.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,481 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Modified Bessel Functions of the First and Second Kinds</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../bessel.html" title="Bessel Functions">
+<link rel="prev" href="bessel.html" title="Bessel Functions of the First and Second Kinds">
+<link rel="next" href="sph_bessel.html" title="Spherical Bessel Functions of the First and Second Kinds">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="bessel.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../bessel.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sph_bessel.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.bessel.mbessel"></a><a href="mbessel.html" title="Modified Bessel Functions of the First and Second Kinds"> Modified Bessel
+ Functions of the First and Second Kinds</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.bessel.mbessel.synopsis"></a><h5>
+<a name="id671789"></a>
+ Synopsis
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">cyl_bessel_i</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">cyl_bessel_i</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">cyl_bessel_k</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">cyl_bessel_k</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<a name="math_toolkit.special.bessel.mbessel.description"></a><h5>
+<a name="id672300"></a>
+ Description
+ </h5>
+<p>
+ The functions cyl_bessel_i
+ and cyl_bessel_k
+ return the result of the modified Bessel functions of the first and second
+ kind respectively:
+ </p>
+<p>
+ cyl_bessel_i(v, x) = I<sub>v</sub>(x)
+ </p>
+<p>
+ cyl_bessel_k(v, x) = K<sub>v</sub>(x)
+ </p>
+<p>
+ where:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel2.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel3.png"></span>
+ </p>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when T1 and T2 are different types.
+ The functions are also optimised for the relatively common case that T1
+ is an integer.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ The functions return the result of domain_error
+ whenever the result is undefined or complex. For cyl_bessel_j
+ this occurs when <code class="computeroutput"><span class="identifier">x</span> <span class="special">&lt;</span>
+ <span class="number">0</span></code> and v is not an integer, or when
+ <code class="computeroutput"><span class="identifier">x</span> <span class="special">==</span>
+ <span class="number">0</span></code> and <code class="computeroutput"><span class="identifier">v</span>
+ <span class="special">!=</span> <span class="number">0</span></code>.
+ For cyl_neumann
+ this occurs when <code class="computeroutput"><span class="identifier">x</span> <span class="special">&lt;=</span>
+ <span class="number">0</span></code>.
+ </p>
+<p>
+ The following graph illustrates the exponential behaviour of I<sub>v</sub>.
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/bessel_i.png" alt="bessel_i"></span>
+ </p>
+<p>
+ The following graph illustrates the exponential decay of K<sub>v</sub>.
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/bessel_k.png" alt="bessel_k"></span>
+ </p>
+<a name="math_toolkit.special.bessel.mbessel.testing"></a><h5>
+<a name="id672660"></a>
+ Testing
+ </h5>
+<p>
+ There are two sets of test values: spot values calculated using functions.wolfram.com, and a
+ much larger set of tests computed using a simplified version of this implementation
+ (with all the special case handling removed).
+ </p>
+<a name="math_toolkit.special.bessel.mbessel.accuracy"></a><h5>
+<a name="id672699"></a>
+ Accuracy
+ </h5>
+<p>
+ The following tables show how the accuracy of these functions varies on
+ various platforms, along with a comparison to the GSL-1.9
+ library. Note that only results for the widest floating-point type on the
+ system are given, as narrower types have <a href="../../backgrounders/relative_error.html#zero_error">effectively
+ zero error</a>. All values are relative errors in units of epsilon.
+ </p>
+<div class="table">
+<a name="id672739"></a><p class="title"><b>Table 31. Errors Rates in cyl_bessel_i</b></p>
+<div class="table-contents"><table class="table" summary="Errors Rates in cyl_bessel_i">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ I<sub>v</sub>
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32 / Visual C++ 8.0
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=10 Mean=3.4 GSL Peak=6000
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux IA64 / G++ 3.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=11 Mean=3
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ SUSE Linux AMD64 / G++ 4.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=11 Mean=4
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HP-UX / HP aCC 6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=15 Mean=4
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id672894"></a><p class="title"><b>Table 32. Errors Rates in cyl_bessel_k</b></p>
+<div class="table-contents"><table class="table" summary="Errors Rates in cyl_bessel_k">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ K<sub>v</sub>
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32 / Visual C++ 8.0
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=9 Mean=2
+ </p>
+ <p>
+ GSL Peak=9
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux IA64 / G++ 3.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=10 Mean=2
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ SUSE Linux AMD64 / G++ 4.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=10 Mean=2
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HP-UX / HP aCC 6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=12 Mean=5
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><a name="math_toolkit.special.bessel.mbessel.implementation"></a><h5>
+<a name="id673062"></a>
+ Implementation
+ </h5>
+<p>
+ The following are handled as special cases first:
+ </p>
+<p>
+ When computing I<sub>v</sub> for <span class="emphasis"><em>x &lt; 0</em></span>, then &#957; must be an integer
+ or a domain error occurs. If &#957; is an integer, then the function is odd if
+ &#957; is odd and even if &#957; is even, and we can reflect to <span class="emphasis"><em>x &gt; 0</em></span>.
+ </p>
+<p>
+ For I<sub>v</sub> with v equal to 0, 1 or 0.5 are handled as special cases.
+ </p>
+<p>
+ The 0 and 1 cases use minimax rational approximations on finite and infinite
+ intervals. The coefficients are from:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ J.M. Blair and C.A. Edwards, <span class="emphasis"><em>Stable rational minimax approximations
+ to the modified Bessel functions I_0(x) and I_1(x)</em></span>, Atomic
+ Energy of Canada Limited Report 4928, Chalk River, 1974.
+ </li>
+<li>
+ S. Moshier, <span class="emphasis"><em>Methods and Programs for Mathematical Functions</em></span>,
+ Ellis Horwood Ltd, Chichester, 1989.
+ </li>
+</ul></div>
+<p>
+ While the 0.5 case is a simple trigonometric function:
+ </p>
+<p>
+ I<sub>0.5</sub>(x) = sqrt(2 / &#960;x) * sinh(x)
+ </p>
+<p>
+ For K<sub>v</sub> with <span class="emphasis"><em>v</em></span> an integer, the result is calculated
+ using the recurrence relation:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel5.png"></span>
+ </p>
+<p>
+ starting from K<sub>0</sub> and K<sub>1</sub> which are calculated using rational the approximations
+ above. These rational approximations are accurate to around 19 digits,
+ and are therefore only used when T has no more than 64 binary digits of
+ precision.
+ </p>
+<p>
+ In the general case, we first normalize &#957; to [<code class="literal">0, [inf</code>])
+ with the help of the reflection formulae:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel9.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel10.png"></span>
+ </p>
+<p>
+ Let &#956; = &#957; - floor(&#957; + 1/2), then &#956; is the fractional part of &#957; such that |&#956;| &lt;=
+ 1/2 (we need this for convergence later). The idea is to calculate K<sub>&#956;</sub>(x)
+ and K<sub>&#956;+1</sub>(x), and use them to obtain I<sub>&#957;</sub>(x) and K<sub>&#957;</sub>(x).
+ </p>
+<p>
+ The algorithm is proposed by Temme in N.M. Temme, <span class="emphasis"><em>On the numerical
+ evaluation of the modified bessel function of the third kind</em></span>,
+ Journal of Computational Physics, vol 19, 324 (1975), which needs two continued
+ fractions as well as the Wronskian:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel11.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel12.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel8.png"></span>
+ </p>
+<p>
+ The continued fractions are computed using the modified Lentz's method
+ (W.J. Lentz, <span class="emphasis"><em>Generating Bessel functions in Mie scattering calculations
+ using continued fractions</em></span>, Applied Optics, vol 15, 668 (1976)).
+ Their convergence rates depend on <span class="emphasis"><em>x</em></span>, therefore we
+ need different strategies for large <span class="emphasis"><em>x</em></span> and small <span class="emphasis"><em>x</em></span>.
+ </p>
+<p>
+ <span class="emphasis"><em>x &gt; v</em></span>, CF1 needs O(<span class="emphasis"><em>x</em></span>) iterations
+ to converge, CF2 converges rapidly.
+ </p>
+<p>
+ <span class="emphasis"><em>x &lt;= v</em></span>, CF1 converges rapidly, CF2 fails to converge
+ when <span class="emphasis"><em>x</em></span> <code class="literal">-&gt;</code> 0.
+ </p>
+<p>
+ When <span class="emphasis"><em>x</em></span> is large (<span class="emphasis"><em>x</em></span> &gt; 2), both
+ continued fractions converge (CF1 may be slow for really large <span class="emphasis"><em>x</em></span>).
+ K<sub>&#956;</sub> and K<sub>&#956;+1</sub>
+can be calculated by
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel13.png"></span>
+ </p>
+<p>
+ where
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel14.png"></span>
+ </p>
+<p>
+ <span class="emphasis"><em>S</em></span> is also a series that is summed along with CF2,
+ see I.J. Thompson and A.R. Barnett, <span class="emphasis"><em>Modified Bessel functions
+ I_v and K_v of real order and complex argument to selected accuracy</em></span>,
+ Computer Physics Communications, vol 47, 245 (1987).
+ </p>
+<p>
+ When <span class="emphasis"><em>x</em></span> is small (<span class="emphasis"><em>x</em></span> &lt;= 2),
+ CF2 convergence may fail (but CF1 works very well). The solution here is
+ Temme's series:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel15.png"></span>
+ </p>
+<p>
+ where
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/mbessel16.png"></span>
+ </p>
+<p>
+ f<sub>k</sub> and h<sub>k</sub>
+are also computed by recursions (involving gamma functions), but
+ the formulas are a little complicated, readers are referred to N.M. Temme,
+ <span class="emphasis"><em>On the numerical evaluation of the modified Bessel function of
+ the third kind</em></span>, Journal of Computational Physics, vol 19, 324
+ (1975). Note: Temme's series converge only for |&#956;| &lt;= 1/2.
+ </p>
+<p>
+ K<sub>&#957;</sub>(x) is then calculated from the forward recurrence, as is K<sub>&#957;+1</sub>(x). With
+ these two values and f<sub>&#957;</sub>, the Wronskian yields I<sub>&#957;</sub>(x) directly.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="bessel.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../bessel.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sph_bessel.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/bessel/sph_bessel.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/bessel/sph_bessel.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,158 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Spherical Bessel Functions of the First and Second Kinds</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../bessel.html" title="Bessel Functions">
+<link rel="prev" href="mbessel.html" title="Modified Bessel Functions of the First and Second Kinds">
+<link rel="next" href="../ellint.html" title="Elliptic Integrals">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="mbessel.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../bessel.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../ellint.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.bessel.sph_bessel"></a><a href="sph_bessel.html" title="Spherical Bessel Functions of the First and Second Kinds"> Spherical
+ Bessel Functions of the First and Second Kinds</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.bessel.sph_bessel.synopsis"></a><h5>
+<a name="id673740"></a>
+ Synopsis
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">sph_bessel</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">sph_bessel</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">sph_neumann</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">sph_neumann</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<a name="math_toolkit.special.bessel.sph_bessel.description"></a><h5>
+<a name="id674250"></a>
+ Description
+ </h5>
+<p>
+ The functions sph_bessel
+ and sph_neumann
+ return the result of the Spherical Bessel functions of the first and second
+ kinds respectively:
+ </p>
+<p>
+ sph_bessel(v, x) = j<sub>v</sub>(x)
+ </p>
+<p>
+ sph_neumann(v, x) = y<sub>v</sub>(x) = n<sub>v</sub>(x)
+ </p>
+<p>
+ where:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/sbessel2.png"></span>
+ </p>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> for the single argument type T.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ The functions return the result of domain_error
+ whenever the result is undefined or complex: this occurs when <code class="computeroutput"><span class="identifier">x</span> <span class="special">&lt;</span> <span class="number">0</span></code>.
+ </p>
+<p>
+ The j<sub>v</sub> function is cyclic like J<sub>v</sub> but differs in its behaviour at the origin:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/sph_bessel_j.png" alt="sph_bessel_j"></span>
+ </p>
+<p>
+ Likewise y<sub>v</sub> is also cyclic for large x, but tends to -&#8734;
+for small <span class="emphasis"><em>x</em></span>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/sph_bessel_y.png" alt="sph_bessel_y"></span>
+ </p>
+<a name="math_toolkit.special.bessel.sph_bessel.testing"></a><h5>
+<a name="id674501"></a>
+ Testing
+ </h5>
+<p>
+ There are two sets of test values: spot values calculated using functions.wolfram.com, and
+ a much larger set of tests computed using a simplified version of this
+ implementation (with all the special case handling removed).
+ </p>
+<a name="math_toolkit.special.bessel.sph_bessel.accuracy"></a><h5>
+<a name="id674540"></a>
+ Accuracy
+ </h5>
+<p>
+ Other than for some special cases, these functions are computed in terms
+ of cyl_bessel_j
+ and cyl_neumann:
+ refer to these functions for accuracy data.
+ </p>
+<a name="math_toolkit.special.bessel.sph_bessel.implementation"></a><h5>
+<a name="id674590"></a>
+ Implementation
+ </h5>
+<p>
+ Other than error handling and a couple of special cases these functions
+ are implemented directly in terms of their definitions:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/sbessel2.png"></span>
+ </p>
+<p>
+ The special cases occur for:
+ </p>
+<p>
+ j<sub>0</sub>= sinc_pi(x)
+ = sin(x) / x
+ </p>
+<p>
+ and for small <span class="emphasis"><em>x &lt; 1</em></span>, we can use the series:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/sbessel5.png"></span>
+ </p>
+<p>
+ which neatly avoids the problem of calculating 0/0 that can occur with
+ the main definition as x &#8594; 0.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="mbessel.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../bessel.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../ellint.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,52 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Elliptic Integrals</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../special.html" title="Special Functions">
+<link rel="prev" href="bessel/sph_bessel.html" title="Spherical Bessel Functions of the First and Second Kinds">
+<link rel="next" href="ellint/ellint_intro.html" title="Elliptic Integral Overview">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="bessel/sph_bessel.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ellint/ellint_intro.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.special.ellint"></a> Elliptic Integrals
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="ellint/ellint_intro.html"> Elliptic
+ Integral Overview</a></span></dt>
+<dt><span class="section"><a href="ellint/ellint_carlson.html"> Elliptic
+ Integrals - Carlson Form</a></span></dt>
+<dt><span class="section"><a href="ellint/ellint_1.html"> Elliptic Integrals
+ of the First Kind - Legendre Form</a></span></dt>
+<dt><span class="section"><a href="ellint/ellint_2.html"> Elliptic Integrals
+ of the Second Kind - Legendre Form</a></span></dt>
+<dt><span class="section"><a href="ellint/ellint_3.html"> Elliptic Integrals
+ of the Third Kind - Legendre Form</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="bessel/sph_bessel.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ellint/ellint_intro.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint/ellint_1.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint/ellint_1.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,281 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Elliptic Integrals of the First Kind - Legendre Form</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../ellint.html" title="Elliptic Integrals">
+<link rel="prev" href="ellint_carlson.html" title="Elliptic Integrals - Carlson Form">
+<link rel="next" href="ellint_2.html" title="Elliptic Integrals of the Second Kind - Legendre Form">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ellint_carlson.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ellint.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ellint_2.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.ellint.ellint_1"></a><a href="ellint_1.html" title="Elliptic Integrals of the First Kind - Legendre Form"> Elliptic Integrals
+ of the First Kind - Legendre Form</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.ellint.ellint_1.synopsis"></a><h6>
+<a name="id680282"></a>
+ Synopsis
+ </h6>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">ellint_1</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span> <span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_1</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_1</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_1</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">k</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_1</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">k</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.ellint.ellint_1.description"></a><h6>
+<a name="id680847"></a>
+ Description
+ </h6>
+<p>
+ These two functions evaluate the incomplete elliptic integral of the first
+ kind <span class="emphasis"><em>F(&#966;, k)</em></span> and its complete counterpart <span class="emphasis"><em>K(k)
+ = F(&#960;/2, k)</em></span>.
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/ellint_1.png" alt="ellint_1"></span>
+ </p>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when T1 and T2 are different types:
+ when they are the same type then the result is the same type as the arguments.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_1</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_1</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the incomplete elliptic integral of the first kind <span class="emphasis"><em>F(&#966;,
+ k)</em></span>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint2.png"></span>
+ </p>
+<p>
+ Requires -1 &lt;= k &lt;= 1, otherwise returns the result of domain_error.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_1</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">k</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_1</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">k</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the complete elliptic integral of the first kind <span class="emphasis"><em>K(k)</em></span>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint6.png"></span>
+ </p>
+<p>
+ Requires -1 &lt;= k &lt;= 1, otherwise returns the result of domain_error.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<a name="math_toolkit.special.ellint.ellint_1.accuracy"></a><h6>
+<a name="id681495"></a>
+ Accuracy
+ </h6>
+<p>
+ These functions are computed using only basic arithmetic operations, so
+ there isn't much variation in accuracy over differing platforms. Note that
+ only results for the widest floating point type on the system are given
+ as narrower types have effectively zero error.
+ All values are relative errors in units of epsilon.
+ </p>
+<div class="table">
+<a name="id681528"></a><p class="title"><b>Table 34. Errors Rates in the Elliptic Integrals of the
+ First Kind</b></p>
+<div class="table-contents"><table class="table" summary="Errors Rates in the Elliptic Integrals of the
+ First Kind">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ F(&#966;, k)
+ </p>
+ </th>
+<th>
+ <p>
+ K(k)
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32 / Visual C++ 8.0
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=3 Mean=0.8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.8 Mean=0.7
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux / G++ 3.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2.6 Mean=1.7
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2.2 Mean=1.8
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HP-UX / HP aCC 6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4.6 Mean=1.5
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=3.7 Mean=1.5
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><a name="math_toolkit.special.ellint.ellint_1.testing"></a><h6>
+<a name="id681691"></a>
+ Testing
+ </h6>
+<p>
+ The tests use a mixture of spot test values calculated using the online
+ calculator at functions.wolfram.com,
+ and random test data generated using NTL::RR at 1000-bit precision and
+ this implementation.
+ </p>
+<a name="math_toolkit.special.ellint.ellint_1.implementation"></a><h6>
+<a name="id681730"></a>
+ Implementation
+ </h6>
+<p>
+ These functions are implemented in terms of Carlson's integrals using the
+ relations:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint19.png"></span>
+ </p>
+<p>
+ and
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint20.png"></span>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ellint_carlson.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ellint.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ellint_2.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint/ellint_2.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint/ellint_2.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,281 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Elliptic Integrals of the Second Kind - Legendre Form</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../ellint.html" title="Elliptic Integrals">
+<link rel="prev" href="ellint_1.html" title="Elliptic Integrals of the First Kind - Legendre Form">
+<link rel="next" href="ellint_3.html" title="Elliptic Integrals of the Third Kind - Legendre Form">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ellint_1.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ellint.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ellint_3.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.ellint.ellint_2"></a><a href="ellint_2.html" title="Elliptic Integrals of the Second Kind - Legendre Form"> Elliptic Integrals
+ of the Second Kind - Legendre Form</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.ellint.ellint_2.synopsis"></a><h6>
+<a name="id681846"></a>
+ Synopsis
+ </h6>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">ellint_2</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span> <span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_2</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_2</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_2</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">k</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_2</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">k</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.ellint.ellint_2.description"></a><h6>
+<a name="id682410"></a>
+ Description
+ </h6>
+<p>
+ These two functions evaluate the incomplete elliptic integral of the second
+ kind <span class="emphasis"><em>E(&#966;, k)</em></span> and its complete counterpart <span class="emphasis"><em>E(k)
+ = E(&#960;/2, k)</em></span>.
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/ellint_2.png" alt="ellint_2"></span>
+ </p>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when T1 and T2 are different types:
+ when they are the same type then the result is the same type as the arguments.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_2</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_2</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the incomplete elliptic integral of the second kind <span class="emphasis"><em>E(&#966;,
+ k)</em></span>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint3.png"></span>
+ </p>
+<p>
+ Requires -1 &lt;= k &lt;= 1, otherwise returns the result of domain_error.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_2</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">k</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_2</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">k</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the complete elliptic integral of the first kind <span class="emphasis"><em>E(k)</em></span>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint7.png"></span>
+ </p>
+<p>
+ Requires -1 &lt;= k &lt;= 1, otherwise returns the result of domain_error.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<a name="math_toolkit.special.ellint.ellint_2.accuracy"></a><h6>
+<a name="id687324"></a>
+ Accuracy
+ </h6>
+<p>
+ These functions are computed using only basic arithmetic operations, so
+ there isn't much variation in accuracy over differing platforms. Note that
+ only results for the widest floating point type on the system are given
+ as narrower types have effectively zero error.
+ All values are relative errors in units of epsilon.
+ </p>
+<div class="table">
+<a name="id687358"></a><p class="title"><b>Table 35. Errors Rates in the Elliptic Integrals of the
+ Second Kind</b></p>
+<div class="table-contents"><table class="table" summary="Errors Rates in the Elliptic Integrals of the
+ Second Kind">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ F(&#966;, k)
+ </p>
+ </th>
+<th>
+ <p>
+ K(k)
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32 / Visual C++ 8.0
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4.6 Mean=1.2
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=3.5 Mean=1.0
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux / G++ 3.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4.3 Mean=1.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4.6 Mean=1.2
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HP-UX / HP aCC 6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=5.8 Mean=2.2
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=10.8 Mean=2.3
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><a name="math_toolkit.special.ellint.ellint_2.testing"></a><h6>
+<a name="id687521"></a>
+ Testing
+ </h6>
+<p>
+ The tests use a mixture of spot test values calculated using the online
+ calculator at functions.wolfram.com,
+ and random test data generated using NTL::RR at 1000-bit precision and
+ this implementation.
+ </p>
+<a name="math_toolkit.special.ellint.ellint_2.implementation"></a><h6>
+<a name="id687560"></a>
+ Implementation
+ </h6>
+<p>
+ These functions are implemented in terms of Carlson's integrals using the
+ relations:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint21.png"></span>
+ </p>
+<p>
+ and
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint22.png"></span>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ellint_1.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ellint.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ellint_3.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint/ellint_3.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint/ellint_3.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,335 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Elliptic Integrals of the Third Kind - Legendre Form</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../ellint.html" title="Elliptic Integrals">
+<link rel="prev" href="ellint_2.html" title="Elliptic Integrals of the Second Kind - Legendre Form">
+<link rel="next" href="../powers.html" title="Logs, Powers, Roots and Exponentials">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ellint_2.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ellint.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../powers.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.ellint.ellint_3"></a><a href="ellint_3.html" title="Elliptic Integrals of the Third Kind - Legendre Form"> Elliptic Integrals
+ of the Third Kind - Legendre Form</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.ellint.ellint_3.synopsis"></a><h6>
+<a name="id687676"></a>
+ Synopsis
+ </h6>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">ellint_3</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span> <span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_3</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">phi</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_3</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">phi</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_3</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">n</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_3</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.ellint.ellint_3.description"></a><h6>
+<a name="id688377"></a>
+ Description
+ </h6>
+<p>
+ These two functions evaluate the incomplete elliptic integral of the third
+ kind <span class="emphasis"><em>&#928;(n, &#966;, k)</em></span> and its complete counterpart <span class="emphasis"><em>&#928;(n,
+ k) = E(n, &#960;/2, k)</em></span>.
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/ellint_3.png" alt="ellint_3"></span>
+ </p>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when the arguments are of different
+ types: when they are the same type then the result is the same type as
+ the arguments.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_3</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">phi</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_3</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">phi</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the incomplete elliptic integral of the third kind <span class="emphasis"><em>&#928;(n,
+ &#966;, k)</em></span>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint4.png"></span>
+ </p>
+<p>
+ Requires <span class="emphasis"><em>-1 &lt;= k &lt;= 1</em></span> and <span class="emphasis"><em>n &lt; 1/sin<sup>2</sup>(&#966;)</em></span>,
+ otherwise returns the result of domain_error
+ (outside this range the result would be complex).
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ In addition, the region where <span class="emphasis"><em>n &gt; 1</em></span> and &#966; <span class="emphasis"><em>is
+ not in the range</em></span> [0, &#960;/2] is currently unsupported and returns
+ the result of domain_error. For this
+ reason it is recomended that you keep &#966; inside its "natural"
+ range of [0, &#960;/2].
+ </p></td></tr>
+</table></div>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_3</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">n</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_3</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the complete elliptic integral of the first kind <span class="emphasis"><em>&#928;(n,
+ k)</em></span>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint8.png"></span>
+ </p>
+<p>
+ Requires <span class="emphasis"><em>-1 &lt;= k &lt;= 1</em></span> and <span class="emphasis"><em>n &lt; 1</em></span>,
+ otherwise returns the result of domain_error
+ (outside this range the result would be complex).
+ </p>
+<p>
+ [opitonal_policy]
+ </p>
+<a name="math_toolkit.special.ellint.ellint_3.accuracy"></a><h6>
+<a name="id689208"></a>
+ Accuracy
+ </h6>
+<p>
+ These functions are computed using only basic arithmetic operations, so
+ there isn't much variation in accuracy over differing platforms. Note that
+ only results for the widest floating point type on the system are given
+ as narrower types have effectively zero error.
+ All values are relative errors in units of epsilon.
+ </p>
+<div class="table">
+<a name="id689242"></a><p class="title"><b>Table 36. Errors Rates in the Elliptic Integrals of the
+ Third Kind</b></p>
+<div class="table-contents"><table class="table" summary="Errors Rates in the Elliptic Integrals of the
+ Third Kind">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ &#928;(n, &#966;, k)
+ </p>
+ </th>
+<th>
+ <p>
+ &#928;(n, k)
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32 / Visual C++ 8.0
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=29 Mean=2.2
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=3 Mean=0.8
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux / G++ 3.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=14 Mean=1.3
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2.3 Mean=0.8
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HP-UX / HP aCC 6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=10 Mean=1.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4.2 Mean=1.1
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><a name="math_toolkit.special.ellint.ellint_3.testing"></a><h6>
+<a name="id689405"></a>
+ Testing
+ </h6>
+<p>
+ The tests use a mixture of spot test values calculated using the online
+ calculator at functions.wolfram.com,
+ and random test data generated using NTL::RR at 1000-bit precision and
+ this implementation.
+ </p>
+<a name="math_toolkit.special.ellint.ellint_3.implementation"></a><h6>
+<a name="id689444"></a>
+ Implementation
+ </h6>
+<p>
+ The implementation for &#928;(n, &#966;, k) first siphons off the special cases:
+ </p>
+<p>
+ <span class="emphasis"><em>&#928;(0, &#966;, k) = F(&#966;, k)</em></span>
+ </p>
+<p>
+ <span class="emphasis"><em>&#928;(n, &#960;/2, k) = &#928;(n, k)</em></span>
+ </p>
+<p>
+ and
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint23.png"></span>
+ </p>
+<p>
+ Then if n &lt; 0 the relations (A&amp;S 17.7.15/16):
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint24.png"></span>
+ </p>
+<p>
+ are used to shift <span class="emphasis"><em>n</em></span> to the range [0, 1].
+ </p>
+<p>
+ Then the relations:
+ </p>
+<p>
+ <span class="emphasis"><em>&#928;(n, -&#966;, k) = -&#928;(n, &#966;, k)</em></span>
+ </p>
+<p>
+ <span class="emphasis"><em>&#928;(n, &#966;+m&#960;, k) = &#928;(n, &#966;, k) + 2m&#928;(n, k)</em></span>
+ </p>
+<p>
+ are used to move &#966; to the range [0, &#960;/2].
+ </p>
+<p>
+ The functions are then implemented in terms of Carlson's integrals using
+ the relations:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint25.png"></span>
+ </p>
+<p>
+ and
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint26.png"></span>
+ </p>
+<p>
+ The remaining problem area occurs when n &gt; 1 and &#966; is outside the range
+ [0, &#960;/2]. In this range the reduction formula for large &#966; can no longer be
+ applied. Likewise the identities 17.7.7/8 in A&amp;S for reducing n to
+ the range [0,1] appear to be no longer applicable.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ellint_2.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ellint.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../powers.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint/ellint_carlson.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint/ellint_carlson.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,480 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Elliptic Integrals - Carlson Form</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../ellint.html" title="Elliptic Integrals">
+<link rel="prev" href="ellint_intro.html" title="Elliptic Integral Overview">
+<link rel="next" href="ellint_1.html" title="Elliptic Integrals of the First Kind - Legendre Form">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ellint_intro.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ellint.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ellint_1.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.ellint.ellint_carlson"></a><a href="ellint_carlson.html" title="Elliptic Integrals - Carlson Form"> Elliptic
+ Integrals - Carlson Form</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.ellint.ellint_carlson.synopsis"></a><h6>
+<a name="id676162"></a>
+ Synopsis
+ </h6>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">ellint_rf</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span> <span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_rf</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">z</span><span class="special">)</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_rf</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;)</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">ellint_rd</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span> <span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_rd</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">z</span><span class="special">)</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_rd</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;)</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">ellint_rj</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span> <span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_rj</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">T4</span> <span class="identifier">p</span><span class="special">)</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_rj</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">T4</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;)</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">ellint_rc</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span> <span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_rc</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">)</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_rc</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;)</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.ellint.ellint_carlson.description"></a><h6>
+<a name="id677942"></a>
+ Description
+ </h6>
+<p>
+ These functions return Carlson's symmetrical elliptic integrals, the functions
+ have complicated behavior over all their possible domains, but the following
+ graph gives an idea of their behavior:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/ellint_c.png" alt="ellint_c"></span>
+ </p>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when the arguments are of different
+ types: otherwise the return is the same type as the arguments.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_rf</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">z</span><span class="special">)</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_rf</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;)</span>
+</pre>
+<p>
+ Returns Carlson's Elliptic Integral R<sub>F</sub>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint9.png"></span>
+ </p>
+<p>
+ Requires that all of the arguments are non-negative, and at most one may
+ be zero. Otherwise returns the result of domain_error.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_rd</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">z</span><span class="special">)</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_rd</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;)</span>
+</pre>
+<p>
+ Returns Carlson's elliptic integral R<sub>D</sub>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint10.png"></span>
+ </p>
+<p>
+ Requires that x and y are non-negative, with at most one of them zero,
+ and that z &gt;= 0. Otherwise returns the result of domain_error.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_rj</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">T4</span> <span class="identifier">p</span><span class="special">)</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_rj</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">T4</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;)</span>
+</pre>
+<p>
+ Returns Carlson's elliptic integral R<sub>J</sub>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint11.png"></span>
+ </p>
+<p>
+ Requires that x, y and z are non-negative, with at most one of them zero,
+ and that <span class="emphasis"><em>p != 0</em></span>. Otherwise returns the result of
+ domain_error.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ When <span class="emphasis"><em>p &lt; 0</em></span> the function returns the <a href="http://en.wikipedia.org/wiki/Cauchy_principal_value" target="_top">Cauchy
+ principal value</a> using the relation:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint17.png"></span>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_rc</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">)</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ellint_rc</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;)</span>
+</pre>
+<p>
+ Returns Carlson's elliptic integral R<sub>C</sub>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint12.png"></span>
+ </p>
+<p>
+ Requires that <span class="emphasis"><em>x &gt; 0</em></span> and that <span class="emphasis"><em>y != 0</em></span>.
+ Otherwise returns the result of domain_error.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ When <span class="emphasis"><em>y &lt; 0</em></span> the function returns the <a href="http://mathworld.wolfram.com/CauchyPrincipalValue.html" target="_top">Cauchy
+ principal value</a> using the relation:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint18.png"></span>
+ </p>
+<a name="math_toolkit.special.ellint.ellint_carlson.testing"></a><h6>
+<a name="id679701"></a>
+ Testing
+ </h6>
+<p>
+ There are two sets of tests.
+ </p>
+<p>
+ Spot tests compare selected values with test data given in:
+ </p>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ B. C. Carlson, <span class="emphasis"><em><a href="http://arxiv.org/abs/math.CA/9409227" target="_top">Numerical
+ computation of real or complex elliptic integrals</a></em></span>.
+ Numerical Algorithms, Volume 10, Number 1 / March, 1995, pp 13-26.
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<p>
+ Random test data generated using NTL::RR at 1000-bit precision and our
+ implementation checks for rounding-errors and/or regressions.
+ </p>
+<p>
+ There are also sanity checks that use the inter-relations between the integrals
+ to verify their correctness: see the above Carlson paper for details.
+ </p>
+<a name="math_toolkit.special.ellint.ellint_carlson.accuracy"></a><h6>
+<a name="id679771"></a>
+ Accuracy
+ </h6>
+<p>
+ These functions are computed using only basic arithmetic operations, so
+ there isn't much variation in accuracy over differing platforms. Note that
+ only results for the widest floating-point type on the system are given
+ as narrower types have effectively zero error.
+ All values are relative errors in units of epsilon.
+ </p>
+<div class="table">
+<a name="id679806"></a><p class="title"><b>Table 33. Errors Rates in the Carlson Elliptic Integrals</b></p>
+<div class="table-contents"><table class="table" summary="Errors Rates in the Carlson Elliptic Integrals">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ R<sub>F</sub>
+ </p>
+ </th>
+<th>
+ <p>
+ R<sub>D</sub>
+ </p>
+ </th>
+<th>
+ <p>
+ R<sub>J</sub>
+ </p>
+ </th>
+<th>
+ <p>
+ R<sub>C</sub>
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32 / Visual C++ 8.0
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2.9 Mean=0.75
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2.6 Mean=0.9
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=108 Mean=6.9
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2.4 Mean=0.6
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux / G++ 3.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2.5 Mean=0.75
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2.7 Mean=0.9
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=105 Mean=8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.9 Mean=0.7
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HP-UX / HP aCC 6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=5.3 Mean=1.6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2.9 Mean=0.99
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=180 Mean=12
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.8 Mean=0.7
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><a name="math_toolkit.special.ellint.ellint_carlson.implementation"></a><h6>
+<a name="id680036"></a>
+ Implementation
+ </h6>
+<p>
+ The key of Carlson's algorithm [Carlson79]
+ is the duplication theorem:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint13.png"></span>
+ </p>
+<p>
+ By applying it repeatedly, <span class="emphasis"><em>x</em></span>, <span class="emphasis"><em>y</em></span>,
+ <span class="emphasis"><em>z</em></span> get closer and closer. When they are nearly equal,
+ the special case equation
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint16.png"></span>
+ </p>
+<p>
+ is used. More specifically, <span class="emphasis"><em>[R F</em></span>] is evaluated from
+ a Taylor series expansion to the fifth order. The calculations of the other
+ three integrals are analogous.
+ </p>
+<p>
+ For <span class="emphasis"><em>p &lt; 0</em></span> in <span class="emphasis"><em>R<sub>J</sub>(x, y, z, p)</em></span>
+ and <span class="emphasis"><em>y &lt; 0</em></span> in <span class="emphasis"><em>R<sub>C</sub>(x, y)</em></span>, the
+ integrals are singular and their <a href="http://mathworld.wolfram.com/CauchyPrincipalValue.html" target="_top">Cauchy
+ principal values</a> are returned via the relations:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint17.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint18.png"></span>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ellint_intro.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ellint.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ellint_1.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint/ellint_intro.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/ellint/ellint_intro.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,419 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Elliptic Integral Overview</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../ellint.html" title="Elliptic Integrals">
+<link rel="prev" href="../ellint.html" title="Elliptic Integrals">
+<link rel="next" href="ellint_carlson.html" title="Elliptic Integrals - Carlson Form">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../ellint.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ellint.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ellint_carlson.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.ellint.ellint_intro"></a><a href="ellint_intro.html" title="Elliptic Integral Overview"> Elliptic
+ Integral Overview</a>
+</h4></div></div></div>
+<p>
+ The main reference for the elliptic integrals is:
+ </p>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ M. Abramowitz and I. A. Stegun (Eds.) (1964) Handbook of Mathematical
+ Functions with Formulas, Graphs, and Mathematical Tables, National
+ Bureau of Standards Applied Mathematics Series, U.S. Government Printing
+ Office, Washington, D.C.
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<p>
+ Mathworld also contain a lot of useful background information:
+ </p>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ <a href="http://mathworld.wolfram.com/EllipticIntegral.html" target="_top">Weisstein,
+ Eric W. "Elliptic Integral." From MathWorld--A Wolfram Web
+ Resource.</a>
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<p>
+ As does <a href="http://en.wikipedia.org/wiki/Elliptic_integral" target="_top">Wikipedia
+ Elliptic integral</a>.
+ </p>
+<a name="math_toolkit.special.ellint.ellint_intro.notation"></a><h5>
+<a name="id674819"></a>
+ Notation
+ </h5>
+<p>
+ All variables are real numbers unless otherwise noted.
+ </p>
+<a name="ellint_def"></a><a name="math_toolkit.special.ellint.ellint_intro.definition"></a><h5>
+<a name="id674855"></a>
+ Definition
+ </h5>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint1.png"></span>
+ </p>
+<p>
+ is called elliptic integral if <span class="emphasis"><em>R(t, s)</em></span> is a rational
+ function of <span class="emphasis"><em>t</em></span> and <span class="emphasis"><em>s</em></span>, and <span class="emphasis"><em>s<sup>2</sup></em></span>
+ is a cubic or quartic polynomial in <span class="emphasis"><em>t</em></span>.
+ </p>
+<p>
+ Elliptic integrals generally can not be expressed in terms of elementary
+ functions. However, Legendre showed that all elliptic integrals can be
+ reduced to the following three canonical forms:
+ </p>
+<p>
+ Elliptic Integral of the First Kind (Legendre form)
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint2.png"></span>
+ </p>
+<p>
+ Elliptic Integral of the Second Kind (Legendre form)
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint3.png"></span>
+ </p>
+<p>
+ Elliptic Integral of the Third Kind (Legendre form)
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint4.png"></span>
+ </p>
+<p>
+ where
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint5.png"></span>
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ <span class="emphasis"><em>&#966;</em></span> is called the amplitude.
+ </p>
+<p>
+ <span class="emphasis"><em>k</em></span> is called the modulus.
+ </p>
+<p>
+ <span class="emphasis"><em>&#945;</em></span> is called the modular angle.
+ </p>
+<p>
+ <span class="emphasis"><em>n</em></span> is called the characteristic.
+ </p>
+</td></tr>
+</table></div>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ Perhaps more than any other special functions the elliptic integrals
+ are expressed in a variety of different ways. In particular, the final
+ parameter <span class="emphasis"><em>k</em></span> (the modulus) may be expressed using
+ a modular angle &#945;, or a parameter <span class="emphasis"><em>m</em></span>. These are related
+ by:
+ </p>
+<p>
+ k = sin&#945;
+ </p>
+<p>
+ m = k<sup>2</sup> = sin<sup>2</sup>&#945;
+ </p>
+<p>
+ So that the integral of the third kind (for example) may be expressed
+ as either:
+ </p>
+<p>
+ &#928;(n, &#966;, k)
+ </p>
+<p>
+ &#928;(n, &#966; \ &#945;)
+ </p>
+<p>
+ &#928;(n, &#966;| m)
+ </p>
+<p>
+ To further complicate matters, some texts refer to the <span class="emphasis"><em>complement
+ of the parameter m</em></span>, or 1 - m, where:
+ </p>
+<p>
+ 1 - m = 1 - k<sup>2</sup> = cos<sup>2</sup>&#945;
+ </p>
+<p>
+ This implementation uses <span class="emphasis"><em>k</em></span> throughout: this matches
+ the requirements of the <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf" target="_top">Technical
+ Report on C++ Library Extensions</a>. However, you should be extra
+ careful when using these functions!
+ </p>
+</td></tr>
+</table></div>
+<p>
+ When <span class="emphasis"><em>&#966;</em></span> = <span class="emphasis"><em>&#960;</em></span> / 2, the elliptic integrals
+ are called <span class="emphasis"><em>complete</em></span>.
+ </p>
+<p>
+ Complete Elliptic Integral of the First Kind (Legendre form)
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint6.png"></span>
+ </p>
+<p>
+ Complete Elliptic Integral of the Second Kind (Legendre form)
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint7.png"></span>
+ </p>
+<p>
+ Complete Elliptic Integral of the Third Kind (Legendre form)
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint8.png"></span>
+ </p>
+<p>
+ Carlson [Carlson77] [Carlson78] gives an alternative definition
+ of elliptic integral's canonical forms:
+ </p>
+<p>
+ Carlson's Elliptic Integral of the First Kind
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint9.png"></span>
+ </p>
+<p>
+ where <span class="emphasis"><em>x</em></span>, <span class="emphasis"><em>y</em></span>, <span class="emphasis"><em>z</em></span>
+ are nonnegative and at most one of them may be zero.
+ </p>
+<p>
+ Carlson's Elliptic Integral of the Second Kind
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint10.png"></span>
+ </p>
+<p>
+ where <span class="emphasis"><em>x</em></span>, <span class="emphasis"><em>y</em></span> are nonnegative, at
+ most one of them may be zero, and <span class="emphasis"><em>z</em></span> must be positive.
+ </p>
+<p>
+ Carlson's Elliptic Integral of the Third Kind
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint11.png"></span>
+ </p>
+<p>
+ where <span class="emphasis"><em>x</em></span>, <span class="emphasis"><em>y</em></span>, <span class="emphasis"><em>z</em></span>
+ are nonnegative, at most one of them may be zero, and <span class="emphasis"><em>p</em></span>
+ must be nonzero.
+ </p>
+<p>
+ Carlson's Degenerate Elliptic Integral
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint12.png"></span>
+ </p>
+<p>
+ where <span class="emphasis"><em>x</em></span> is nonnegative and <span class="emphasis"><em>y</em></span>
+ is nonzero.
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ <span class="emphasis"><em>R<sub>C</sub>(x, y) = R<sub>F</sub>(x, y, y)</em></span>
+ </p>
+<p>
+ <span class="emphasis"><em>R<sub>D</sub>(x, y, z) = R<sub>J</sub>(x, y, z, z)</em></span>
+ </p>
+</td></tr>
+</table></div>
+<a name="ellint_theorem"></a><a name="math_toolkit.special.ellint.ellint_intro.duplication_theorem"></a><h5>
+<a name="id675611"></a>
+ <a href="ellint_intro.html#math_toolkit.special.ellint.ellint_intro.duplication_theorem">Duplication
+ Theorem</a>
+ </h5>
+<p>
+ Carlson proved in [Carlson78]
+ that
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint13.png"></span>
+ </p>
+<a name="ellint_formula"></a><a name="math_toolkit.special.ellint.ellint_intro.carlson_s_formulas"></a><h5>
+<a name="id675686"></a>
+ <a href="ellint_intro.html#math_toolkit.special.ellint.ellint_intro.carlson_s_formulas">Carlson's
+ Formulas</a>
+ </h5>
+<p>
+ The Legendre form and Carlson form of elliptic integrals are related by
+ equations:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint14.png"></span>
+ </p>
+<p>
+ In particular,
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ellint15.png"></span>
+ </p>
+<a name="math_toolkit.special.ellint.ellint_intro.numerical_algorithms"></a><h5>
+<a name="id675781"></a>
+ <a href="ellint_intro.html#math_toolkit.special.ellint.ellint_intro.numerical_algorithms">Numerical
+ Algorithms</a>
+ </h5>
+<p>
+ The conventional methods for computing elliptic integrals are Gauss and
+ Landen transformations, which converge quadratically and work well for
+ elliptic integrals of the first and second kinds. Unfortunately they suffer
+ from loss of significant digits for the third kind. Carlson's algorithm
+ [Carlson79] [Carlson78],
+ by contrast, provides a unified method for all three kinds of elliptic
+ integrals with satisfactory precisions.
+ </p>
+<a name="ellint_refs"></a><a name="math_toolkit.special.ellint.ellint_intro.references"></a><h5>
+<a name="id675843"></a>
+ References
+ </h5>
+<p>
+ Special mention goes to:
+ </p>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ A. M. Legendre, <span class="emphasis"><em>Traitd des Fonctions Elliptiques et des Integrales
+ Euleriennes</em></span>, Vol. 1. Paris (1825).
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<p>
+ However the main references are:
+ </p>
+<a name="ellint_ref_AS"></a><a name="ellint_ref_carlson79"></a><a name="ellint_ref_carlson77"></a><a name="ellint_ref_carlson78"></a><a name="ellint_ref_carlson81"></a><div class="orderedlist"><ol type="1">
+<li>
+ M. Abramowitz and I. A. Stegun (Eds.) (1964) Handbook of Mathematical
+ Functions with Formulas, Graphs, and Mathematical Tables, National Bureau
+ of Standards Applied Mathematics Series, U.S. Government Printing Office,
+ Washington, D.C.
+ </li>
+<li>
+ B.C. Carlson, <span class="emphasis"><em>Computing elliptic integrals by duplication</em></span>,
+ Numerische Mathematik, vol 33, 1 (1979).
+ </li>
+<li>
+ B.C. Carlson, <span class="emphasis"><em>Elliptic Integrals of the First Kind</em></span>,
+ SIAM Journal on Mathematical Analysis, vol 8, 231 (1977).
+ </li>
+<li>
+ B.C. Carlson, <span class="emphasis"><em>Short Proofs of Three Theorems on Elliptic Integrals</em></span>,
+ SIAM Journal on Mathematical Analysis, vol 9, 524 (1978).
+ </li>
+<li>
+ B.C. Carlson and E.M. Notis, <span class="emphasis"><em>ALGORITHM 577: Algorithms for
+ Incomplete Elliptic Integrals</em></span>, ACM Transactions on Mathematmal
+ Software, vol 7, 398 (1981).
+ </li>
+<li>
+ B. C. Carlson, <span class="emphasis"><em>On computing elliptic integrals and functions</em></span>.
+ J. Math. and Phys., 44 (1965), pp. 36-51.
+ </li>
+<li>
+ B. C. Carlson, <span class="emphasis"><em>A table of elliptic integrals of the second
+ kind</em></span>. Math. Comp., 49 (1987), pp. 595-606. (Supplement, ibid.,
+ pp. S13-S17.)
+ </li>
+<li>
+ B. C. Carlson, <span class="emphasis"><em>A table of elliptic integrals of the third kind</em></span>.
+ Math. Comp., 51 (1988), pp. 267-280. (Supplement, ibid., pp. S1-S5.)
+ </li>
+<li>
+ B. C. Carlson, <span class="emphasis"><em>A table of elliptic integrals: cubic cases</em></span>.
+ Math. Comp., 53 (1989), pp. 327-333.
+ </li>
+<li>
+ B. C. Carlson, <span class="emphasis"><em>A table of elliptic integrals: one quadratic
+ factor</em></span>. Math. Comp., 56 (1991), pp. 267-280.
+ </li>
+<li>
+ B. C. Carlson, <span class="emphasis"><em>A table of elliptic integrals: two quadratic
+ factors</em></span>. Math. Comp., 59 (1992), pp. 165-180.
+ </li>
+<li>
+ B. C. Carlson, <span class="emphasis"><em><a href="http://arxiv.org/abs/math.CA/9409227" target="_top">Numerical
+ computation of real or complex elliptic integrals</a></em></span>.
+ Numerical Algorithms, Volume 10, Number 1 / March, 1995, p13-26.
+ </li>
+<li>
+ B. C. Carlson and John L. Gustafson, <span class="emphasis"><em><a href="http://arxiv.org/abs/math.CA/9310223" target="_top">Asymptotic
+ Approximations for Symmetric Elliptic Integrals</a></em></span>, SIAM
+ Journal on Mathematical Analysis, Volume 25, Issue 2 (March 1994), 288-303.
+ </li>
+</ol></div>
+<p>
+ The following references, while not directly relevent to our implementation,
+ may also be of interest:
+ </p>
+<div class="orderedlist"><ol type="1">
+<li>
+ R. Burlisch, <span class="emphasis"><em>Numerical Compuation of Elliptic Integrals and
+ Elliptic Functions.</em></span> Numerical Mathematik 7, 78-90.
+ </li>
+<li>
+ R. Burlisch, <span class="emphasis"><em>An extension of the Bartky Transformation to Incomplete
+ Elliptic Integrals of the Third Kind</em></span>. Numerical Mathematik
+ 13, 266-284.
+ </li>
+<li>
+ R. Burlisch, <span class="emphasis"><em>Numerical Compuation of Elliptic Integrals and
+ Elliptic Functions. III</em></span>. Numerical Mathematik 13, 305-315.
+ </li>
+<li>
+ T. Fukushima and H. Ishizaki, <span class="emphasis"><em><a href="http://adsabs.harvard.edu/abs/1994CeMDA..59..237F" target="_top">Numerical
+ Computation of Incomplete Elliptic Integrals of a General Form.</a></em></span>
+ Celestial Mechanics and Dynamical Astronomy, Volume 59, Number 3 / July,
+ 1994, 237-251.
+ </li>
+</ol></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../ellint.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ellint.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ellint_carlson.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,52 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Factorials and Binomial Coefficients</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../special.html" title="Special Functions">
+<link rel="prev" href="sf_gamma/gamma_derivatives.html" title="Derivative of the Incomplete Gamma Function">
+<link rel="next" href="factorials/sf_factorial.html" title="Factorial">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_gamma/gamma_derivatives.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="factorials/sf_factorial.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.special.factorials"></a><a href="factorials.html" title="Factorials and Binomial Coefficients"> Factorials and Binomial
+ Coefficients</a>
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"> Factorial</span></dt>
+<dt><span class="section"><a href="factorials/sf_double_factorial.html">
+ Double Factorial</a></span></dt>
+<dt><span class="section"><a href="factorials/sf_rising_factorial.html">
+ Rising Factorial</a></span></dt>
+<dt><span class="section"><a href="factorials/sf_falling_factorial.html">
+ Falling Factorial</a></span></dt>
+<dt><span class="section"><a href="factorials/sf_binomial.html"> Binomial
+ Coefficients</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_gamma/gamma_derivatives.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="factorials/sf_factorial.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials/sf_binomial.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials/sf_binomial.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,121 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Binomial Coefficients</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../factorials.html" title="Factorials and Binomial Coefficients">
+<link rel="prev" href="sf_falling_factorial.html" title="Falling Factorial">
+<link rel="next" href="../sf_beta.html" title="Beta Functions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_falling_factorial.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../factorials.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../sf_beta.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.factorials.sf_binomial"></a><a href="sf_binomial.html" title="Binomial Coefficients"> Binomial
+ Coefficients</a>
+</h4></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">binomial_coefficient</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">k</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">binomial_coefficient</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">k</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ Returns the binomial coefficient: <sub>n</sub>C<sub>k</sub>.
+ </p>
+<p>
+ Requires k &lt;= n.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ May return the result of overflow_error
+ if the result is too large to represent in type T.
+ </p>
+<a name="math_toolkit.special.factorials.sf_binomial.accuracy"></a><h5>
+<a name="id637068"></a>
+ Accuracy
+ </h5>
+<p>
+ The accuracy will be the same as for the factorials for small arguments
+ (i.e. no more than one or two epsilon), and the beta
+ function for larger arguments.
+ </p>
+<a name="math_toolkit.special.factorials.sf_binomial.testing"></a><h5>
+<a name="id637108"></a>
+ Testing
+ </h5>
+<p>
+ The spot tests for the binomial coefficients use data generated by functions.wolfram.com.
+ </p>
+<a name="math_toolkit.special.factorials.sf_binomial.implementation"></a><h5>
+<a name="id637138"></a>
+ Implementation
+ </h5>
+<p>
+ Binomial coefficients are calculated using table lookup of factorials where
+ possible using:
+ </p>
+<p>
+ <sub>n</sub>C<sub>k</sub> = n! / (k!(n-k)!)
+ </p>
+<p>
+ Otherwise it is implemented in terms of the beta function using the relations:
+ </p>
+<p>
+ <sub>n</sub>C<sub>k</sub> = 1 / (k * beta(k,
+ n-k+1))
+ </p>
+<p>
+ and
+ </p>
+<p>
+ <sub>n</sub>C<sub>k</sub> = 1 / ((n-k) * beta(k+1,
+ n-k))
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_falling_factorial.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../factorials.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../sf_beta.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials/sf_double_factorial.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials/sf_double_factorial.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,114 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Double Factorial</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../factorials.html" title="Factorials and Binomial Coefficients">
+<link rel="prev" href="sf_factorial.html" title="Factorial">
+<link rel="next" href="sf_rising_factorial.html" title="Rising Factorial">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_factorial.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../factorials.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sf_rising_factorial.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.factorials.sf_double_factorial"></a><a href="sf_double_factorial.html" title="Double Factorial">
+ Double Factorial</a>
+</h4></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">factorials</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">double_factorial</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">double_factorial</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ Returns <code class="literal">i!!</code>.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ May return the result of overflow_error
+ if the result is too large to represent in type T. The implementation is
+ designed to be optimised for small <span class="emphasis"><em>i</em></span> where table lookup
+ of i! is possible.
+ </p>
+<a name="math_toolkit.special.factorials.sf_double_factorial.accuracy"></a><h5>
+<a name="id635383"></a>
+ Accuracy
+ </h5>
+<p>
+ The implementation uses a trivial adaptation of the factorial function,
+ so error rates should be no more than a couple of epsilon higher.
+ </p>
+<a name="math_toolkit.special.factorials.sf_double_factorial.testing"></a><h5>
+<a name="id635414"></a>
+ Testing
+ </h5>
+<p>
+ The spot tests for the double factorial use data generated by functions.wolfram.com.
+ </p>
+<a name="math_toolkit.special.factorials.sf_double_factorial.implementation"></a><h5>
+<a name="id635446"></a>
+ Implementation
+ </h5>
+<p>
+ The double factorial is implemented in terms of the factorial and gamma
+ functions using the relations:
+ </p>
+<p>
+ (2n)!! = 2<sup>n </sup> * n!
+ </p>
+<p>
+ (2n+1)!! = (2n+1)! / (2<sup>n </sup> n!)
+ </p>
+<p>
+ and
+ </p>
+<p>
+ (2n-1)!! = &#915;((2n+1)/2) * 2<sup>n </sup> / sqrt(pi)
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_factorial.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../factorials.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sf_rising_factorial.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials/sf_factorial.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials/sf_factorial.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,157 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Factorial</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../factorials.html" title="Factorials and Binomial Coefficients">
+<link rel="prev" href="../factorials.html" title="Factorials and Binomial Coefficients">
+<link rel="next" href="sf_double_factorial.html" title="Double Factorial">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../factorials.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../factorials.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sf_double_factorial.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.factorials.sf_factorial"></a> Factorial
+</h4></div></div></div>
+<a name="math_toolkit.special.factorials.sf_factorial.synopsis"></a><h5>
+<a name="id633917"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">factorials</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">factorial</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">factorial</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">unchecked_factorial</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">max_factorial</span><span class="special">;</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.factorials.sf_factorial.description"></a><h5>
+<a name="id634342"></a>
+ Description
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">factorial</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">factorial</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns <code class="literal">i!</code>.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ For <code class="literal">i &lt;= max_factorial&lt;T&gt;::value</code> this is implemented
+ by table lookup, for larger values of <code class="literal">i</code>, this function
+ is implemented in terms of tgamma.
+ </p>
+<p>
+ If <code class="literal">i</code> is so large that the result can not be represented
+ in type T, then calls overflow_error.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">unchecked_factorial</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span><span class="special">);</span>
+</pre>
+<p>
+ Returns <code class="literal">i!</code>.
+ </p>
+<p>
+ Internally this function performs table lookup of the result. Further it
+ performs no range checking on the value of i: it is up to the caller to
+ ensure that <code class="literal">i &lt;= max_factorial&lt;T&gt;::value</code>. This
+ function is intended to be used inside inner loops that require fast table
+ lookup of factorials, but requires care to ensure that argument <code class="literal">i</code>
+ never grows too large.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">max_factorial</span>
+<span class="special">{</span>
+ <span class="keyword">static</span> <span class="keyword">const</span> <span class="keyword">unsigned</span> <span class="identifier">value</span> <span class="special">=</span> <span class="identifier">X</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ This traits class defines the largest value that can be passed to <code class="literal">unchecked_factorial</code>.
+ The member <code class="computeroutput"><span class="identifier">value</span></code> can be
+ used where integral constant expressions are required: for example to define
+ the size of further tables that depend on the factorials.
+ </p>
+<a name="math_toolkit.special.factorials.sf_factorial.accuracy"></a><h5>
+<a name="id634860"></a>
+ Accuracy
+ </h5>
+<p>
+ For arguments smaller than <code class="computeroutput"><span class="identifier">max_factorial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">value</span></code>
+ the result should be correctly rounded. For larger arguments the accuracy
+ will be the same as for tgamma.
+ </p>
+<a name="math_toolkit.special.factorials.sf_factorial.testing"></a><h5>
+<a name="id634932"></a>
+ Testing
+ </h5>
+<p>
+ Basic sanity checks and spot values to verify the data tables: the main
+ tests for the tgamma
+ function handle those cases already.
+ </p>
+<a name="math_toolkit.special.factorials.sf_factorial.implementation"></a><h5>
+<a name="id634973"></a>
+ Implementation
+ </h5>
+<p>
+ The factorial function is table driven for small arguments, and is implemented
+ in terms of tgamma
+ for larger arguments.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../factorials.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../factorials.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sf_double_factorial.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials/sf_falling_factorial.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials/sf_falling_factorial.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,116 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Falling Factorial</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../factorials.html" title="Factorials and Binomial Coefficients">
+<link rel="prev" href="sf_rising_factorial.html" title="Rising Factorial">
+<link rel="next" href="sf_binomial.html" title="Binomial Coefficients">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_rising_factorial.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../factorials.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sf_binomial.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.factorials.sf_falling_factorial"></a><a href="sf_falling_factorial.html" title="Falling Factorial">
+ Falling Factorial</a>
+</h4></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">factorials</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">falling_factorial</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">i</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">falling_factorial</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">i</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ Returns the falling factorial of <span class="emphasis"><em>x</em></span> and <span class="emphasis"><em>i</em></span>:
+ </p>
+<p>
+ falling_factorial(x, i) = x(x-1)(x-2)(x-3)...(x-i+1)
+ </p>
+<p>
+ Note that this function is only defined for positive <span class="emphasis"><em>i</em></span>,
+ hence the <code class="computeroutput"><span class="keyword">unsigned</span></code> second
+ argument. Argument <span class="emphasis"><em>x</em></span> can be either positive or negative
+ however.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ May return the result of overflow_error
+ if the result is too large to represent in type T.
+ </p>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: the type of the result is <code class="computeroutput"><span class="keyword">double</span></code> if T is an integer type, otherwise
+ the type of the result is T.
+ </p>
+<a name="math_toolkit.special.factorials.sf_falling_factorial.accuracy"></a><h5>
+<a name="id636551"></a>
+ Accuracy
+ </h5>
+<p>
+ The accuracy will be the same as the tgamma_delta_ratio
+ function.
+ </p>
+<a name="math_toolkit.special.factorials.sf_falling_factorial.testing"></a><h5>
+<a name="id636590"></a>
+ Testing
+ </h5>
+<p>
+ The spot tests for the falling factorials use data generated by functions.wolfram.com.
+ </p>
+<a name="math_toolkit.special.factorials.sf_falling_factorial.implementation"></a><h5>
+<a name="id636621"></a>
+ Implementation
+ </h5>
+<p>
+ Rising and falling factorials are implemented as ratios of gamma functions
+ using tgamma_delta_ratio.
+ Optimisations for small integer arguments are handled internally by that
+ function.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_rising_factorial.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../factorials.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sf_binomial.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials/sf_rising_factorial.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/factorials/sf_rising_factorial.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,120 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Rising Factorial</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../factorials.html" title="Factorials and Binomial Coefficients">
+<link rel="prev" href="sf_double_factorial.html" title="Double Factorial">
+<link rel="next" href="sf_falling_factorial.html" title="Falling Factorial">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_double_factorial.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../factorials.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sf_falling_factorial.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.factorials.sf_rising_factorial"></a><a href="sf_rising_factorial.html" title="Rising Factorial">
+ Rising Factorial</a>
+</h4></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">factorials</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">rising_factorial</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">i</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">rising_factorial</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">i</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ Returns the rising factorial of <span class="emphasis"><em>x</em></span> and <span class="emphasis"><em>i</em></span>:
+ </p>
+<p>
+ rising_factorial(x, i) = &#915;(x + i) / &#915;(x);
+ </p>
+<p>
+ or
+ </p>
+<p>
+ rising_factorial(x, i) = x(x+1)(x+2)(x+3)...(x+i)
+ </p>
+<p>
+ Note that both <span class="emphasis"><em>x</em></span> and <span class="emphasis"><em>i</em></span> can be
+ negative as well as positive.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ May return the result of overflow_error
+ if the result is too large to represent in type T.
+ </p>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: the type of the result is <code class="computeroutput"><span class="keyword">double</span></code> if T is an integer type, otherwise
+ the type of the result is T.
+ </p>
+<a name="math_toolkit.special.factorials.sf_rising_factorial.accuracy"></a><h5>
+<a name="id635971"></a>
+ Accuracy
+ </h5>
+<p>
+ The accuracy will be the same as the tgamma_delta_ratio
+ function.
+ </p>
+<a name="math_toolkit.special.factorials.sf_rising_factorial.testing"></a><h5>
+<a name="id636009"></a>
+ Testing
+ </h5>
+<p>
+ The spot tests for the rising factorials use data generated by functions.wolfram.com.
+ </p>
+<a name="math_toolkit.special.factorials.sf_rising_factorial.implementation"></a><h5>
+<a name="id636041"></a>
+ Implementation
+ </h5>
+<p>
+ Rising and falling factorials are implemented as ratios of gamma functions
+ using tgamma_delta_ratio.
+ Optimisations for small integer arguments are handled internally by that
+ function.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_double_factorial.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../factorials.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sf_falling_factorial.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/fpclass.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/fpclass.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,223 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Floating Point Classification: Infinities and NaN's</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../special.html" title="Special Functions">
+<link rel="prev" href="inv_hyper/atanh.html" title="atanh">
+<link rel="next" href="../toolkit.html" title="Internal Details and Tools (Experimental)">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="inv_hyper/atanh.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../toolkit.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.special.fpclass"></a><a href="fpclass.html" title="Floating Point Classification: Infinities and NaN's"> Floating Point Classification:
+ Infinities and NaN's</a>
+</h3></div></div></div>
+<a name="math_toolkit.special.fpclass.synopsis"></a><h5>
+<a name="id696573"></a>
+ Synopsis
+ </h5>
+<pre class="programlisting">
+<span class="preprocessor">#define</span> <span class="identifier">FP_ZERO</span> <span class="comment">/* implementation specific value */</span>
+<span class="preprocessor">#define</span> <span class="identifier">FP_NORMAL</span> <span class="comment">/* implementation specific value */</span>
+<span class="preprocessor">#define</span> <span class="identifier">FP_INFINITE</span> <span class="comment">/* implementation specific value */</span>
+<span class="preprocessor">#define</span> <span class="identifier">FP_NAN</span> <span class="comment">/* implementation specific value */</span>
+<span class="preprocessor">#define</span> <span class="identifier">FP_SUBNORMAL</span> <span class="comment">/* implementation specific value */</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">int</span> <span class="identifier">fpclassify</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">t</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">bool</span> <span class="identifier">isfinite</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">bool</span> <span class="identifier">isinf</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">t</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">bool</span> <span class="identifier">isnan</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">t</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">bool</span> <span class="identifier">isnormal</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">t</span><span class="special">);</span>
+</pre>
+<a name="math_toolkit.special.fpclass.description"></a><h5>
+<a name="id697014"></a>
+ Description
+ </h5>
+<p>
+ These functions provide the same functionality as the macros with the same
+ name in C99, indeed if the C99 macros are available, then these functions
+ are implemented in terms of them, otherwise they rely on std::numeric_limits&lt;&gt;
+ to function.
+ </p>
+<p>
+ Note that the definition of these functions <span class="emphasis"><em>does not suppress the
+ definition of these names as macros by math.h</em></span> on those platforms
+ that already provide these as macros. That mean that the following have differing
+ meanings:
+ </p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">;</span>
+
+<span class="comment">// This might call a global macro if defined,
+</span><span class="comment">// but might not work if the type of z is unsupported
+</span><span class="comment">// by the std lib macro:
+</span><span class="identifier">isnan</span><span class="special">(</span><span class="identifier">z</span><span class="special">);</span>
+<span class="comment">//
+</span><span class="comment">// This calls the Boost version
+</span><span class="comment">// (found via the "using namespace boost::math" declaration)
+</span><span class="comment">// it works for any type that has numeric_limits support for type z:
+</span><span class="special">(</span><span class="identifier">isnan</span><span class="special">)(</span><span class="identifier">z</span><span class="special">);</span>
+<span class="comment">//
+</span><span class="comment">// As above but with namespace qualification.
+</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">isnan</span><span class="special">)(</span><span class="identifier">z</span><span class="special">);</span>
+<span class="comment">//
+</span><span class="comment">// This will cause a compiler error is isnan is a native macro:
+</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">isnan</span><span class="special">(</span><span class="identifier">z</span><span class="special">);</span>
+<span class="comment">// So always use (boost::math::isnan)(z); instead.
+</span></pre>
+<p>
+ Detailed descriptions for each of these functions follows:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">int</span> <span class="identifier">fpclassify</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">t</span><span class="special">);</span>
+</pre>
+<p>
+ Returns an integer value that classifies the value <span class="emphasis"><em>t</em></span>:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ fpclassify value
+ </p>
+ </th>
+<th>
+ <p>
+ class of t.
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ FP_ZERO
+ </p>
+ </td>
+<td>
+ <p>
+ If <span class="emphasis"><em>t</em></span> is zero.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ FP_NORMAL
+ </p>
+ </td>
+<td>
+ <p>
+ If <span class="emphasis"><em>t</em></span> is a non-zero, non-denormalised finite
+ value.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ FP_INFINITE
+ </p>
+ </td>
+<td>
+ <p>
+ If <span class="emphasis"><em>t</em></span> is plus or minus infinity.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ FP_NAN
+ </p>
+ </td>
+<td>
+ <p>
+ If <span class="emphasis"><em>t</em></span> is a NaN.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ FP_SUBNORMAL
+ </p>
+ </td>
+<td>
+ <p>
+ If <span class="emphasis"><em>t</em></span> is a denormalised number.
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">bool</span> <span class="identifier">isfinite</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">);</span>
+</pre>
+<p>
+ Returns true only if <span class="emphasis"><em>z</em></span> is not an infinity or a NaN.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">bool</span> <span class="identifier">isinf</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">t</span><span class="special">);</span>
+</pre>
+<p>
+ Returns true only if <span class="emphasis"><em>z</em></span> is plus or minus infinity.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">bool</span> <span class="identifier">isnan</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">t</span><span class="special">);</span>
+</pre>
+<p>
+ Returns true only if <span class="emphasis"><em>z</em></span> is a NaN.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">bool</span> <span class="identifier">isnormal</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">t</span><span class="special">);</span>
+</pre>
+<p>
+ Returns true only if <span class="emphasis"><em>z</em></span> is a normal number (not zero,
+ infinite, NaN, or denormalised).
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="inv_hyper/atanh.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../toolkit.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/inv_hyper.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/inv_hyper.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,47 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Inverse Hyperbolic Functions</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../special.html" title="Special Functions">
+<link rel="prev" href="sinc/sinhc_pi.html" title="sinhc_pi">
+<link rel="next" href="inv_hyper/inv_hyper_over.html" title="Inverse Hyperbolic Functions Overview">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sinc/sinhc_pi.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="inv_hyper/inv_hyper_over.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.special.inv_hyper"></a> Inverse Hyperbolic Functions
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="inv_hyper/inv_hyper_over.html"> Inverse
+ Hyperbolic Functions Overview</a></span></dt>
+<dt><span class="section"> acosh</span></dt>
+<dt><span class="section"> asinh</span></dt>
+<dt><span class="section"> atanh</span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sinc/sinhc_pi.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="inv_hyper/inv_hyper_over.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/inv_hyper/acosh.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/inv_hyper/acosh.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,81 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>acosh</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../inv_hyper.html" title="Inverse Hyperbolic Functions">
+<link rel="prev" href="inv_hyper_over.html" title="Inverse Hyperbolic Functions Overview">
+<link rel="next" href="asinh.html" title="asinh">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="inv_hyper_over.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../inv_hyper.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="asinh.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.inv_hyper.acosh"></a> acosh
+</h4></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">acosh</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">acosh</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">acosh</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Computes the reciprocal of (the restriction to the range of <code class="literal">[0;+&#8734;[</code>)
+ <a href="inv_hyper_over.html" title="Inverse Hyperbolic Functions Overview">the hyperbolic
+ cosine function</a>, at x. Values returned are positive. Generalised
+ Taylor series are used near 1 and Laurent series are used near the infinity
+ to ensure accuracy.
+ </p>
+<p>
+ If x is in the range <code class="literal">]-&#8734;;+1[</code> then returns the result
+ of domain_error.
+ </p>
+<p>
+ The return type of this function is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: the return type is <code class="computeroutput"><span class="keyword">double</span></code> when T is an integer type, and T
+ otherwise.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="inv_hyper_over.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../inv_hyper.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="asinh.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/inv_hyper/asinh.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/inv_hyper/asinh.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,75 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>asinh</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../inv_hyper.html" title="Inverse Hyperbolic Functions">
+<link rel="prev" href="acosh.html" title="acosh">
+<link rel="next" href="atanh.html" title="atanh">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="acosh.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../inv_hyper.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="atanh.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.inv_hyper.asinh"></a> asinh
+</h4></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">asinh</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">asinh</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">asinh</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Computes the reciprocal of <a href="inv_hyper_over.html" title="Inverse Hyperbolic Functions Overview">the
+ hyperbolic sine function</a>. Taylor series are used at the origin and
+ Laurent series are used near the infinity to ensure accuracy.
+ </p>
+<p>
+ The return type of this function is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: the return type is <code class="computeroutput"><span class="keyword">double</span></code> when T is an integer type, and T
+ otherwise.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="acosh.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../inv_hyper.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="atanh.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/inv_hyper/atanh.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/inv_hyper/atanh.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,89 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>atanh</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../inv_hyper.html" title="Inverse Hyperbolic Functions">
+<link rel="prev" href="asinh.html" title="asinh">
+<link rel="next" href="../fpclass.html" title="Floating Point Classification: Infinities and NaN's">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="asinh.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../inv_hyper.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../fpclass.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.inv_hyper.atanh"></a> atanh
+</h4></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">atanh</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">atanh</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">atanh</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Computes the reciprocal of <a href="inv_hyper_over.html" title="Inverse Hyperbolic Functions Overview">the
+ hyperbolic tangent function</a>, at x. Taylor series are used at the
+ origin to ensure accuracy.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ If x is in the range <code class="literal">]-&#8734;;-1[</code> or in the range <code class="literal">]+1;+&#8734;[</code>
+ then returns the result of domain_error.
+ </p>
+<p>
+ If x is in the range <code class="literal">[-1;-1+&#949;[</code>, then the result of -overflow_error is returned, with &#949;
+denoting
+ numeric_limits&lt;T&gt;::epsilon().
+ </p>
+<p>
+ If x is in the range <code class="literal">]+1-&#949;;+1]</code>, then the result of overflow_error is returned, with &#949;
+denoting
+ numeric_limits&lt;T&gt;::epsilon().
+ </p>
+<p>
+ The return type of this function is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: the return type is <code class="computeroutput"><span class="keyword">double</span></code> when T is an integer type, and T
+ otherwise.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="asinh.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../inv_hyper.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../fpclass.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/inv_hyper/inv_hyper_over.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/inv_hyper/inv_hyper_over.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,159 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Inverse Hyperbolic Functions Overview</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../inv_hyper.html" title="Inverse Hyperbolic Functions">
+<link rel="prev" href="../inv_hyper.html" title="Inverse Hyperbolic Functions">
+<link rel="next" href="acosh.html" title="acosh">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../inv_hyper.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../inv_hyper.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="acosh.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.inv_hyper.inv_hyper_over"></a><a href="inv_hyper_over.html" title="Inverse Hyperbolic Functions Overview"> Inverse
+ Hyperbolic Functions Overview</a>
+</h4></div></div></div>
+<p>
+ The exponential funtion is defined, for all objects for which this makes
+ sense, as the power series <span class="inlinemediaobject"><img src="../../../../equations/special_functions_blurb1.png"></span>,
+ with <span class="emphasis"><em><code class="literal">n! = 1x2x3x4x5...xn</code></em></span> (and
+ <span class="emphasis"><em><code class="literal">0! = 1</code></em></span> by definition) being the
+ factorial of <span class="emphasis"><em><code class="literal">n</code></em></span>. In particular,
+ the exponential function is well defined for real numbers, complex number,
+ quaternions, octonions, and matrices of complex numbers, among others.
+ </p>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ <span class="emphasis"><em><span class="bold"><strong>Graph of exp on R</strong></span></em></span>
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/exp_on_r.png" alt="exp_on_r"></span>
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ <span class="emphasis"><em><span class="bold"><strong>Real and Imaginary parts of exp on
+ C</strong></span></em></span>
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/im_exp_on_c.png" alt="im_exp_on_c"></span>
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<p>
+ The hyperbolic functions are defined as power series which can be computed
+ (for reals, complex, quaternions and octonions) as:
+ </p>
+<p>
+ Hyperbolic cosine: <span class="inlinemediaobject"><img src="../../../../equations/special_functions_blurb5.png"></span>
+ </p>
+<p>
+ Hyperbolic sine: <span class="inlinemediaobject"><img src="../../../../equations/special_functions_blurb6.png"></span>
+ </p>
+<p>
+ Hyperbolic tangent: <span class="inlinemediaobject"><img src="../../../../equations/special_functions_blurb7.png"></span>
+ </p>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ <span class="emphasis"><em><span class="bold"><strong>Trigonometric functions on R (cos:
+ purple; sin: red; tan: blue)</strong></span></em></span>
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/trigonometric.png" alt="trigonometric"></span>
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ <span class="emphasis"><em><span class="bold"><strong>Hyperbolic functions on r (cosh: purple;
+ sinh: red; tanh: blue)</strong></span></em></span>
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/hyperbolic.png" alt="hyperbolic"></span>
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<p>
+ The hyperbolic sine is one to one on the set of real numbers, with range
+ the full set of reals, while the hyperbolic tangent is also one to one
+ on the set of real numbers but with range <code class="literal">[0;+&#8734;[</code>, and
+ therefore both have inverses. The hyperbolic cosine is one to one from
+ <code class="literal">]-&#8734;;+1[</code> onto <code class="literal">]-&#8734;;-1[</code> (and from <code class="literal">]+1;+&#8734;[</code>
+ onto <code class="literal">]-&#8734;;-1[</code>); the inverse function we use here is defined
+ on <code class="literal">]-&#8734;;-1[</code> with range <code class="literal">]-&#8734;;+1[</code>.
+ </p>
+<p>
+ The inverse of the hyperbolic tangent is called the Argument hyperbolic
+ tangent, and can be computed as <span class="inlinemediaobject"><img src="../../../../equations/special_functions_blurb15.png"></span>.
+ </p>
+<p>
+ The inverse of the hyperbolic sine is called the Argument hyperbolic sine,
+ and can be computed (for <code class="literal">[-1;-1+&#949;[</code>) as <span class="inlinemediaobject"><img src="../../../../equations/special_functions_blurb17.png"></span>.
+ </p>
+<p>
+ The inverse of the hyperbolic cosine is called the Argument hyperbolic
+ cosine, and can be computed as <span class="inlinemediaobject"><img src="../../../../equations/special_functions_blurb18.png"></span>.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../inv_hyper.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../inv_hyper.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="acosh.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,49 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Logs, Powers, Roots and Exponentials</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../special.html" title="Special Functions">
+<link rel="prev" href="ellint/ellint_3.html" title="Elliptic Integrals of the Third Kind - Legendre Form">
+<link rel="next" href="powers/log1p.html" title="log1p">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ellint/ellint_3.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="powers/log1p.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.special.powers"></a><a href="powers.html" title="Logs, Powers, Roots and Exponentials"> Logs, Powers, Roots and
+ Exponentials</a>
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"> log1p</span></dt>
+<dt><span class="section"> expm1</span></dt>
+<dt><span class="section"> cbrt</span></dt>
+<dt><span class="section"> sqrt1pm1</span></dt>
+<dt><span class="section"> powm1</span></dt>
+<dt><span class="section"> hypot</span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ellint/ellint_3.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="powers/log1p.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/cbrt.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/cbrt.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,96 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>cbrt</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../powers.html" title="Logs, Powers, Roots and Exponentials">
+<link rel="prev" href="expm1.html" title="expm1">
+<link rel="next" href="sqrt1pm1.html" title="sqrt1pm1">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="expm1.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../powers.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sqrt1pm1.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.powers.cbrt"></a> cbrt
+</h4></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">cbrt</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">cbrt</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">cbrt</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ Returns the cubed root of x: x<sup>1/3</sup>.
+ </p>
+<p>
+ The return type of this function is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: the return is <code class="computeroutput"><span class="keyword">double</span></code>
+ when <span class="emphasis"><em>x</em></span> is an integer type and T otherwise.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ Implemented using Halley iteration.
+ </p>
+<a name="math_toolkit.special.powers.cbrt.accuracy"></a><h5>
+<a name="id691579"></a>
+ Accuracy
+ </h5>
+<p>
+ For built in floating-point types <code class="computeroutput"><span class="identifier">cbrt</span></code>
+ should have approximately 2 epsilon accuracy.
+ </p>
+<a name="math_toolkit.special.powers.cbrt.testing"></a><h5>
+<a name="id691621"></a>
+ Testing
+ </h5>
+<p>
+ A mixture of spot test sanity checks, and random high precision test values
+ calculated using NTL::RR at 1000-bit precision.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="expm1.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../powers.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sqrt1pm1.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/expm1.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/expm1.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,105 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>expm1</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../powers.html" title="Logs, Powers, Roots and Exponentials">
+<link rel="prev" href="log1p.html" title="log1p">
+<link rel="next" href="cbrt.html" title="cbrt">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="log1p.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../powers.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="cbrt.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.powers.expm1"></a> expm1
+</h4></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">expm1</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">expm1</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">expm1</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ Returns e<sup>x</sup> - 1.
+ </p>
+<p>
+ The return type of this function is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: the return is <code class="computeroutput"><span class="keyword">double</span></code>
+ when <span class="emphasis"><em>x</em></span> is an integer type and T otherwise.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ For small x, then <code class="computeroutput">e<sup>x</sup></code> is very close to 1, as a result calculating <code class="computeroutput">e<sup>x</sup> - 1</code> results in
+ catastrophic cancellation errors when x is small. <code class="computeroutput"><span class="identifier">expm1</span></code>
+ calculates <code class="computeroutput">e<sup>x</sup> - 1</code> using rational approximations (for up to 128-bit long doubles),
+ otherwise via a series expansion when x is small (giving an accuracy of
+ less than 2&#603;).
+ </p>
+<p>
+ Finally when BOOST_HAS_EXPM1 is defined then the <code class="computeroutput"><span class="keyword">float</span><span class="special">/</span><span class="keyword">double</span><span class="special">/</span><span class="keyword">long</span> <span class="keyword">double</span></code>
+ specializations of this template simply forward to the platform's native
+ (POSIX) implementation of this function.
+ </p>
+<a name="math_toolkit.special.powers.expm1.accuracy"></a><h5>
+<a name="id691116"></a>
+ Accuracy
+ </h5>
+<p>
+ For built in floating point types <code class="computeroutput"><span class="identifier">expm1</span></code>
+ should have approximately 1 epsilon accuracy.
+ </p>
+<a name="math_toolkit.special.powers.expm1.testing"></a><h5>
+<a name="id691157"></a>
+ Testing
+ </h5>
+<p>
+ A mixture of spot test sanity checks, and random high precision test values
+ calculated using NTL::RR at 1000-bit precision.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="log1p.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../powers.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="cbrt.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/hypot.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/hypot.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,90 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>hypot</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../powers.html" title="Logs, Powers, Roots and Exponentials">
+<link rel="prev" href="powm1.html" title="powm1">
+<link rel="next" href="../sinc.html" title="Sinus Cardinal and Hyperbolic Sinus Cardinal Functions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="powm1.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../powers.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../sinc.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.powers.hypot"></a> hypot
+</h4></div></div></div>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">hypot</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">hypot</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ <span class="bold"><strong>Effects: </strong></span> computes <span class="inlinemediaobject"><img src="../../../../equations/hypot.png"></span>
+in such a
+ way as to avoid undue underflow and overflow.
+ </p>
+<p>
+ The return type of this function is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when T1 and T2 are of different
+ types.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ When calculating <span class="inlinemediaobject"><img src="../../../../equations/hypot.png"></span> it's quite easy for the intermediate terms to
+ either overflow or underflow, even though the result is in fact perfectly
+ representable.
+ </p>
+<a name="math_toolkit.special.powers.hypot.implementation"></a><h5>
+<a name="id693089"></a>
+ Implementation
+ </h5>
+<p>
+ The function is even and symmetric in x and y, so first take assume <span class="emphasis"><em>x,y
+ &gt; 0</em></span> and <span class="emphasis"><em>x &gt; y</em></span> (we can permute the
+ arguments if this is not the case).
+ </p>
+<p>
+ Then if <span class="emphasis"><em>x * &#949; &gt;= y</em></span> we can simply return <span class="emphasis"><em>x</em></span>.
+ </p>
+<p>
+ Otherwise the result is given by:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/hypot2.png"></span>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="powm1.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../powers.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../sinc.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/log1p.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/log1p.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,119 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>log1p</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../powers.html" title="Logs, Powers, Roots and Exponentials">
+<link rel="prev" href="../powers.html" title="Logs, Powers, Roots and Exponentials">
+<link rel="next" href="expm1.html" title="expm1">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../powers.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../powers.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="expm1.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.powers.log1p"></a> log1p
+</h4></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">log1p</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">log1p</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">log1p</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ Returns the natural logarithm of <code class="computeroutput"><span class="identifier">x</span><span class="special">+</span><span class="number">1</span></code>.
+ </p>
+<p>
+ The return type of this function is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: the return is <code class="computeroutput"><span class="keyword">double</span></code>
+ when <span class="emphasis"><em>x</em></span> is an integer type and T otherwise.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ There are many situations where it is desirable to compute <code class="computeroutput"><span class="identifier">log</span><span class="special">(</span><span class="identifier">x</span><span class="special">+</span><span class="number">1</span><span class="special">)</span></code>. However, for small <code class="computeroutput"><span class="identifier">x</span></code>
+ then <code class="computeroutput"><span class="identifier">x</span><span class="special">+</span><span class="number">1</span></code> suffers from catastrophic cancellation
+ errors so that <code class="computeroutput"><span class="identifier">x</span><span class="special">+</span><span class="number">1</span> <span class="special">==</span> <span class="number">1</span></code>
+ and <code class="computeroutput"><span class="identifier">log</span><span class="special">(</span><span class="identifier">x</span><span class="special">+</span><span class="number">1</span><span class="special">)</span> <span class="special">==</span> <span class="number">0</span></code>,
+ when in fact for very small x, the best approximation to <code class="computeroutput"><span class="identifier">log</span><span class="special">(</span><span class="identifier">x</span><span class="special">+</span><span class="number">1</span><span class="special">)</span></code> would be <code class="computeroutput"><span class="identifier">x</span></code>.
+ <code class="computeroutput"><span class="identifier">log1p</span></code> calculates the best
+ approximation to <code class="computeroutput"><span class="identifier">log</span><span class="special">(</span><span class="number">1</span><span class="special">+</span><span class="identifier">x</span><span class="special">)</span></code> using a Taylor series expansion for accuracy
+ (less than 2&#603;). Alternatively note that there are faster methods available,
+ for example using the equivalence:
+ </p>
+<pre class="programlisting">
+<span class="identifier">log</span><span class="special">(</span><span class="number">1</span><span class="special">+</span><span class="identifier">x</span><span class="special">)</span> <span class="special">==</span> <span class="special">(</span><span class="identifier">log</span><span class="special">(</span><span class="number">1</span><span class="special">+</span><span class="identifier">x</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">/</span> <span class="special">((</span><span class="number">1</span><span class="special">-</span><span class="identifier">x</span><span class="special">)</span> <span class="special">-</span> <span class="number">1</span><span class="special">)</span>
+</pre>
+<p>
+ However, experience has shown that these methods tend to fail quite spectacularly
+ once the compiler's optimizations are turned on, consequently they are
+ used only when known not to break with a particular compiler. In contrast,
+ the series expansion method seems to be reasonably immune to optimizer-induced
+ errors.
+ </p>
+<p>
+ Finally when BOOST_HAS_LOG1P is defined then the <code class="computeroutput"><span class="keyword">float</span><span class="special">/</span><span class="keyword">double</span><span class="special">/</span><span class="keyword">long</span> <span class="keyword">double</span></code>
+ specializations of this template simply forward to the platform's native
+ (POSIX) implementation of this function.
+ </p>
+<a name="math_toolkit.special.powers.log1p.accuracy"></a><h5>
+<a name="id690557"></a>
+ Accuracy
+ </h5>
+<p>
+ For built in floating point types <code class="computeroutput"><span class="identifier">log1p</span></code>
+ should have approximately 1 epsilon accuracy.
+ </p>
+<a name="math_toolkit.special.powers.log1p.testing"></a><h5>
+<a name="id690598"></a>
+ Testing
+ </h5>
+<p>
+ A mixture of spot test sanity checks, and random high precision test values
+ calculated using NTL::RR at 1000-bit precision.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../powers.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../powers.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="expm1.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/powm1.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/powm1.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,98 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>powm1</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../powers.html" title="Logs, Powers, Roots and Exponentials">
+<link rel="prev" href="sqrt1pm1.html" title="sqrt1pm1">
+<link rel="next" href="hypot.html" title="hypot">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sqrt1pm1.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../powers.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="hypot.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.powers.powm1"></a> powm1
+</h4></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">powm1</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">powm1</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">powm1</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">y</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ Returns x<sup>y </sup> - 1.
+ </p>
+<p>
+ The return type of this function is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when T1 and T2 are dufferent types.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ There are two domains where this is useful: when y is very small, or when
+ x is close to 1.
+ </p>
+<p>
+ Implemented in terms of <code class="computeroutput"><span class="identifier">expm1</span></code>.
+ </p>
+<a name="math_toolkit.special.powers.powm1.accuracy"></a><h5>
+<a name="id692648"></a>
+ Accuracy
+ </h5>
+<p>
+ Should have approximately 2-3 epsilon accuracy.
+ </p>
+<a name="math_toolkit.special.powers.powm1.testing"></a><h5>
+<a name="id692678"></a>
+ Testing
+ </h5>
+<p>
+ A selection of random high precision test values calculated using NTL::RR
+ at 1000-bit precision.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sqrt1pm1.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../powers.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="hypot.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/sqrt1pm1.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/powers/sqrt1pm1.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,101 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>sqrt1pm1</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../powers.html" title="Logs, Powers, Roots and Exponentials">
+<link rel="prev" href="cbrt.html" title="cbrt">
+<link rel="next" href="powm1.html" title="powm1">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="cbrt.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../powers.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="powm1.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.powers.sqrt1pm1"></a> sqrt1pm1
+</h4></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">sqrt1pm1</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">sqrt1pm1</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">sqrt1pm1</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ Returns <code class="computeroutput"><span class="identifier">sqrt</span><span class="special">(</span><span class="number">1</span><span class="special">+</span><span class="identifier">x</span><span class="special">)</span> <span class="special">-</span> <span class="number">1</span></code>.
+ </p>
+<p>
+ The return type of this function is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: the return is <code class="computeroutput"><span class="keyword">double</span></code>
+ when <span class="emphasis"><em>x</em></span> is an integer type and T otherwise.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ This function is useful when you need the difference between sqrt(x) and
+ 1, when x is itself close to 1.
+ </p>
+<p>
+ Implemented in terms of <code class="computeroutput"><span class="identifier">log1p</span></code>
+ and <code class="computeroutput"><span class="identifier">expm1</span></code>.
+ </p>
+<a name="math_toolkit.special.powers.sqrt1pm1.accuracy"></a><h5>
+<a name="id692117"></a>
+ Accuracy
+ </h5>
+<p>
+ For built in floating-point types <code class="computeroutput"><span class="identifier">sqrt1pm1</span></code>
+ should have approximately 3 epsilon accuracy.
+ </p>
+<a name="math_toolkit.special.powers.sqrt1pm1.testing"></a><h5>
+<a name="id692158"></a>
+ Testing
+ </h5>
+<p>
+ A selection of random high precision test values calculated using NTL::RR
+ at 1000-bit precision.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="cbrt.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../powers.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="powm1.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_beta.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_beta.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,49 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Beta Functions</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../special.html" title="Special Functions">
+<link rel="prev" href="factorials/sf_binomial.html" title="Binomial Coefficients">
+<link rel="next" href="sf_beta/beta_function.html" title="Beta">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="factorials/sf_binomial.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sf_beta/beta_function.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.special.sf_beta"></a> Beta Functions
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"> Beta</span></dt>
+<dt><span class="section"><a href="sf_beta/ibeta_function.html"> Incomplete
+ Beta Functions</a></span></dt>
+<dt><span class="section"><a href="sf_beta/ibeta_inv_function.html"> The
+ Incomplete Beta Function Inverses</a></span></dt>
+<dt><span class="section"><a href="sf_beta/beta_derivative.html"> Derivative
+ of the Incomplete Beta Function</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="factorials/sf_binomial.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sf_beta/beta_function.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_beta/beta_derivative.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_beta/beta_derivative.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,107 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Derivative of the Incomplete Beta Function</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_beta.html" title="Beta Functions">
+<link rel="prev" href="ibeta_inv_function.html" title="The Incomplete Beta Function Inverses">
+<link rel="next" href="../sf_erf.html" title="Error Functions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ibeta_inv_function.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_beta.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../sf_erf.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_beta.beta_derivative"></a><a href="beta_derivative.html" title="Derivative of the Incomplete Beta Function"> Derivative
+ of the Incomplete Beta Function</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.sf_beta.beta_derivative.synopsis"></a><h5>
+<a name="id650794"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">beta</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_derivative</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_derivative</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.sf_beta.beta_derivative.description"></a><h5>
+<a name="id651256"></a>
+ Description
+ </h5>
+<p>
+ This function finds some uses in statistical distributions: it computes
+ the partial derivative with respect to <span class="emphasis"><em>x</em></span> of the incomplete
+ beta function ibeta.
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/derivative2.png"></span>
+ </p>
+<p>
+ The return type of this function is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when T1, T2 and T3 are different
+ types.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<a name="math_toolkit.special.sf_beta.beta_derivative.accuracy"></a><h5>
+<a name="id651372"></a>
+ Accuracy
+ </h5>
+<p>
+ Almost identical to the incomplete beta function ibeta.
+ </p>
+<a name="math_toolkit.special.sf_beta.beta_derivative.implementation"></a><h5>
+<a name="id651410"></a>
+ Implementation
+ </h5>
+<p>
+ This function just expose some of the internals of the incomplete beta
+ function ibeta:
+ refer to the documentation for that function for more information.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ibeta_inv_function.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_beta.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../sf_erf.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_beta/beta_function.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_beta/beta_function.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,332 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Beta</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_beta.html" title="Beta Functions">
+<link rel="prev" href="../sf_beta.html" title="Beta Functions">
+<link rel="next" href="ibeta_function.html" title="Incomplete Beta Functions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../sf_beta.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_beta.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ibeta_function.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_beta.beta_function"></a> Beta
+</h4></div></div></div>
+<a name="math_toolkit.special.sf_beta.beta_function.synopsis"></a><h5>
+<a name="id637270"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">beta</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">beta</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">beta</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.sf_beta.beta_function.description"></a><h5>
+<a name="id637663"></a>
+ Description
+ </h5>
+<p>
+ The beta function is defined by:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/beta1.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/beta.png" alt="beta"></span>
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ There are effectively two versions of this function internally: a fully
+ generic version that is slow, but reasonably accurate, and a much more
+ efficient approximation that is used where the number of digits in the
+ significand of T correspond to a certain <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a>. In practice any built-in floating-point type you
+ will encounter has an appropriate <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a> defined for it. It is also possible, given enough
+ machine time, to generate further <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a>'s using the program libs/math/tools/lanczos_generator.cpp.
+ </p>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when T1 and T2 are different types.
+ </p>
+<a name="math_toolkit.special.sf_beta.beta_function.accuracy"></a><h5>
+<a name="id637825"></a>
+ Accuracy
+ </h5>
+<p>
+ The following table shows peak errors for various domains of input arguments,
+ along with comparisons to the GSL-1.9
+ and Cephes libraries.
+ Note that only results for the widest floating point type on the system
+ are given as narrower types have <a href="../../backgrounders/relative_error.html#zero_error">effectively
+ zero error</a>.
+ </p>
+<div class="table">
+<a name="id637872"></a><p class="title"><b>Table 15. Peak Errors In the Beta Function</b></p>
+<div class="table-contents"><table class="table" summary="Peak Errors In the Beta Function">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ Errors in range
+ </p>
+ <p>
+ 0.4 &lt; a,b &lt; 100
+ </p>
+ </th>
+<th>
+ <p>
+ Errors in range
+ </p>
+ <p>
+ 1e-6 &lt; a,b &lt; 36
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=99 Mean=22
+ </p>
+ <p>
+ (GSL Peak=1178 Mean=238)
+ </p>
+ <p>
+ (Cephes=1612)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=10.7 Mean=2.6
+ </p>
+ <p>
+ (GSL Peak=12 Mean=2.0)
+ </p>
+ <p>
+ (Cephes=174)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux IA32, g++ 3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=112.1 Mean=26.9
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=15.8 Mean=3.6
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux IA64, g++ 3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=61.4 Mean=19.5
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=12.2 Mean=3.6
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=42.03 Mean=13.94
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=9.8 Mean=3.1
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><p>
+ Note that the worst errors occur when a or b are large, and that when this
+ is the case the result is very close to zero, so absolute errors will be
+ very small.
+ </p>
+<a name="math_toolkit.special.sf_beta.beta_function.testing"></a><h5>
+<a name="id638118"></a>
+ Testing
+ </h5>
+<p>
+ A mixture of spot tests of exact values, and randomly generated test data
+ are used: the test data was computed using NTL::RR
+ at 1000-bit precision.
+ </p>
+<a name="math_toolkit.special.sf_beta.beta_function.implementation"></a><h5>
+<a name="id638156"></a>
+ Implementation
+ </h5>
+<p>
+ Traditional methods of evaluating the beta function either involve evaluating
+ the gamma functions directly, or taking logarithms and then exponentiating
+ the result. However, the former is prone to overflows for even very modest
+ arguments, while the latter is prone to cancellation errors. As an alternative,
+ if we regard the gamma function as a white-box containing the <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a>, then we can combine the power terms:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/beta2.png"></span>
+ </p>
+<p>
+ which is almost the ideal solution, however almost all of the error occurs
+ in evaluating the power terms when <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span>
+ are large. If we assume that <span class="emphasis"><em>a &gt; b</em></span> then the larger
+ of the two power terms can be reduced by a factor of <span class="emphasis"><em>b</em></span>,
+ which immediately cuts the maximum error in half:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/beta3.png"></span>
+ </p>
+<p>
+ This may not be the final solution, but it is very competitive compared
+ to other implementation methods.
+ </p>
+<p>
+ The generic implementation - where no <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a> approximation is available - is implemented in a very
+ similar way to the generic version of the gamma function. Again in order
+ to avoid numerical overflow the power terms that prefix the series and
+ continued fraction parts are collected together into:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/beta8.png"></span>
+ </p>
+<p>
+ where la, lb and lc are the integration limits used for a, b, and a+b.
+ </p>
+<p>
+ There are a few special cases worth mentioning:
+ </p>
+<p>
+ When <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span> are less than one,
+ we can use the recurrence relations:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/beta4.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/beta5.png"></span>
+ </p>
+<p>
+ to move to a more favorable region where they are both greater than 1.
+ </p>
+<p>
+ In addition:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/beta7.png"></span>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../sf_beta.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_beta.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ibeta_function.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_beta/ibeta_function.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_beta/ibeta_function.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,978 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Incomplete Beta Functions</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_beta.html" title="Beta Functions">
+<link rel="prev" href="beta_function.html" title="Beta">
+<link rel="next" href="ibeta_inv_function.html" title="The Incomplete Beta Function Inverses">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="beta_function.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_beta.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ibeta_inv_function.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_beta.ibeta_function"></a><a href="ibeta_function.html" title="Incomplete Beta Functions"> Incomplete
+ Beta Functions</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.sf_beta.ibeta_function.synopsis"></a><h5>
+<a name="id638478"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">beta</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">beta</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">betac</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">betac</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.sf_beta.ibeta_function.description"></a><h5>
+<a name="id639863"></a>
+ Description
+ </h5>
+<p>
+ There are four <a href="http://en.wikipedia.org/wiki/Incomplete_beta_function" target="_top">incomplete
+ beta functions</a> : two are normalised versions (also known as <span class="emphasis"><em>regularized</em></span>
+ beta functions) that return values in the range [0, 1], and two are non-normalised
+ and return values in the range [0, beta(a,
+ b)]. Users interested in statistical applications should use the normalised
+ (or regularized
+ ) versions (ibeta and ibetac).
+ </p>
+<p>
+ All of these functions require <span class="emphasis"><em>a &gt; 0</em></span>, <span class="emphasis"><em>b
+ &gt; 0</em></span> and <span class="emphasis"><em>0 &lt;= x &lt;= 1</em></span>.
+ </p>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when T1, T2 and T3 are different
+ types.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the normalised incomplete beta function of a, b and x:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta3.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/ibeta.png" alt="ibeta"></span>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the normalised complement of the incomplete beta function of a,
+ b and x:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta4.png"></span>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">beta</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">beta</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the full (non-normalised) incomplete beta function of a, b and
+ x:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta1.png"></span>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">betac</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">betac</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the full (non-normalised) complement of the incomplete beta function
+ of a, b and x:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta2.png"></span>
+ </p>
+<a name="math_toolkit.special.sf_beta.ibeta_function.accuracy"></a><h5>
+<a name="id641408"></a>
+ Accuracy
+ </h5>
+<p>
+ The following tables give peak and mean relative errors in over various
+ domains of a, b and x, along with comparisons to the GSL-1.9
+ and Cephes libraries.
+ Note that only results for the widest floating-point type on the system
+ are given as narrower types have <a href="../../backgrounders/relative_error.html#zero_error">effectively
+ zero error</a>.
+ </p>
+<p>
+ Note that the results for 80 and 128-bit long doubles are noticeably higher
+ than for doubles: this is because the wider exponent range of these types
+ allow more extreme test cases to be tested. For example expected results
+ that are zero at double precision, may be finite but exceptionally small
+ with the wider exponent range of the long double types.
+ </p>
+<div class="table">
+<a name="id641465"></a><p class="title"><b>Table 16. Errors In the Function ibeta(a,b,x)</b></p>
+<div class="table-contents"><table class="table" summary="Errors In the Function ibeta(a,b,x)">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ 0 &lt; a,b &lt; 10
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0 &lt; x &lt; 1
+ </p>
+ </th>
+<th>
+ <p>
+ 0 &lt; a,b &lt; 100
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0 &lt; x &lt; 1
+ </p>
+ </th>
+<th>
+ <p>
+ 1x10<sup>-5</sup> &lt; a,b &lt; 1x10<sup>5</sup>
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0 &lt; x &lt; 1
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=42.3 Mean=2.9
+ </p>
+ <p>
+ (GSL Peak=682 Mean=32.5)
+ </p>
+ <p>
+ (Cephes Peak=42.7
+ Mean=7.0)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=108 Mean=16.6
+ </p>
+ <p>
+ (GSL Peak=690 Mean=151)
+ </p>
+ <p>
+ (Cephes Peak=1545
+ Mean=218)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4x10<sup>3</sup> Mean=203
+ </p>
+ <p>
+ (GSL Peak~3x10<sup>5</sup> Mean~2x10<sup>4</sup>)
+ </p>
+ <p>
+ (Cephes Peak~5x10<sup>5</sup> Mean~2x10<sup>4</sup>)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA32, gcc-3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=21.9 Mean=3.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=270.7 Mean=26.8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak~5x10<sup>4</sup> Mean=3x10<sup>3</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA64, gcc-3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=15.4 Mean=3.0
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=112.9 Mean=14.3
+ </p>
+ </td>
+<td>
+ <p>
+ Peak~5x10<sup>4</sup> Mean=3x10<sup>3</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=20.9 Mean=2.6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=88.1 Mean=14.3
+ </p>
+ </td>
+<td>
+ <p>
+ Peak~2x10<sup>4</sup> Mean=1x10<sup>3</sup>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id641814"></a><p class="title"><b>Table 17. Errors In the Function ibetac(a,b,x)</b></p>
+<div class="table-contents"><table class="table" summary="Errors In the Function ibetac(a,b,x)">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ 0 &lt; a,b &lt; 10
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0 &lt; x &lt; 1
+ </p>
+ </th>
+<th>
+ <p>
+ 0 &lt; a,b &lt; 100
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0 &lt; x &lt; 1
+ </p>
+ </th>
+<th>
+ <p>
+ 1x10<sup>-5</sup> &lt; a,b &lt; 1x10<sup>5</sup>
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0 &lt; x &lt; 1
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=13.9 Mean=2.0
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=56.2 Mean=14
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=3x10<sup>3</sup> Mean=159
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA32, gcc-3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=21.1 Mean=3.6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=221.7 Mean=25.8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak~9x10<sup>4</sup> Mean=3x10<sup>3</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA64, gcc-3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=10.6 Mean=2.2
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=73.9 Mean=11.9
+ </p>
+ </td>
+<td>
+ <p>
+ Peak~9x10<sup>4</sup> Mean=3x10<sup>3</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=9.9 Mean=2.6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=117.7 Mean=15.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak~3x10<sup>4</sup> Mean=1x10<sup>3</sup>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id642099"></a><p class="title"><b>Table 18. Errors In the Function beta(a, b, x)</b></p>
+<div class="table-contents"><table class="table" summary="Errors In the Function beta(a, b, x)">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ 0 &lt; a,b &lt; 10
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0 &lt; x &lt; 1
+ </p>
+ </th>
+<th>
+ <p>
+ 0 &lt; a,b &lt; 100
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0 &lt; x &lt; 1
+ </p>
+ </th>
+<th>
+ <p>
+ 1x10<sup>-5</sup> &lt; a,b &lt; 1x10<sup>5</sup>
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0 &lt; x &lt; 1
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=39 Mean=2.9
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=91 Mean=12.7
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=635 Mean=25
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA32, gcc-3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=26 Mean=3.6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=180.7 Mean=30.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak~7x10<sup>4</sup> Mean=3x10<sup>3</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA64, gcc-3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=13 Mean=2.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=67.1 Mean=13.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak~7x10<sup>4</sup> Mean=3x10<sup>3</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=27.3 Mean=3.6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=49.8 Mean=9.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak~6x10<sup>4</sup> Mean=3x10<sup>3</sup>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id642380"></a><p class="title"><b>Table 19. Errors In the Function betac(a,b,x)</b></p>
+<div class="table-contents"><table class="table" summary="Errors In the Function betac(a,b,x)">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ 0 &lt; a,b &lt; 10
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0 &lt; x &lt; 1
+ </p>
+ </th>
+<th>
+ <p>
+ 0 &lt; a,b &lt; 100
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0 &lt; x &lt; 1
+ </p>
+ </th>
+<th>
+ <p>
+ 1x10<sup>-5</sup> &lt; a,b &lt; 1x10<sup>5</sup>
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0 &lt; x &lt; 1
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=12.0 Mean=2.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=91 Mean=15
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4x10<sup>3</sup> Mean=113
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA32, gcc-3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=19.8 Mean=3.8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=295.1 Mean=33.9
+ </p>
+ </td>
+<td>
+ <p>
+ Peak~1x10<sup>5</sup> Mean=5x10<sup>3</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA64, gcc-3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=11.2 Mean=2.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=63.5 Mean=13.6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak~1x10<sup>5</sup> Mean=5x10<sup>3</sup>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=15.6 Mean=3.5
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=39.8 Mean=8.9
+ </p>
+ </td>
+<td>
+ <p>
+ Peak~9x10<sup>4</sup> Mean=5x10<sup>3</sup>
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><a name="math_toolkit.special.sf_beta.ibeta_function.testing"></a><h5>
+<a name="id642673"></a>
+ Testing
+ </h5>
+<p>
+ There are two sets of tests: spot tests compare values taken from <a href="http://functions.wolfram.com/webMathematica/FunctionEvaluation.jsp?name=BetaRegularized" target="_top">Mathworld's
+ online function evaluator</a> with this implementation: they provide
+ a basic "sanity check" for the implementation, with one spot-test
+ in each implementation-domain (see implementation notes below).
+ </p>
+<p>
+ Accuracy tests use data generated at very high precision (with <a href="http://shoup.net/ntl/doc/RR.txt" target="_top">NTL
+ RR class</a> set at 1000-bit precision), using the "textbook"
+ continued fraction representation (refer to the first continued fraction
+ in the implementation discussion below). Note that this continued fraction
+ is <span class="emphasis"><em>not</em></span> used in the implementation, and therefore we
+ have test data that is fully independent of the code.
+ </p>
+<a name="math_toolkit.special.sf_beta.ibeta_function.implementation"></a><h5>
+<a name="id642736"></a>
+ Implementation
+ </h5>
+<p>
+ This implementation is closely based upon <a href="http://portal.acm.org/citation.cfm?doid=131766.131776" target="_top">"Algorithm
+ 708; Significant digit computation of the incomplete beta function ratios",
+ DiDonato and Morris, ACM, 1992.</a>
+ </p>
+<p>
+ All four of these functions share a common implementation: this is passed
+ both x and y, and can return either p or q where these are related by:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta_inv5.png"></span>
+ </p>
+<p>
+ so at any point we can swap a for b, x for y and p for q if this results
+ in a more favourable position. Generally such swaps are performed so that
+ we always compute a value less than 0.9: when required this can then be
+ subtracted from 1 without undue cancellation error.
+ </p>
+<p>
+ The following continued fraction representation is found in many textbooks
+ but is not used in this implementation - it's both slower and less accurate
+ than the alternatives - however it is used to generate test data:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta5.png"></span>
+ </p>
+<p>
+ The following continued fraction is due to <a href="http://portal.acm.org/citation.cfm?doid=131766.131776" target="_top">Didonato
+ and Morris</a>, and is used in this implementation when a and b are
+ both greater than 1:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta6.png"></span>
+ </p>
+<p>
+ For smallish b and x then a series representation can be used:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta7.png"></span>
+ </p>
+<p>
+ When b &lt;&lt; a then the transition from 0 to 1 occurs very close to
+ x = 1 and some care has to be taken over the method of computation, in
+ that case the following series representation is used:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta8.png"></span>
+ </p>
+<p>
+ Where Q(a,x) is an <a href="http://functions.wolfram.com/GammaBetaErf/Gamma2/" target="_top">incomplete
+ gamma function</a>. Note that this method relies on keeping a table
+ of all the p<sub>n </sub> previously computed, which does limit the precision of the
+ method, depending upon the size of the table used.
+ </p>
+<p>
+ When <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span> are both small integers,
+ then we can relate the incomplete beta to the binomial distribution and
+ use the following finite sum:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta12.png"></span>
+ </p>
+<p>
+ Finally we can sidestep difficult areas, or move to an area with a more
+ efficient means of computation, by using the duplication formulae:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta10.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta11.png"></span>
+ </p>
+<p>
+ The domains of a, b and x for which the various methods are used are identical
+ to those described in the <a href="http://portal.acm.org/citation.cfm?doid=131766.131776" target="_top">Didonato
+ and Morris TOMS 708 paper</a>.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="beta_function.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_beta.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ibeta_inv_function.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_beta/ibeta_inv_function.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_beta/ibeta_inv_function.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,573 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>The Incomplete Beta Function Inverses</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_beta.html" title="Beta Functions">
+<link rel="prev" href="ibeta_function.html" title="Incomplete Beta Functions">
+<link rel="next" href="beta_derivative.html" title="Derivative of the Incomplete Beta Function">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ibeta_function.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_beta.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="beta_derivative.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_beta.ibeta_inv_function"></a><a href="ibeta_inv_function.html" title="The Incomplete Beta Function Inverses"> The
+ Incomplete Beta Function Inverses</a>
+</h4></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">beta</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">T4</span><span class="special">*</span> <span class="identifier">py</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">T4</span><span class="special">*</span> <span class="identifier">py</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">,</span> <span class="identifier">T4</span><span class="special">*</span> <span class="identifier">py</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">,</span> <span class="identifier">T4</span><span class="special">*</span> <span class="identifier">py</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_invb</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_invb</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac_invb</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac_invb</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.sf_beta.ibeta_inv_function.description"></a><h5>
+<a name="id645886"></a>
+ Description
+ </h5>
+<p>
+ There are six <a href="http://functions.wolfram.com/GammaBetaErf/" target="_top">incomplete
+ beta function inverses</a> which allow you solve for any of the three
+ parameters to the incomplete beta, starting from either the result of the
+ incomplete beta (p) or its complement (q).
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<div class="tip"><table border="0" summary="Tip">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../../doc/html/images/tip.png"></td>
+<th align="left">Tip</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ When people normally talk about the inverse of the incomplete beta function,
+ they are talking about inverting on parameter <span class="emphasis"><em>x</em></span>.
+ These are implemented here as ibeta_inv and ibeta_inv, and are by far
+ the most efficient of the inverses presented here.
+ </p>
+<p>
+ The inverses on the <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span>
+ parameters find use in some statistical applications, but have to be
+ computed by rather brute force numerical techniques and are consequently
+ several times slower. These are implemented here as ibeta_inva and ibeta_invb,
+ and complement versions ibetac_inva and ibetac_invb.
+ </p>
+</td></tr>
+</table></div>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when called with arguments T1...TN
+ of different types.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">T4</span><span class="special">*</span> <span class="identifier">py</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">T4</span><span class="special">*</span> <span class="identifier">py</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns a value <span class="emphasis"><em>x</em></span> such that: <code class="computeroutput"><span class="identifier">p</span>
+ <span class="special">=</span> <span class="identifier">ibeta</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
+ <span class="identifier">b</span><span class="special">,</span>
+ <span class="identifier">x</span><span class="special">);</span></code>
+ and sets <code class="computeroutput"><span class="special">*</span><span class="identifier">py</span>
+ <span class="special">=</span> <span class="number">1</span> <span class="special">-</span> <span class="identifier">x</span></code> when
+ the <code class="computeroutput"><span class="identifier">py</span></code> parameter is provided
+ and is non-null. Note that internally this function computes whichever
+ is the smaller of <code class="computeroutput"><span class="identifier">x</span></code> and
+ <code class="computeroutput"><span class="number">1</span><span class="special">-</span><span class="identifier">x</span></code>, and therefore the value assigned to
+ <code class="computeroutput"><span class="special">*</span><span class="identifier">py</span></code>
+ is free from cancellation errors. That means that even if the function
+ returns <code class="computeroutput"><span class="number">1</span></code>, the value stored
+ in <code class="computeroutput"><span class="special">*</span><span class="identifier">py</span></code>
+ may be non-zero, albeit very small.
+ </p>
+<p>
+ Requires: <span class="emphasis"><em>a,b &gt; 0</em></span> and <span class="emphasis"><em>0 &lt;= p &lt;=
+ 1</em></span>.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">,</span> <span class="identifier">T4</span><span class="special">*</span> <span class="identifier">py</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T4</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">q</span><span class="special">,</span> <span class="identifier">T4</span><span class="special">*</span> <span class="identifier">py</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns a value <span class="emphasis"><em>x</em></span> such that: <code class="computeroutput"><span class="identifier">q</span>
+ <span class="special">=</span> <span class="identifier">ibetac</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
+ <span class="identifier">b</span><span class="special">,</span>
+ <span class="identifier">x</span><span class="special">);</span></code>
+ and sets <code class="computeroutput"><span class="special">*</span><span class="identifier">py</span>
+ <span class="special">=</span> <span class="number">1</span> <span class="special">-</span> <span class="identifier">x</span></code> when
+ the <code class="computeroutput"><span class="identifier">py</span></code> parameter is provided
+ and is non-null. Note that internally this function computes whichever
+ is the smaller of <code class="computeroutput"><span class="identifier">x</span></code> and
+ <code class="computeroutput"><span class="number">1</span><span class="special">-</span><span class="identifier">x</span></code>, and therefore the value assigned to
+ <code class="computeroutput"><span class="special">*</span><span class="identifier">py</span></code>
+ is free from cancellation errors. That means that even if the function
+ returns <code class="computeroutput"><span class="number">1</span></code>, the value stored
+ in <code class="computeroutput"><span class="special">*</span><span class="identifier">py</span></code>
+ may be non-zero, albeit very small.
+ </p>
+<p>
+ Requires: <span class="emphasis"><em>a,b &gt; 0</em></span> and <span class="emphasis"><em>0 &lt;= q &lt;=
+ 1</em></span>.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns a value <span class="emphasis"><em>a</em></span> such that: <code class="computeroutput"><span class="identifier">p</span>
+ <span class="special">=</span> <span class="identifier">ibeta</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
+ <span class="identifier">b</span><span class="special">,</span>
+ <span class="identifier">x</span><span class="special">);</span></code>
+ </p>
+<p>
+ Requires: <span class="emphasis"><em>b &gt; 0</em></span>, <span class="emphasis"><em>0 &lt; x &lt; 1</em></span>
+ and <span class="emphasis"><em>0 &lt;= p &lt;= 1</em></span>.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns a value <span class="emphasis"><em>a</em></span> such that: <code class="computeroutput"><span class="identifier">q</span>
+ <span class="special">=</span> <span class="identifier">ibetac</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
+ <span class="identifier">b</span><span class="special">,</span>
+ <span class="identifier">x</span><span class="special">);</span></code>
+ </p>
+<p>
+ Requires: <span class="emphasis"><em>b &gt; 0</em></span>, <span class="emphasis"><em>0 &lt; x &lt; 1</em></span>
+ and <span class="emphasis"><em>0 &lt;= q &lt;= 1</em></span>.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_invb</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibeta_invb</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns a value <span class="emphasis"><em>b</em></span> such that: <code class="computeroutput"><span class="identifier">p</span>
+ <span class="special">=</span> <span class="identifier">ibeta</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
+ <span class="identifier">b</span><span class="special">,</span>
+ <span class="identifier">x</span><span class="special">);</span></code>
+ </p>
+<p>
+ Requires: <span class="emphasis"><em>a &gt; 0</em></span>, <span class="emphasis"><em>0 &lt; x &lt; 1</em></span>
+ and <span class="emphasis"><em>0 &lt;= p &lt;= 1</em></span>.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac_invb</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">ibetac_invb</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns a value <span class="emphasis"><em>b</em></span> such that: <code class="computeroutput"><span class="identifier">q</span>
+ <span class="special">=</span> <span class="identifier">ibetac</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
+ <span class="identifier">b</span><span class="special">,</span>
+ <span class="identifier">x</span><span class="special">);</span></code>
+ </p>
+<p>
+ Requires: <span class="emphasis"><em>a &gt; 0</em></span>, <span class="emphasis"><em>0 &lt; x &lt; 1</em></span>
+ and <span class="emphasis"><em>0 &lt;= q &lt;= 1</em></span>.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<a name="math_toolkit.special.sf_beta.ibeta_inv_function.accuracy"></a><h5>
+<a name="id649618"></a>
+ Accuracy
+ </h5>
+<p>
+ The accuracy of these functions should closely follow that of the regular
+ forward incomplete beta functions. However, note that in some parts of
+ their domain, these functions can be extremely sensitive to changes in
+ input, particularly when the argument <span class="emphasis"><em>p</em></span> (or it's complement
+ <span class="emphasis"><em>q</em></span>) is very close to <code class="computeroutput"><span class="number">0</span></code>
+ or <code class="computeroutput"><span class="number">1</span></code>.
+ </p>
+<a name="math_toolkit.special.sf_beta.ibeta_inv_function.testing"></a><h5>
+<a name="id649684"></a>
+ Testing
+ </h5>
+<p>
+ There are two sets of tests:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Basic sanity checks attempt to "round-trip" from <span class="emphasis"><em>a,
+ b</em></span> and <span class="emphasis"><em>x</em></span> to <span class="emphasis"><em>p</em></span> or
+ <span class="emphasis"><em>q</em></span> and back again. These tests have quite generous
+ tolerances: in general both the incomplete beta and its inverses change
+ so rapidly, that round tripping to more than a couple of significant
+ digits isn't possible. This is especially true when <span class="emphasis"><em>p</em></span>
+ or <span class="emphasis"><em>q</em></span> is very near one: in this case there isn't
+ enough "information content" in the input to the inverse function
+ to get back where you started.
+ </li>
+<li>
+ Accuracy checks using high precision test values. These measure the accuracy
+ of the result, given exact input values.
+ </li>
+</ul></div>
+<a name="math_toolkit.special.sf_beta.ibeta_inv_function.implementation_of_ibeta_inv_and_ibetac_inv"></a><h5>
+<a name="id649761"></a>
+ <a href="ibeta_inv_function.html#math_toolkit.special.sf_beta.ibeta_inv_function.implementation_of_ibeta_inv_and_ibetac_inv">Implementation
+ of ibeta_inv and ibetac_inv</a>
+ </h5>
+<p>
+ These two functions share a common implementation.
+ </p>
+<p>
+ First an initial approximation to x is computed then the last few bits
+ are cleaned up using <a href="http://en.wikipedia.org/wiki/Simple_rational_approximation" target="_top">Halley
+ iteration</a>. The iteration limit is set to 1<span class="emphasis"><em>2 of the number
+ of bits in T, which by experiment is sufficient to ensure that the inverses
+ are at least as accurate as the normal incomplete beta functions. Up to
+ 5 iterations may be required in extreme cases, although normally only one
+ or two are required. Further, the number of iterations required decreases
+ with increasing /a</em></span> and <span class="emphasis"><em>b</em></span> (which generally
+ form the more important use cases).
+ </p>
+<p>
+ The initial guesses used for iteration are obtained as follows:
+ </p>
+<p>
+ Firstly recall that:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta_inv5.png"></span>
+ </p>
+<p>
+ We may wish to start from either p or q, and to calculate either x or y.
+ In addition at any stage we can exchange a for b, p for q, and x for y
+ if it results in a more manageable problem.
+ </p>
+<p>
+ For <code class="computeroutput"><span class="identifier">a</span><span class="special">+</span><span class="identifier">b</span> <span class="special">&gt;=</span> <span class="number">5</span></code> the initial guess is computed using the
+ methods described in:
+ </p>
+<p>
+ Asymptotic Inversion of the Incomplete Beta Function, by N. M. Temme.
+ Journal of Computational and Applied Mathematics 41 (1992) 145-157.
+ </p>
+<p>
+ The nearly symmetrical case (section 2 of the paper) is used for
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta_inv2.png"></span>
+ </p>
+<p>
+ and involves solving the inverse error function first. The method is accurate
+ to at least 2 decimal digits when <code class="literal">a = 5</code> rising to at
+ least 8 digits when <code class="literal">a = 10<sup>5</sup></code>.
+ </p>
+<p>
+ The general error function case (section 3 of the paper) is used for
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta_inv3.png"></span>
+ </p>
+<p>
+ and again expresses the inverse incomplete beta in terms of the inverse
+ of the error function. The method is accurate to at least 2 decimal digits
+ when <code class="literal">a+b = 5</code> rising to 11 digits when <code class="literal">a+b =
+ 10<sup>5</sup></code>. However, when the result is expected to be very small, and
+ when a+b is also small, then its accuracy tails off, in this case when
+ p<sup>1/a</sup> &lt; 0.0025 then it is better to use the following as an initial estimate:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta_inv4.png"></span>
+ </p>
+<p>
+ Finally the for all other cases where <code class="computeroutput"><span class="identifier">a</span><span class="special">+</span><span class="identifier">b</span> <span class="special">&gt;</span>
+ <span class="number">5</span></code> the method of section 4 of the
+ paper is used. This expresses the inverse incomplete beta in terms of the
+ inverse of the incomplete gamma function, and is therefore significantly
+ more expensive to compute than the other cases. However the method is accurate
+ to at least 3 decimal digits when <code class="literal">a = 5</code> rising to at
+ least 10 digits when <code class="literal">a = 10<sup>5</sup></code>. This method is limited
+ to a &gt; b, and therefore we need to perform an exchange a for b, p for
+ q and x for y when this is not the case. In addition when p is close to
+ 1 the method is inaccurate should we actually want y rather than x as output.
+ Therefore when q is small (<code class="literal">q<sup>1/p</sup> &lt; 10<sup>-3</sup></code>) we use:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta_inv6.png"></span>
+ </p>
+<p>
+ which is both cheaper to compute than the full method, and a more accurate
+ estimate on q.
+ </p>
+<p>
+ When a and b are both small there is a distinct lack of information in
+ the literature on how to proceed. I am extremely grateful to Prof Nico
+ Temme who provided the following information with a great deal of patience
+ and explanation on his part. Any errors that follow are entirely my own,
+ and not Prof Temme's.
+ </p>
+<p>
+ When a and b are both less than 1, then there is a point of inflection
+ in the incomplete beta at point <code class="computeroutput"><span class="identifier">xs</span>
+ <span class="special">=</span> <span class="special">(</span><span class="number">1</span> <span class="special">-</span> <span class="identifier">a</span><span class="special">)</span> <span class="special">/</span> <span class="special">(</span><span class="number">2</span> <span class="special">-</span> <span class="identifier">a</span>
+ <span class="special">-</span> <span class="identifier">b</span><span class="special">)</span></code>. Therefore if <code class="literal">p &gt; I<sub>x</sub>(a,b)</code>
+ we swap a for b, p for q and x for y, so that now we always look for a
+ point x below the point of inflection <code class="computeroutput"><span class="identifier">xs</span></code>,
+ and on a convex curve. An initial estimate for x is made with:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta_inv7.png"></span>
+ </p>
+<p>
+ which is provably below the true value for x: <a href="http://en.wikipedia.org/wiki/Newton%27s_method" target="_top">Newton
+ iteration</a> will therefore smoothly converge on x without problems
+ caused by overshooting etc.
+ </p>
+<p>
+ When a and b are both greater than 1, but a+b is too small to use the other
+ methods mentioned above, we proceed as follows. Observe that there is a
+ point of inflection in the incomplete beta at <code class="computeroutput"><span class="identifier">xs</span>
+ <span class="special">=</span> <span class="special">(</span><span class="number">1</span> <span class="special">-</span> <span class="identifier">a</span><span class="special">)</span> <span class="special">/</span> <span class="special">(</span><span class="number">2</span> <span class="special">-</span> <span class="identifier">a</span>
+ <span class="special">-</span> <span class="identifier">b</span><span class="special">)</span></code>. Therefore if <code class="literal">p &gt; I<sub>x</sub>(a,b)</code>
+ we swap a for b, p for q and x for y, so that now we always look for a
+ point x below the point of inflection <code class="computeroutput"><span class="identifier">xs</span></code>,
+ and on a concave curve. An initial estimate for x is made with:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta_inv4.png"></span>
+ </p>
+<p>
+ which can be improved somewhat to:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta_inv1.png"></span>
+ </p>
+<p>
+ when b and x are both small (I've used b &lt; a and x &lt; 0.2). This actually
+ under-estimates x, which drops us on the wrong side of x for Newton iteration
+ to converge monotonically. However, use of higher derivatives and Halley
+ iteration keeps everything under control.
+ </p>
+<p>
+ The final case to be considered if when one of a and b is less than or
+ equal to 1, and the other greater that 1. Here, if b &lt; a we swap a for
+ b, p for q and x for y. Now the curve of the incomplete beta is convex
+ with no points of inflection in [0,1]. For small p, x can be estimated
+ using
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta_inv4.png"></span>
+ </p>
+<p>
+ which under-estimates x, and drops us on the right side of the true value
+ for Newton iteration to converge monotonically. However, when p is large
+ this can quite badly underestimate x. This is especially an issue when
+ we really want to find y, in which case this method can be an arbitrary
+ number of order of magnitudes out, leading to very poor convergence during
+ iteration.
+ </p>
+<p>
+ Things can be improved by considering the incomplete beta as a distorted
+ quarter circle, and estimating y from:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/ibeta_inv8.png"></span>
+ </p>
+<p>
+ This doesn't guarantee that we will drop in on the right side of x for
+ monotonic convergence, but it does get us close enough that Halley iteration
+ rapidly converges on the true value.
+ </p>
+<a name="math_toolkit.special.sf_beta.ibeta_inv_function.implementation_of_inverses_on_the_a_and_b_parameters"></a><h5>
+<a name="id650687"></a>
+ <a href="ibeta_inv_function.html#math_toolkit.special.sf_beta.ibeta_inv_function.implementation_of_inverses_on_the_a_and_b_parameters">Implementation
+ of inverses on the a and b parameters</a>
+ </h5>
+<p>
+ These four functions share a common implementation.
+ </p>
+<p>
+ First an initial approximation is computed for <span class="emphasis"><em>a</em></span> or
+ <span class="emphasis"><em>b</em></span>: where possible this uses a Cornish-Fisher expansion
+ for the negative binomial distribution to get within around 1 of the result.
+ However, when <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span> are very
+ small the Cornish Fisher expansion is not usable, in this case the initial
+ approximation is chosen so that I<sub>x</sub>(a, b) is near the middle of the range
+ [0,1].
+ </p>
+<p>
+ This initial guess is then used as a starting value for a generic root
+ finding algorithm. The algorithm converges rapidly on the root once it
+ has been bracketed, but bracketing the root may take several iterations.
+ A better initial approximation for <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span>
+ would improve these functions quite substantially: currently 10-20 incomplete
+ beta function invocations are required to find the root.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ibeta_function.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_beta.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="beta_derivative.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_erf.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_erf.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,46 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Error Functions</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../special.html" title="Special Functions">
+<link rel="prev" href="sf_beta/beta_derivative.html" title="Derivative of the Incomplete Beta Function">
+<link rel="next" href="sf_erf/error_function.html" title="Error Functions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_beta/beta_derivative.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sf_erf/error_function.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.special.sf_erf"></a> Error Functions
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="sf_erf/error_function.html"> Error
+ Functions</a></span></dt>
+<dt><span class="section"><a href="sf_erf/error_inv.html"> Error Function
+ Inverses</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_beta/beta_derivative.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sf_erf/error_function.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_erf/error_function.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_erf/error_function.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,638 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Error Functions</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_erf.html" title="Error Functions">
+<link rel="prev" href="../sf_erf.html" title="Error Functions">
+<link rel="next" href="error_inv.html" title="Error Function Inverses">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../sf_erf.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_erf.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="error_inv.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_erf.error_function"></a><a href="error_function.html" title="Error Functions"> Error
+ Functions</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.sf_erf.error_function.synopsis"></a><h5>
+<a name="id651487"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">erf</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">erf</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">erf</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">erfc</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">erfc</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: the return type is <code class="computeroutput"><span class="keyword">double</span></code> if T is an integer type, and T otherwise.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<a name="math_toolkit.special.sf_erf.error_function.description"></a><h5>
+<a name="id652036"></a>
+ Description
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">erf</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">erf</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the <a href="http://en.wikipedia.org/wiki/Error_function" target="_top">error
+ function</a> erf
+ of z:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/erf1.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/erf1.png" alt="erf1"></span>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">erfc</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">erfc</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the complement of the <a href="http://functions.wolfram.com/GammaBetaErf/Erfc/" target="_top">error
+ function</a> of z:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/erf2.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/erf2.png" alt="erf2"></span>
+ </p>
+<a name="math_toolkit.special.sf_erf.error_function.accuracy"></a><h5>
+<a name="id652546"></a>
+ Accuracy
+ </h5>
+<p>
+ The following table shows the peak errors (in units of epsilon) found on
+ various platforms with various floating point types, along with comparisons
+ to the GSL-1.9,
+ GNU C Lib, HP-UX C Library
+ and Cephes libraries.
+ Unless otherwise specified any floating point type that is narrower than
+ the one shown will have effectively zero error.
+ </p>
+<div class="table">
+<a name="id652607"></a><p class="title"><b>Table 20. Errors In the Function erf(z)</b></p>
+<div class="table-contents"><table class="table" summary="Errors In the Function erf(z)">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ z &lt; 0.5
+ </p>
+ </th>
+<th>
+ <p>
+ 0.5 &lt; z &lt; 8
+ </p>
+ </th>
+<th>
+ <p>
+ z &gt; 8
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0 Mean=0
+ </p>
+ <p>
+ GSL Peak=2.0 Mean=0.3
+ </p>
+ <p>
+ Cephes Peak=1.1
+ Mean=0.7
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.9 Mean=0.09
+ </p>
+ <p>
+ GSL Peak=2.3 Mean=0.3
+ </p>
+ <p>
+ Cephes Peak=1.3
+ Mean=0.2
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0 Mean=0
+ </p>
+ <p>
+ GSL Peak=0 Mean=0
+ </p>
+ <p>
+ Cephes Peak=0
+ Mean=0
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ RedHat Linux IA32, gcc-3.3
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.7 Mean=0.07
+ </p>
+ <p>
+ GNU C Lib
+ Peak=0.9 Mean=0.2
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.9 Mean=0.2
+ </p>
+ <p>
+ GNU C Lib
+ Peak=0.9 Mean=0.07
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0 Mean=0
+ </p>
+ <p>
+ GNU C Lib
+ Peak=0 Mean=0
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA64, gcc-3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.7 Mean=0.07
+ </p>
+ <p>
+ GNU C Lib
+ Peak=0 Mean=0
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.9 Mean=0.1
+ </p>
+ <p>
+ GNU C Lib
+ Peak=0.5 Mean=0.03
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0 Mean=0
+ </p>
+ <p>
+ GNU C Lib
+ Peak=0 Mean=0
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.8 Mean=0.1
+ </p>
+ <p>
+ <a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX C
+ Library</a> Lib Peak=0.9 Mean=0.2
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.9 Mean=0.1
+ </p>
+ <p>
+ <a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX C
+ Library</a> Lib Peak=0.5 Mean=0.02
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0 Mean=0
+ </p>
+ <p>
+ <a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX C
+ Library</a> Lib Peak=0 Mean=0
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id652980"></a><p class="title"><b>Table 21. Errors In the Function erfc(z)</b></p>
+<div class="table-contents"><table class="table" summary="Errors In the Function erfc(z)">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ z &lt; 0.5
+ </p>
+ </th>
+<th>
+ <p>
+ 0.5 &lt; z &lt; 8
+ </p>
+ </th>
+<th>
+ <p>
+ z &gt; 8
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.7 Mean=0.06
+ </p>
+ <p>
+ GSL Peak=1.0 Mean=0.4
+ </p>
+ <p>
+ Cephes Peak=0.7
+ Mean=0.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.99 Mean=0.3
+ </p>
+ <p>
+ GSL Peak=2.6 Mean=0.6
+ </p>
+ <p>
+ Cephes Peak=3.6
+ Mean=0.7
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.0 Mean=0.2
+ </p>
+ <p>
+ GSL Peak=3.9 Mean=0.4
+ </p>
+ <p>
+ Cephes Peak=2.7
+ Mean=0.4
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ RedHat Linux IA32, gcc-3.3
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0 Mean=0
+ </p>
+ <p>
+ GNU C Lib
+ Peak=0 Mean=0
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.4 Mean=0.3
+ </p>
+ <p>
+ GNU C Lib
+ Peak=1.3 Mean=0.3
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.6 Mean=0.4
+ </p>
+ <p>
+ GNU C Lib
+ Peak=1.3 Mean=0.4
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA64, gcc-3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0 Mean=0
+ </p>
+ <p>
+ GNU C Lib
+ Peak=0 Mean=0
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.4 Mean=0.3
+ </p>
+ <p>
+ GNU C Lib
+ Peak=0 Mean=0
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.5 Mean=0.4
+ </p>
+ <p>
+ GNU C Lib
+ Peak=0 Mean=0
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0 Mean=0
+ </p>
+ <p>
+ <a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX C
+ Library</a> Peak=0 Mean=0
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.5 Mean=0.3
+ </p>
+ <p>
+ <a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX C
+ Library</a> Peak=0.9 Mean=0.08
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.6 Mean=0.4
+ </p>
+ <p>
+ <a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX C
+ Library</a> Peak=0.9 Mean=0.1
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><a name="math_toolkit.special.sf_erf.error_function.testing"></a><h5>
+<a name="id653363"></a>
+ Testing
+ </h5>
+<p>
+ The tests for these functions come in two parts: basic sanity checks use
+ spot values calculated using <a href="http://functions.wolfram.com/webMathematica/FunctionEvaluation.jsp?name=Erf" target="_top">Mathworld's
+ online evaluator</a>, while accuracy checks use high-precision test
+ values calculated at 1000-bit precision with NTL::RR
+ and this implementation. Note that the generic and type-specific versions
+ of these functions use differing implementations internally, so this gives
+ us reasonably independent test data. Using our test data to test other
+ "known good" implementations also provides an additional sanity
+ check.
+ </p>
+<a name="math_toolkit.special.sf_erf.error_function.implementation"></a><h5>
+<a name="id653416"></a>
+ Implementation
+ </h5>
+<p>
+ All versions of these functions first use the usual reflection formulas
+ to make their arguments positive:
+ </p>
+<pre class="programlisting">
+<span class="identifier">erf</span><span class="special">(-</span><span class="identifier">z</span><span class="special">)</span> <span class="special">=</span> <span class="number">1</span> <span class="special">-</span> <span class="identifier">erf</span><span class="special">(</span><span class="identifier">z</span><span class="special">);</span>
+
+<span class="identifier">erfc</span><span class="special">(-</span><span class="identifier">z</span><span class="special">)</span> <span class="special">=</span> <span class="number">2</span> <span class="special">-</span> <span class="identifier">erfc</span><span class="special">(</span><span class="identifier">z</span><span class="special">);</span> <span class="comment">// preferred when -z &lt; -0.5
+</span>
+<span class="identifier">erfc</span><span class="special">(-</span><span class="identifier">z</span><span class="special">)</span> <span class="special">=</span> <span class="number">1</span> <span class="special">+</span> <span class="identifier">erf</span><span class="special">(</span><span class="identifier">z</span><span class="special">);</span> <span class="comment">// preferred when -0.5 &lt;= -z &lt; 0
+</span></pre>
+<p>
+ The generic versions of these functions are implemented in terms of the
+ incomplete gamma function.
+ </p>
+<p>
+ When the significand (mantissa) size is recognised (currently for 53, 64
+ and 113-bit reals, plus single-precision 24-bit handled via promotion to
+ double) then a series of rational approximations <a href="../../backgrounders/implementation.html#math_toolkit.backgrounders.implementation.rational_approximations_used">devised
+ by JM</a> are used.
+ </p>
+<p>
+ For <code class="computeroutput"><span class="identifier">z</span> <span class="special">&lt;=</span>
+ <span class="number">0.5</span></code> then a rational approximation
+ to erf is used, based on the observation that:
+ </p>
+<pre class="programlisting">
+<span class="identifier">erf</span><span class="special">(</span><span class="identifier">z</span><span class="special">)/</span><span class="identifier">z</span> <span class="special">~</span> <span class="number">1.12</span><span class="special">....</span>
+</pre>
+<p>
+ Therefore erf is calculated using:
+ </p>
+<pre class="programlisting">
+<span class="identifier">erf</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">z</span> <span class="special">*</span> <span class="special">(</span><span class="number">1.125F</span> <span class="special">+</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">z</span><span class="special">));</span>
+</pre>
+<p>
+ where the rational approximation R(z) is optimised for absolute error:
+ as long as its absolute error is small enough compared to 1.125, then any
+ round-off error incurred during the computation of R(z) will effectively
+ disappear from the result. As a result the error for erf and erfc in this
+ region is very low: the last bit is incorrect in only a very small number
+ of cases.
+ </p>
+<p>
+ For <code class="computeroutput"><span class="identifier">z</span> <span class="special">&gt;</span>
+ <span class="number">0.5</span></code> we observe that over a small
+ interval [a, b) then:
+ </p>
+<pre class="programlisting">
+<span class="identifier">erfc</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">exp</span><span class="special">(</span><span class="identifier">z</span><span class="special">*</span><span class="identifier">z</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">z</span> <span class="special">~</span> <span class="identifier">c</span>
+</pre>
+<p>
+ for some constant c.
+ </p>
+<p>
+ Therefore for <code class="computeroutput"><span class="identifier">z</span> <span class="special">&gt;</span>
+ <span class="number">0.5</span></code> we calculate erfc using:
+ </p>
+<pre class="programlisting">
+<span class="identifier">erfc</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">exp</span><span class="special">(-</span><span class="identifier">z</span><span class="special">*</span><span class="identifier">z</span><span class="special">)</span> <span class="special">*</span> <span class="special">(</span><span class="identifier">c</span> <span class="special">+</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">z</span><span class="special">))</span> <span class="special">/</span> <span class="identifier">z</span><span class="special">;</span>
+</pre>
+<p>
+ Again R(z) is optimised for absolute error, and the constant <code class="computeroutput"><span class="identifier">c</span></code> is the average of <code class="computeroutput"><span class="identifier">erfc</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span>
+ <span class="special">*</span> <span class="identifier">exp</span><span class="special">(</span><span class="identifier">z</span><span class="special">*</span><span class="identifier">z</span><span class="special">)</span> <span class="special">*</span>
+ <span class="identifier">z</span></code> taken at the endpoints of the
+ range. Once again, as long as the absolute error in R(z) is small compared
+ to <code class="computeroutput"><span class="identifier">c</span></code> then <code class="computeroutput"><span class="identifier">c</span> <span class="special">+</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span></code> will be correctly rounded, and the error
+ in the result will depend only on the accuracy of the exp function. In
+ practice, in all but a very small number of cases, the error is confined
+ to the last bit of the result.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../sf_erf.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_erf.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="error_inv.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_erf/error_inv.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_erf/error_inv.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,216 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Error Function Inverses</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_erf.html" title="Error Functions">
+<link rel="prev" href="error_function.html" title="Error Functions">
+<link rel="next" href="../sf_poly.html" title="Polynomials">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="error_function.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_erf.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../sf_poly.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_erf.error_inv"></a><a href="error_inv.html" title="Error Function Inverses"> Error Function
+ Inverses</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.sf_erf.error_inv.synopsis"></a><h5>
+<a name="id654289"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">erf</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">erf_inv</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">p</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">erf_inv</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">erfc_inv</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">p</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">erfc_inv</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: the return type is <code class="computeroutput"><span class="keyword">double</span></code> if T is an integer type, and T otherwise.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<a name="math_toolkit.special.sf_erf.error_inv.description"></a><h5>
+<a name="id654839"></a>
+ Description
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">erf_inv</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">erf_inv</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the <a href="http://functions.wolfram.com/GammaBetaErf/InverseErf/" target="_top">inverse
+ error function</a> of z, that is a value x such that:
+ </p>
+<pre class="programlisting">
+<span class="identifier">p</span> <span class="special">=</span> <span class="identifier">erf</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span>
+</pre>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/erf_inv.png" alt="erf_inv"></span>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">erfc_inv</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">erfc_inv</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the inverse of the complement of the error function of z, that
+ is a value x such that:
+ </p>
+<pre class="programlisting">
+<span class="identifier">p</span> <span class="special">=</span> <span class="identifier">erfc</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span>
+</pre>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/erfc_inv.png" alt="erfc_inv"></span>
+ </p>
+<a name="math_toolkit.special.sf_erf.error_inv.accuracy"></a><h5>
+<a name="id655359"></a>
+ Accuracy
+ </h5>
+<p>
+ For types up to and including 80-bit long doubles the approximations used
+ are accurate to less than ~ 2 epsilon. For higher precision types these
+ functions have the same accuracy as the <a href="error_function.html" title="Error Functions">forward
+ error functions</a>.
+ </p>
+<a name="math_toolkit.special.sf_erf.error_inv.testing"></a><h5>
+<a name="id655400"></a>
+ Testing
+ </h5>
+<p>
+ There are two sets of tests:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Basic sanity checks attempt to "round-trip" from <span class="emphasis"><em>x</em></span>
+ to <span class="emphasis"><em>p</em></span> and back again. These tests have quite generous
+ tolerances: in general both the error functions and their inverses change
+ so rapidly in some places that round tripping to more than a couple of
+ significant digits isn't possible. This is especially true when <span class="emphasis"><em>p</em></span>
+ is very near one: in this case there isn't enough "information content"
+ in the input to the inverse function to get back where you started.
+ </li>
+<li>
+ Accuracy checks using high-precision test values. These measure the accuracy
+ of the result, given <span class="emphasis"><em>exact</em></span> input values.
+ </li>
+</ul></div>
+<a name="math_toolkit.special.sf_erf.error_inv.implementation"></a><h5>
+<a name="id655462"></a>
+ Implementation
+ </h5>
+<p>
+ These functions use a rational approximation <a href="../../backgrounders/implementation.html#math_toolkit.backgrounders.implementation.rational_approximations_used">devised
+ by JM</a> to calculate an initial approximation to the result that is
+ accurate to ~10<sup>-19</sup>, then only if that has insufficient accuracy compared
+ to the epsilon for T, do we clean up the result using <a href="http://en.wikipedia.org/wiki/Simple_rational_approximation" target="_top">Halley
+ iteration</a>.
+ </p>
+<p>
+ Constructing rational approximations to the erf/erfc functions is actually
+ surprisingly hard, especially at high precision. For this reason no attempt
+ has been made to achieve 10<sup>-34 </sup> accuracy suitable for use with 128-bit reals.
+ </p>
+<p>
+ In the following discussion, <span class="emphasis"><em>p</em></span> is the value passed
+ to erf_inv, and <span class="emphasis"><em>q</em></span> is the value passed to erfc_inv,
+ so that <span class="emphasis"><em>p = 1 - q</em></span> and <span class="emphasis"><em>q = 1 - p</em></span>
+ and in both cases we want to solve for the same result <span class="emphasis"><em>x</em></span>.
+ </p>
+<p>
+ For <span class="emphasis"><em>p &lt; 0.5</em></span> the inverse erf function is reasonably
+ smooth and the approximation:
+ </p>
+<pre class="programlisting">
+<span class="identifier">x</span> <span class="special">=</span> <span class="identifier">p</span><span class="special">(</span><span class="identifier">p</span> <span class="special">+</span> <span class="number">10</span><span class="special">)(</span><span class="identifier">Y</span> <span class="special">+</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">p</span><span class="special">))</span>
+</pre>
+<p>
+ Gives a good result for a constant Y, and R(p) optimised for low absolute
+ error compared to |Y|.
+ </p>
+<p>
+ For q &lt; 0.5 things get trickier, over the interval <span class="emphasis"><em>0.5 &gt;
+ q &gt; 0.25</em></span> the following approximation works well:
+ </p>
+<pre class="programlisting">
+<span class="identifier">x</span> <span class="special">=</span> <span class="identifier">sqrt</span><span class="special">(-</span><span class="number">2l</span><span class="identifier">og</span><span class="special">(</span><span class="identifier">q</span><span class="special">))</span> <span class="special">/</span> <span class="special">(</span><span class="identifier">Y</span> <span class="special">+</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">q</span><span class="special">))</span>
+</pre>
+<p>
+ While for q &lt; 0.25, let
+ </p>
+<pre class="programlisting">
+<span class="identifier">z</span> <span class="special">=</span> <span class="identifier">sqrt</span><span class="special">(-</span><span class="identifier">log</span><span class="special">(</span><span class="identifier">q</span><span class="special">))</span>
+</pre>
+<p>
+ Then the result is given by:
+ </p>
+<pre class="programlisting">
+<span class="identifier">x</span> <span class="special">=</span> <span class="identifier">z</span><span class="special">(</span><span class="identifier">Y</span> <span class="special">+</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">z</span> <span class="special">-</span> <span class="identifier">B</span><span class="special">))</span>
+</pre>
+<p>
+ As before Y is a constant and the rational function R is optimised for
+ low absolute error compared to |Y|. B is also a constant: it is the smallest
+ value of <span class="emphasis"><em>z</em></span> for which each approximation is valid.
+ There are several approximations of this form each of which reaches a little
+ further into the tail of the erfc function (at <code class="computeroutput"><span class="keyword">long</span>
+ <span class="keyword">double</span></code> precision the extended exponent
+ range compared to <code class="computeroutput"><span class="keyword">double</span></code> means
+ that the tail goes on for a very long way indeed).
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="error_function.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_erf.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../sf_poly.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,53 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Gamma Functions</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../special.html" title="Special Functions">
+<link rel="prev" href="../special.html" title="Special Functions">
+<link rel="next" href="sf_gamma/tgamma.html" title="Gamma">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../special.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sf_gamma/tgamma.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.special.sf_gamma"></a> Gamma Functions
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"> Gamma</span></dt>
+<dt><span class="section"> Log Gamma</span></dt>
+<dt><span class="section"> Digamma</span></dt>
+<dt><span class="section"><a href="sf_gamma/gamma_ratios.html"> Ratios
+ of Gamma Functions</a></span></dt>
+<dt><span class="section"><a href="sf_gamma/igamma.html"> Incomplete Gamma
+ Functions</a></span></dt>
+<dt><span class="section"><a href="sf_gamma/igamma_inv.html"> Incomplete
+ Gamma Function Inverses</a></span></dt>
+<dt><span class="section"><a href="sf_gamma/gamma_derivatives.html"> Derivative
+ of the Incomplete Gamma Function</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../special.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sf_gamma/tgamma.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/digamma.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/digamma.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,396 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Digamma</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_gamma.html" title="Gamma Functions">
+<link rel="prev" href="lgamma.html" title="Log Gamma">
+<link rel="next" href="gamma_ratios.html" title="Ratios of Gamma Functions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lgamma.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="gamma_ratios.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_gamma.digamma"></a> Digamma
+</h4></div></div></div>
+<a name="math_toolkit.special.sf_gamma.digamma.synopsis"></a><h5>
+<a name="id622374"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">digamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">digamma</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">digamma</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.sf_gamma.digamma.description"></a><h5>
+<a name="id622697"></a>
+ Description
+ </h5>
+<p>
+ Returns the digamma or psi function of <span class="emphasis"><em>x</em></span>. Digamma
+ is defined as the logarithmic derivative of the gamma function:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/digamma1.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/digamma.png" alt="digamma"></span>
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ There is no fully generic version of this function: all the implementations
+ are tuned to specific accuracy levels, the most precise of which delivers
+ 34-digits of precision.
+ </p>
+<p>
+ The return type of this function is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: the result is of type <code class="computeroutput"><span class="keyword">double</span></code> when T is an integer type, and type
+ T otherwise.
+ </p>
+<a name="math_toolkit.special.sf_gamma.digamma.accuracy"></a><h5>
+<a name="id622843"></a>
+ Accuracy
+ </h5>
+<p>
+ The following table shows the peak errors (in units of epsilon) found on
+ various platforms with various floating point types. Unless otherwise specified
+ any floating point type that is narrower than the one shown will have
+ effectively zero error.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ Random Positive Values
+ </p>
+ </th>
+<th>
+ <p>
+ Values Near The Positive Root
+ </p>
+ </th>
+<th>
+ <p>
+ Values Near Zero
+ </p>
+ </th>
+<th>
+ <p>
+ Negative Values
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32 Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.98 Mean=0.36
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.99 Mean=0.5
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.95 Mean=0.5
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=214 Mean=16
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Linux IA32 / GCC
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.4 Mean=0.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.3 Mean=0.45
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.98 Mean=0.35
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=180 Mean=13
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Linux IA64 / GCC
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.92 Mean=0.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.3 Mean=0.45
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.98 Mean=0.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=180 Mean=13
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.9 Mean=0.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.1 Mean=0.5
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.99 Mean=0.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=64 Mean=6
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<p>
+ As shown above, error rates for positive arguments are generally very low.
+ For negative arguments there are an infinite number of irrational roots:
+ relative errors very close to these can be arbitrarily large, although
+ absolute error will remain very low.
+ </p>
+<a name="math_toolkit.special.sf_gamma.digamma.testing"></a><h5>
+<a name="id623147"></a>
+ Testing
+ </h5>
+<p>
+ There are two sets of tests: spot values are computed using the online
+ calculator at functions.wolfram.com, while random test values are generated
+ using the high-precision reference implementation (a differentiated Lanczos approximation
+ see below).
+ </p>
+<a name="math_toolkit.special.sf_gamma.digamma.implementation"></a><h5>
+<a name="id623189"></a>
+ Implementation
+ </h5>
+<p>
+ The implementation is divided up into the following domains:
+ </p>
+<p>
+ For Negative arguments the reflection formula:
+ </p>
+<pre class="programlisting">
+<span class="identifier">digamma</span><span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">x</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">digamma</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">pi</span><span class="special">/</span><span class="identifier">tan</span><span class="special">(</span><span class="identifier">pi</span><span class="special">*</span><span class="identifier">x</span><span class="special">);</span>
+</pre>
+<p>
+ is used to make <span class="emphasis"><em>x</em></span> positive.
+ </p>
+<p>
+ For arguments in the range [0,1] the recurrence relation:
+ </p>
+<pre class="programlisting">
+<span class="identifier">digamma</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">digamma</span><span class="special">(</span><span class="identifier">x</span><span class="special">+</span><span class="number">1</span><span class="special">)</span> <span class="special">-</span> <span class="number">1</span><span class="special">/</span><span class="identifier">x</span>
+</pre>
+<p>
+ is used to shift the evaluation to [1,2].
+ </p>
+<p>
+ For arguments in the range [1,2] a rational approximation <a href="../../backgrounders/implementation.html#math_toolkit.backgrounders.implementation.rational_approximations_used">devised
+ by JM</a> is used (see below).
+ </p>
+<p>
+ For arguments in the range [2,BIG] the recurrence relation:
+ </p>
+<pre class="programlisting">
+<span class="identifier">digamma</span><span class="special">(</span><span class="identifier">x</span><span class="special">+</span><span class="number">1</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">digamma</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">+</span> <span class="number">1</span><span class="special">/</span><span class="identifier">x</span><span class="special">;</span>
+</pre>
+<p>
+ is used to shift the evaluation to the range [1,2].
+ </p>
+<p>
+ For arguments &gt; BIG the asymptotic expansion:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/digamma2.png"></span>
+ </p>
+<p>
+ can be used. However, this expansion is divergent after a few terms: exactly
+ how many terms depends on the size of <span class="emphasis"><em>x</em></span>. Therefore
+ the value of <span class="emphasis"><em>BIG</em></span> must be chosen so that the series
+ can be truncated at a term that is too small to have any effect on the
+ result when evaluated at <span class="emphasis"><em>BIG</em></span>. Choosing BIG=10 for
+ up to 80-bit reals, and BIG=20 for 128-bit reals allows the series to truncated
+ after a suitably small number of terms and evaluated as a polynomial in
+ <code class="computeroutput"><span class="number">1</span><span class="special">/(</span><span class="identifier">x</span><span class="special">*</span><span class="identifier">x</span><span class="special">)</span></code>.
+ </p>
+<p>
+ The rational approximation <a href="../../backgrounders/implementation.html#math_toolkit.backgrounders.implementation.rational_approximations_used">devised
+ by JM</a> in the range [1,2] is derived as follows.
+ </p>
+<p>
+ First a high precision approximation to digamma was constructed using a
+ 60-term differentiated <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a>, the form used is:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/digamma3.png"></span>
+ </p>
+<p>
+ Where P(x) and Q(x) are the polynomials from the rational form of the Lanczos
+ sum, and P'(x) and Q'(x) are their first derivatives. The Lanzos part of
+ this approximation has a theoretical precision of ~100 decimal digits.
+ However, cancellation in the above sum will reduce that to around <code class="computeroutput"><span class="number">99</span><span class="special">-(</span><span class="number">1</span><span class="special">/</span><span class="identifier">y</span><span class="special">)</span></code>
+ digits if <span class="emphasis"><em>y</em></span> is the result. This approximation was
+ used to calculate the positive root of digamma, and was found to agree
+ with the value used by Cody to 25 digits (See Math. Comp. 27, 123-127 (1973)
+ by Cody, Strecok and Thacher) and with the value used by Morris to 35 digits
+ (See TOMS Algorithm 708).
+ </p>
+<p>
+ Likewise a few spot tests agreed with values calculated using functions.wolfram.com
+ to &gt;40 digits. That's sufficiently precise to insure that the approximation
+ below is accurate to double precision. Achieving 128-bit long double precision
+ requires that the location of the root is known to ~70 digits, and it's
+ not clear whether the value calculated by this method meets that requirement:
+ the difficulty lies in independently verifying the value obtained.
+ </p>
+<p>
+ The rational approximation <a href="../../backgrounders/implementation.html#math_toolkit.backgrounders.implementation.rational_approximations_used">devised
+ by JM</a> was optimised for absolute error using the form:
+ </p>
+<pre class="programlisting">
+<span class="identifier">digamma</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">x</span> <span class="special">-</span> <span class="identifier">X0</span><span class="special">)(</span><span class="identifier">Y</span> <span class="special">+</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">x</span> <span class="special">-</span> <span class="number">1</span><span class="special">));</span>
+</pre>
+<p>
+ Where X0 is the positive root of digamma, Y is a constant, and R(x - 1)
+ is the rational approximation. Note that since X0 is irrational, we need
+ twice as many digits in X0 as in x in order to avoid cancellation error
+ during the subtraction (this assumes that <span class="emphasis"><em>x</em></span> is an
+ exact value, if it's not then all bets are off). That means that even when
+ x is the value of the root rounded to the nearest representable value,
+ the result of digamma(x) <span class="emphasis"><em><span class="bold"><strong>will not be zero</strong></span></em></span>.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="lgamma.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="gamma_ratios.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/gamma_derivatives.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/gamma_derivatives.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,112 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Derivative of the Incomplete Gamma Function</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_gamma.html" title="Gamma Functions">
+<link rel="prev" href="igamma_inv.html" title="Incomplete Gamma Function Inverses">
+<link rel="next" href="../factorials.html" title="Factorials and Binomial Coefficients">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="igamma_inv.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../factorials.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_gamma.gamma_derivatives"></a><a href="gamma_derivatives.html" title="Derivative of the Incomplete Gamma Function"> Derivative
+ of the Incomplete Gamma Function</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.sf_gamma.gamma_derivatives.synopsis"></a><h5>
+<a name="id633277"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_p_derivative</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_p_derivative</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.sf_gamma.gamma_derivatives.description"></a><h5>
+<a name="id633670"></a>
+ Description
+ </h5>
+<p>
+ This function find some uses in statistical distributions: it implements
+ the partial derivative with respect to <span class="emphasis"><em>x</em></span> of the incomplete
+ gamma function.
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/derivative1.png"></span>
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ Note that the derivative of the function gamma_q
+ can be obtained by negating the result of this function.
+ </p>
+<p>
+ The return type of this function is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when T1 and T2 are different types,
+ otherwise the return type is simply T1.
+ </p>
+<a name="math_toolkit.special.sf_gamma.gamma_derivatives.accuracy"></a><h5>
+<a name="id633795"></a>
+ Accuracy
+ </h5>
+<p>
+ Almost identical to the incomplete gamma function gamma_p:
+ refer to the documentation for that function for more information.
+ </p>
+<a name="math_toolkit.special.sf_gamma.gamma_derivatives.implementation"></a><h5>
+<a name="id633836"></a>
+ Implementation
+ </h5>
+<p>
+ This function just expose some of the internals of the incomplete gamma
+ function gamma_p:
+ refer to the documentation for that function for more information.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="igamma_inv.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../factorials.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/gamma_ratios.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/gamma_ratios.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,367 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Ratios of Gamma Functions</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_gamma.html" title="Gamma Functions">
+<link rel="prev" href="digamma.html" title="Digamma">
+<link rel="next" href="igamma.html" title="Incomplete Gamma Functions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="digamma.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="igamma.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_gamma.gamma_ratios"></a><a href="gamma_ratios.html" title="Ratios of Gamma Functions"> Ratios
+ of Gamma Functions</a>
+</h4></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma_ratio</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma_ratio</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma_delta_ratio</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">delta</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policy</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma_delta_ratio</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">delta</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.sf_gamma.gamma_ratios.description"></a><h5>
+<a name="id624568"></a>
+ Description
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma_ratio</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma_ratio</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the ratio of gamma functions:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/gamma_ratio0.png"></span>
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ Internally this just calls <code class="computeroutput"><span class="identifier">tgamma_delta_ratio</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
+ <span class="identifier">b</span><span class="special">-</span><span class="identifier">a</span><span class="special">)</span></code>.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma_delta_ratio</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">delta</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma_delta_ratio</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">delta</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the ratio of gamma functions:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/gamma_ratio1.png"></span>
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ Note that the result is calculated accurately even when <span class="emphasis"><em>delta</em></span>
+ is small compared to <span class="emphasis"><em>a</em></span>: indeed even if <span class="emphasis"><em>a+delta
+ ~ a</em></span>. The function is typically used when <span class="emphasis"><em>a</em></span>
+ is large and <span class="emphasis"><em>delta</em></span> is very small.
+ </p>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when T1 and T2 are different types,
+ otherwise the result type is simple T1.
+ </p>
+<a name="math_toolkit.special.sf_gamma.gamma_ratios.accuracy"></a><h5>
+<a name="id625306"></a>
+ Accuracy
+ </h5>
+<p>
+ The following table shows the peak errors (in units of epsilon) found on
+ various platforms with various floating point types. Unless otherwise specified
+ any floating point type that is narrower than the one shown will have
+ effectively zero error.
+ </p>
+<div class="table">
+<a name="id625339"></a><p class="title"><b>Table 9. Errors In the Function tgamma_delta_ratio(a, delta)</b></p>
+<div class="table-contents"><table class="table" summary="Errors In the Function tgamma_delta_ratio(a, delta)">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ 20 &lt; a &lt; 80
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ delta &lt; 1
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=16.9 Mean=1.7
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA32, gcc-3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=24 Mean=2.7
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA64, gcc-3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=12.8 Mean=1.8
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=21.4 Mean=2.3
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id625500"></a><p class="title"><b>Table 10. Errors In the Function tgamma_ratio(a,
+ b)</b></p>
+<div class="table-contents"><table class="table" summary="Errors In the Function tgamma_ratio(a,
+ b)">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ 6 &lt; a,b &lt; 50
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=34 Mean=9
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA32, gcc-3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=91 Mean=23
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA64, gcc-3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=35.6 Mean=9.3
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=43.9 Mean=13.2
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><a name="math_toolkit.special.sf_gamma.gamma_ratios.testing"></a><h5>
+<a name="id625662"></a>
+ Testing
+ </h5>
+<p>
+ Accuracy tests use data generated at very high precision (with <a href="http://shoup.net/ntl/doc/RR.txt" target="_top">NTL
+ RR class</a> set at 1000-bit precision: about 300 decimal digits) and
+ a deliberately naive calculation of &#915;(x)/&#915;(y).
+ </p>
+<a name="math_toolkit.special.sf_gamma.gamma_ratios.implementation"></a><h5>
+<a name="id625702"></a>
+ Implementation
+ </h5>
+<p>
+ The implementation of these functions is very similar to that of beta, and is
+ based on combining similar power terms to improve accuracy and avoid spurious
+ overflow/underflow.
+ </p>
+<p>
+ In addition there are optimisations for the situation where <span class="emphasis"><em>delta</em></span>
+ is a small integer: in which case this function is basically the reciprocal
+ of a rising factorial, or where both arguments are smallish integers: in
+ which case table lookup of factorials can be used to calculate the ratio.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="digamma.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="igamma.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/igamma.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/igamma.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,1058 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Incomplete Gamma Functions</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_gamma.html" title="Gamma Functions">
+<link rel="prev" href="gamma_ratios.html" title="Ratios of Gamma Functions">
+<link rel="next" href="igamma_inv.html" title="Incomplete Gamma Function Inverses">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="gamma_ratios.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="igamma_inv.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_gamma.igamma"></a><a href="igamma.html" title="Incomplete Gamma Functions"> Incomplete Gamma
+ Functions</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.sf_gamma.igamma.synopsis"></a><h5>
+<a name="id625775"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_p</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_p</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_q</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_q</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma_lower</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma_lower</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.sf_gamma.igamma.description"></a><h5>
+<a name="id626884"></a>
+ Description
+ </h5>
+<p>
+ There are four <a href="http://mathworld.wolfram.com/IncompleteGammaFunction.html" target="_top">incomplete
+ gamma functions</a>: two are normalised versions (also known as <span class="emphasis"><em>regularized</em></span>
+ incomplete gamma functions) that return values in the range [0, 1], and
+ two are non-normalised and return values in the range [0, &#915;(a)]. Users interested
+ in statistical applications should use the <a href="http://mathworld.wolfram.com/RegularizedGammaFunction.html" target="_top">normalised
+ versions (gamma_p and gamma_q)</a>.
+ </p>
+<p>
+ All of these functions require <span class="emphasis"><em>a &gt; 0</em></span> and <span class="emphasis"><em>z
+ &gt;= 0</em></span>, otherwise they return the result of domain_error.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when T1 and T2 are different types,
+ otherwise the return type is simply T1.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_p</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policy</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_p</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the normalised lower incomplete gamma function of a and z:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/igamma4.png"></span>
+ </p>
+<p>
+ This function changes rapidly from 0 to 1 around the point z == a:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/gamma_p.png" alt="gamma_p"></span>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_q</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_q</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the normalised upper incomplete gamma function of a and z:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/igamma3.png"></span>
+ </p>
+<p>
+ This function changes rapidly from 1 to 0 around the point z == a:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/gamma_q.png" alt="gamma_q"></span>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma_lower</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma_lower</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the full (non-normalised) lower incomplete gamma function of a
+ and z:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/igamma2.png"></span>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the full (non-normalised) upper incomplete gamma function of a
+ and z:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/igamma1.png"></span>
+ </p>
+<a name="math_toolkit.special.sf_gamma.igamma.accuracy"></a><h5>
+<a name="id628184"></a>
+ Accuracy
+ </h5>
+<p>
+ The following tables give peak and mean relative errors in over various
+ domains of a and z, along with comparisons to the GSL-1.9
+ and Cephes libraries.
+ Note that only results for the widest floating point type on the system
+ are given as narrower types have <a href="../../backgrounders/relative_error.html#zero_error">effectively
+ zero error</a>.
+ </p>
+<p>
+ Note that errors grow as <span class="emphasis"><em>a</em></span> grows larger.
+ </p>
+<p>
+ Note also that the higher error rates for the 80 and 128 bit long double
+ results are somewhat misleading: expected results that are zero at 64-bit
+ double precision may be non-zero - but exceptionally small - with the larger
+ exponent range of a long double. These results therefore reflect the more
+ extreme nature of the tests conducted for these types.
+ </p>
+<p>
+ All values are in units of epsilon.
+ </p>
+<div class="table">
+<a name="id628253"></a><p class="title"><b>Table 11. Errors In the Function gamma_p(a,z)</b></p>
+<div class="table-contents"><table class="table" summary="Errors In the Function gamma_p(a,z)">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ 0.5 &lt; a &lt; 100
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0.01*a &lt; z &lt; 100*a
+ </p>
+ </th>
+<th>
+ <p>
+ 1x10<sup>-12</sup> &lt; a &lt; 5x10<sup>-2</sup>
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0.01*a &lt; z &lt; 100*a
+ </p>
+ </th>
+<th>
+ <p>
+ 1e-6 &lt; a &lt; 1.7x10<sup>6</sup>
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 1 &lt; z &lt; 100*a
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=36 Mean=9.1
+ </p>
+ <p>
+ (GSL Peak=342 Mean=46)
+ </p>
+ <p>
+ (Cephes Peak=491
+ Mean=102)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4.5 Mean=1.4
+ </p>
+ <p>
+ (GSL Peak=4.8 Mean=0.76)
+ </p>
+ <p>
+ (Cephes Peak=21
+ Mean=5.6)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=244 Mean=21
+ </p>
+ <p>
+ (GSL Peak=1022 Mean=1054)
+ </p>
+ <p>
+ (Cephes Peak~8x10<sup>6</sup> Mean~7x10<sup>4</sup>)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ RedHat Linux IA32, gcc-3.3
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=241 Mean=36
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4.7 Mean=1.5
+ </p>
+ </td>
+<td>
+ <p>
+ Peak~30,220 Mean=1929
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA64, gcc-3.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=41 Mean=10
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4.7 Mean=1.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak~30,790 Mean=1864
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=40.2 Mean=10.2
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=5 Mean=1.6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=5,476 Mean=440
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id628572"></a><p class="title"><b>Table 12. Errors In the Function gamma_q(a,z)</b></p>
+<div class="table-contents"><table class="table" summary="Errors In the Function gamma_q(a,z)">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ 0.5 &lt; a &lt; 100
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0.01*a &lt; z &lt; 100*a
+ </p>
+ </th>
+<th>
+ <p>
+ 1x10<sup>-12</sup> &lt; a &lt; 5x10<sup>-2</sup>
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0.01*a &lt; z &lt; 100*a
+ </p>
+ </th>
+<th>
+ <p>
+ 1x10<sup>-6</sup> &lt; a &lt; 1.7x10<sup>6</sup>
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 1 &lt; z &lt; 100*a
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=28.3 Mean=7.2
+ </p>
+ <p>
+ (GSL Peak=201 Mean=13)
+ </p>
+ <p>
+ (Cephes Peak=556
+ Mean=97)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4.8 Mean=1.6
+ </p>
+ <p>
+ (GSL Peak~1.3x10<sup>10</sup> Mean=1x10<sup>+9</sup>)
+ </p>
+ <p>
+ (Cephes Peak~3x10<sup>11</sup> Mean=4x10<sup>10</sup>)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=469 Mean=33
+ </p>
+ <p>
+ (GSL Peak=27,050 Mean=2159)
+ </p>
+ <p>
+ (Cephes Peak~8x10<sup>6</sup> Mean~7x10<sup>5</sup>)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ RedHat Linux IA32, gcc-3.3
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=280 Mean=33
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4.1 Mean=1.6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=11,490 Mean=732
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA64, gcc-3.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=32 Mean=9.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4.7 Mean=1.5
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=6815 Mean=414
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=37 Mean=10
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=11.2 Mean=2.0
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4,999 Mean=298
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id628910"></a><p class="title"><b>Table 13. Errors In the Function tgamma_lower(a,z)</b></p>
+<div class="table-contents"><table class="table" summary="Errors In the Function tgamma_lower(a,z)">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ 0.5 &lt; a &lt; 100
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0.01*a &lt; z &lt; 100*a
+ </p>
+ </th>
+<th>
+ <p>
+ 1x10<sup>-12</sup> &lt; a &lt; 5x10<sup>-2</sup>
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0.01*a &lt; z &lt; 100*a
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=5.5 Mean=1.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=3.6 Mean=0.78
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ RedHat Linux IA32, gcc-3.3
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=402 Mean=79
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=3.4 Mean=0.8
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA64, gcc-3.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=6.8 Mean=1.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=3.4 Mean=0.78
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=6.1 Mean=1.8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=3.7 Mean=0.89
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id629123"></a><p class="title"><b>Table 14. Errors In the Function tgamma(a,z)</b></p>
+<div class="table-contents"><table class="table" summary="Errors In the Function tgamma(a,z)">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ 0.5 &lt; a &lt; 100
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0.01*a &lt; z &lt; 100*a
+ </p>
+ </th>
+<th>
+ <p>
+ 1x10<sup>-12</sup> &lt; a &lt; 5x10<sup>-2</sup>
+ </p>
+ <p>
+ and
+ </p>
+ <p>
+ 0.01*a &lt; z &lt; 100*a
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=5.9 Mean=1.5
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.8 Mean=0.6
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ RedHat Linux IA32, gcc-3.3
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=596 Mean=116
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=3.2 Mean=0.84
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Redhat Linux IA64, gcc-3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=40.2 Mean=2.5
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=3.2 Mean=0.8
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=364 Mean=17.6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=12.7 Mean=1.8
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><a name="math_toolkit.special.sf_gamma.igamma.testing"></a><h5>
+<a name="id629344"></a>
+ Testing
+ </h5>
+<p>
+ There are two sets of tests: spot tests compare values taken from Mathworld's online evaluator
+ with this implementation to perform a basic "sanity check". Accuracy
+ tests use data generated at very high precision (using NTL's RR class set
+ at 1000-bit precision) using this implementation with a very high precision
+ 60-term Lanczos approximation,
+ and some but not all of the special case handling disabled. This is less
+ than satisfactory: an independent method should really be used, but apparently
+ a complete lack of such methods are available. We can't even use a deliberately
+ naive implementation without special case handling since Legendre's continued
+ fraction (see below) is unstable for small a and z.
+ </p>
+<a name="math_toolkit.special.sf_gamma.igamma.implementation"></a><h5>
+<a name="id629402"></a>
+ Implementation
+ </h5>
+<p>
+ These four functions share a common implementation since they are all related
+ via:
+ </p>
+<p>
+ 1) <span class="inlinemediaobject"><img src="../../../../equations/igamma5.png"></span>
+ </p>
+<p>
+ 2) <span class="inlinemediaobject"><img src="../../../../equations/igamma6.png"></span>
+ </p>
+<p>
+ 3) <span class="inlinemediaobject"><img src="../../../../equations/igamma7.png"></span>
+ </p>
+<p>
+ The lower incomplete gamma is computed from its series representation:
+ </p>
+<p>
+ 4) <span class="inlinemediaobject"><img src="../../../../equations/igamma8.png"></span>
+ </p>
+<p>
+ Or by subtraction of the upper integral from either &#915;(a) or 1 when <span class="emphasis"><em>x
+ &gt; a and x &gt; 1.1</em></span>.
+ </p>
+<p>
+ The upper integral is computed from Legendre's continued fraction representation:
+ </p>
+<p>
+ 5) <span class="inlinemediaobject"><img src="../../../../equations/igamma9.png"></span>
+ </p>
+<p>
+ When <span class="emphasis"><em>x &gt; 1.1</em></span> or by subtraction of the lower integral
+ from either &#915;(a) or 1 when <span class="emphasis"><em>x &lt; a</em></span>.
+ </p>
+<p>
+ For <span class="emphasis"><em>x &lt; 1.1</em></span> computation of the upper integral is
+ more complex as the continued fraction representation is unstable in this
+ area. However there is another series representation for the lower integral:
+ </p>
+<p>
+ 6) <span class="inlinemediaobject"><img src="../../../../equations/igamma10.png"></span>
+ </p>
+<p>
+ That lends itself to calculation of the upper integral via rearrangement
+ to:
+ </p>
+<p>
+ 7) <span class="inlinemediaobject"><img src="../../../../equations/igamma11.png"></span>
+ </p>
+<p>
+ Refer to the documentation for powm1
+ and tgamma1pm1
+ for details of their implementation. Note however that the precision of
+ tgamma1pm1
+ is capped to either around 35 digits, or to that of the <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a> associated with type T - if there is one - whichever
+ of the two is the greater. That therefore imposes a similar limit on the
+ precision of this function in this region.
+ </p>
+<p>
+ For <span class="emphasis"><em>x &lt; 1.1</em></span> the crossover point where the result
+ is ~0.5 no longer occurs for <span class="emphasis"><em>x ~ y</em></span>. Using <span class="emphasis"><em>x
+ * 1.1 &lt; a</em></span> as the crossover criterion for <span class="emphasis"><em>0.5 &lt;
+ x &lt;= 1.1</em></span> keeps the maximum value computed (whether it's the
+ upper or lower interval) to around 0.6. Likewise for <span class="emphasis"><em>x &lt;=
+ 0.5</em></span> then using <span class="emphasis"><em>-0.4 / log(x) &lt; a</em></span> as
+ the crossover criterion keeps the maximum value computed to around 0.7
+ (whether it's the upper or lower interval).
+ </p>
+<p>
+ There are two special cases used when a is an integer or half integer,
+ and the crossover conditions listed above indicate that we should compute
+ the upper integral Q. If a is an integer in the range <span class="emphasis"><em>1 &lt;=
+ a &lt; 30</em></span> then the following finite sum is used:
+ </p>
+<p>
+ 9) <span class="inlinemediaobject"><img src="../../../../equations/igamma1f.png"></span>
+ </p>
+<p>
+ While for half integers in the range <span class="emphasis"><em>0.5 &lt;= a &lt; 30</em></span>
+ then the following finite sum is used:
+ </p>
+<p>
+ 10) <span class="inlinemediaobject"><img src="../../../../equations/igamma2f.png"></span>
+ </p>
+<p>
+ These are both more stable and more efficient than the continued fraction
+ alternative.
+ </p>
+<p>
+ When the argument <span class="emphasis"><em>a</em></span> is large, and <span class="emphasis"><em>x ~ a</em></span>
+ then the series (4) and continued fraction (5) above are very slow to converge.
+ In this area an expansion due to Temme is used:
+ </p>
+<p>
+ 11) <span class="inlinemediaobject"><img src="../../../../equations/igamma16.png"></span>
+ </p>
+<p>
+ 12) <span class="inlinemediaobject"><img src="../../../../equations/igamma17.png"></span>
+ </p>
+<p>
+ 13) <span class="inlinemediaobject"><img src="../../../../equations/igamma18.png"></span>
+ </p>
+<p>
+ 14) <span class="inlinemediaobject"><img src="../../../../equations/igamma19.png"></span>
+ </p>
+<p>
+ The double sum is truncated to a fixed number of terms - to give a specific
+ target precision - and evaluated as a polynomial-of-polynomials. There
+ are versions for up to 128-bit long double precision: types requiring greater
+ precision than that do not use these expansions. The coefficients C<sub>k</sub><sup>n</sup> are
+ computed in advance using the recurrence relations given by Temme. The
+ zone where these expansions are used is
+ </p>
+<pre class="programlisting">
+<span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;</span> <span class="number">20</span><span class="special">)</span> <span class="special">&amp;&amp;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="number">200</span><span class="special">)</span> <span class="special">&amp;&amp;</span> <span class="identifier">fabs</span><span class="special">(</span><span class="identifier">x</span><span class="special">-</span><span class="identifier">a</span><span class="special">)/</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="number">0.4</span>
+</pre>
+<p>
+ And:
+ </p>
+<pre class="programlisting">
+<span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;</span> <span class="number">200</span><span class="special">)</span> <span class="special">&amp;&amp;</span> <span class="special">(</span><span class="identifier">fabs</span><span class="special">(</span><span class="identifier">x</span><span class="special">-</span><span class="identifier">a</span><span class="special">)/</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="number">4.5</span><span class="special">/</span><span class="identifier">sqrt</span><span class="special">(</span><span class="identifier">a</span><span class="special">))</span>
+</pre>
+<p>
+ The latter range is valid for all types up to 128-bit long doubles, and
+ is designed to ensure that the result is larger than 10<sup>-6</sup>, the first range
+ is used only for types up to 80-bit long doubles. These domains are narrower
+ than the ones recommended by either Temme or Didonato and Morris. However,
+ using a wider range results in large and inexact (i.e. computed) values
+ being passed to the <code class="computeroutput"><span class="identifier">exp</span></code>
+ and <code class="computeroutput"><span class="identifier">erfc</span></code> functions resulting
+ in significantly larger error rates. In other words there is a fine trade
+ off here between efficiency and error. The current limits should keep the
+ number of terms required by (4) and (5) to no more than ~20 at double precision.
+ </p>
+<p>
+ For the normalised incomplete gamma functions, calculation of the leading
+ power terms is central to the accuracy of the function. For smallish a
+ and x combining the power terms with the <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a> gives the greatest accuracy:
+ </p>
+<p>
+ 15) <span class="inlinemediaobject"><img src="../../../../equations/igamma12.png"></span>
+ </p>
+<p>
+ In the event that this causes underflow<span class="emphasis"><em>overflow then the exponent
+ can be reduced by a factor of /a</em></span> and brought inside the power
+ term.
+ </p>
+<p>
+ When a and x are large, we end up with a very large exponent with a base
+ near one: this will not be computed accurately via the pow function, and
+ taking logs simply leads to cancellation errors. The worst of the errors
+ can be avoided by using:
+ </p>
+<p>
+ 16) <span class="inlinemediaobject"><img src="../../../../equations/igamma13.png"></span>
+ </p>
+<p>
+ when <span class="emphasis"><em>a-x</em></span> is small and a and x are large. There is
+ still a subtraction and therefore some cancellation errors - but the terms
+ are small so the absolute error will be small - and it is absolute rather
+ than relative error that counts in the argument to the <span class="emphasis"><em>exp</em></span>
+ function. Note that for sufficiently large a and x the errors will still
+ get you eventually, although this does delay the inevitable much longer
+ than other methods. Use of <span class="emphasis"><em>log(1+x)-x</em></span> here is inspired
+ by Temme (see references below).
+ </p>
+<a name="math_toolkit.special.sf_gamma.igamma.references"></a><h5>
+<a name="id630444"></a>
+ References
+ </h5>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ N. M. Temme, A Set of Algorithms for the Incomplete Gamma Functions,
+ Probability in the Engineering and Informational Sciences, 8, 1994.
+ </li>
+<li>
+ N. M. Temme, The Asymptotic Expansion of the Incomplete Gamma Functions,
+ Siam J. Math Anal. Vol 10 No 4, July 1979, p757.
+ </li>
+<li>
+ A. R. Didonato and A. H. Morris, Computation of the Incomplete Gamma
+ Function Ratios and their Inverse. ACM TOMS, Vol 12, No 4, Dec 1986,
+ p377.
+ </li>
+<li>
+ W. Gautschi, The Incomplete Gamma Functions Since Tricomi, In Tricomi's
+ Ideas and Contemporary Applied Mathematics, Atti dei Convegni Lincei,
+ n. 147, Accademia Nazionale dei Lincei, Roma, 1998, pp. 203--237. http://citeseer.ist.psu.edu/gautschi98incomplete.html
+</li>
+</ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="gamma_ratios.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="igamma_inv.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/igamma_inv.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/igamma_inv.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,266 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Incomplete Gamma Function Inverses</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_gamma.html" title="Gamma Functions">
+<link rel="prev" href="igamma.html" title="Incomplete Gamma Functions">
+<link rel="next" href="gamma_derivatives.html" title="Derivative of the Incomplete Gamma Function">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="igamma.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="gamma_derivatives.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_gamma.igamma_inv"></a><a href="igamma_inv.html" title="Incomplete Gamma Function Inverses"> Incomplete
+ Gamma Function Inverses</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.sf_gamma.igamma_inv.synopsis"></a><h5>
+<a name="id630526"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_q_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">q</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_q_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">q</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_p_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">p</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_p_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_q_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">q</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_q_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">q</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_p_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">p</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_p_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.sf_gamma.igamma_inv.description"></a><h5>
+<a name="id631636"></a>
+ Description
+ </h5>
+<p>
+ There are four <a href="http://mathworld.wolfram.com/IncompleteGammaFunction.html" target="_top">incomplete
+ gamma function</a> inverses which either compute <span class="emphasis"><em>x</em></span>
+ given <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>p</em></span> or <span class="emphasis"><em>q</em></span>,
+ or else compute <span class="emphasis"><em>a</em></span> given <span class="emphasis"><em>x</em></span> and
+ either <span class="emphasis"><em>p</em></span> or <span class="emphasis"><em>q</em></span>.
+ </p>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when T1 and T2 are different types,
+ otherwise the return type is simply T1.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<div class="tip"><table border="0" summary="Tip">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../../doc/html/images/tip.png"></td>
+<th align="left">Tip</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ When people normally talk about the inverse of the incomplete gamma function,
+ they are talking about inverting on parameter <span class="emphasis"><em>x</em></span>.
+ These are implemented here as gamma_p_inv and gamma_q_inv, and are by
+ far the most efficient of the inverses presented here.
+ </p>
+<p>
+ The inverse on the <span class="emphasis"><em>a</em></span> parameter finds use in some
+ statistical applications but has to be computed by rather brute force
+ numerical techniques and is consequently several times slower. These
+ are implemented here as gamma_p_inva and gamma_q_inva.
+ </p>
+</td></tr>
+</table></div>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_q_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">q</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_q_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">q</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns a value x such that: <code class="computeroutput"><span class="identifier">q</span>
+ <span class="special">=</span> <span class="identifier">gamma_q</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
+ <span class="identifier">x</span><span class="special">);</span></code>
+ </p>
+<p>
+ Requires: <span class="emphasis"><em>a &gt; 0</em></span> and <span class="emphasis"><em>1 &gt;= p,q &gt;=
+ 0</em></span>.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_p_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">p</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_p_inv</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns a value x such that: <code class="computeroutput"><span class="identifier">p</span>
+ <span class="special">=</span> <span class="identifier">gamma_p</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
+ <span class="identifier">x</span><span class="special">);</span></code>
+ </p>
+<p>
+ Requires: <span class="emphasis"><em>a &gt; 0</em></span> and <span class="emphasis"><em>1 &gt;= p,q &gt;=
+ 0</em></span>.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_q_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">q</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_q_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">q</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns a value a such that: <code class="computeroutput"><span class="identifier">q</span>
+ <span class="special">=</span> <span class="identifier">gamma_q</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
+ <span class="identifier">x</span><span class="special">);</span></code>
+ </p>
+<p>
+ Requires: <span class="emphasis"><em>x &gt; 0</em></span> and <span class="emphasis"><em>1 &gt;= p,q &gt;=
+ 0</em></span>.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_p_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">p</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">gamma_p_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns a value a such that: <code class="computeroutput"><span class="identifier">p</span>
+ <span class="special">=</span> <span class="identifier">gamma_p</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
+ <span class="identifier">x</span><span class="special">);</span></code>
+ </p>
+<p>
+ Requires: <span class="emphasis"><em>x &gt; 0</em></span> and <span class="emphasis"><em>1 &gt;= p,q &gt;=
+ 0</em></span>.
+ </p>
+<a name="math_toolkit.special.sf_gamma.igamma_inv.accuracy"></a><h5>
+<a name="id633033"></a>
+ Accuracy
+ </h5>
+<p>
+ The accuracy of these functions doesn't vary much by platform or by the
+ type T. Given that these functions are computed by iterative methods, they
+ are deliberately "detuned" so as not to be too accurate: it is
+ in any case impossible for these function to be more accurate than the
+ regular forward incomplete gamma functions. In practice, the accuracy of
+ these functions is very similar to that of gamma_p
+ and gamma_q
+ functions.
+ </p>
+<a name="math_toolkit.special.sf_gamma.igamma_inv.testing"></a><h5>
+<a name="id633087"></a>
+ Testing
+ </h5>
+<p>
+ There are two sets of tests:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Basic sanity checks attempt to "round-trip" from <span class="emphasis"><em>a</em></span>
+ and <span class="emphasis"><em>x</em></span> to <span class="emphasis"><em>p</em></span> or <span class="emphasis"><em>q</em></span>
+ and back again. These tests have quite generous tolerances: in general
+ both the incomplete gamma, and its inverses, change so rapidly that round
+ tripping to more than a couple of significant digits isn't possible.
+ This is especially true when <span class="emphasis"><em>p</em></span> or <span class="emphasis"><em>q</em></span>
+ is very near one: in this case there isn't enough "information content"
+ in the input to the inverse function to get back where you started.
+ </li>
+<li>
+ Accuracy checks using high precision test values. These measure the accuracy
+ of the result, given exact input values.
+ </li>
+</ul></div>
+<a name="math_toolkit.special.sf_gamma.igamma_inv.implementation"></a><h5>
+<a name="id633162"></a>
+ Implementation
+ </h5>
+<p>
+ The functions gamma_p_inv and gamma_q_inv
+ share a common implementation.
+ </p>
+<p>
+ First an initial approximation is computed using the methodology described
+ in:
+ </p>
+<p>
+ <a href="http://portal.acm.org/citation.cfm?id=23109&amp;coll=portal&amp;dl=ACM" target="_top">A.
+ R. Didonato and A. H. Morris, Computation of the Incomplete Gamma Function
+ Ratios and their Inverse, ACM Trans. Math. Software 12 (1986), 377-393.</a>
+ </p>
+<p>
+ Finally, the last few bits are cleaned up using Halley iteration, the iteration
+ limit is set to 2/3 of the number of bits in T, which by experiment is
+ sufficient to ensure that the inverses are at least as accurate as the
+ normal incomplete gamma functions. In testing, no more than 3 iterations
+ are required to produce a result as accurate as the forward incomplete
+ gamma function, and in many cases only one iteration is required.
+ </p>
+<p>
+ The functions gamma_p_inva and gamma_q_inva also share a common implementation
+ but are handled separately from gamma_p_inv and gamma_q_inv.
+ </p>
+<p>
+ An initial approximation for <span class="emphasis"><em>a</em></span> is computed very crudely
+ so that <span class="emphasis"><em>gamma_p(a, x) ~ 0.5</em></span>, this value is then used
+ as a starting point for a generic derivative-free root finding algorithm.
+ As a consequence, these two functions are rather more expensive to compute
+ than the gamma_p_inv or gamma_q_inv functions. Even so, the root is usually
+ found in fewer than 10 iterations.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="igamma.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="gamma_derivatives.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/lgamma.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/lgamma.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,490 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Log Gamma</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_gamma.html" title="Gamma Functions">
+<link rel="prev" href="tgamma.html" title="Gamma">
+<link rel="next" href="digamma.html" title="Digamma">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tgamma.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="digamma.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_gamma.lgamma"></a> Log Gamma
+</h4></div></div></div>
+<a name="math_toolkit.special.sf_gamma.lgamma.synopsis"></a><h5>
+<a name="id620019"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">int</span><span class="special">*</span> <span class="identifier">sign</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">int</span><span class="special">*</span> <span class="identifier">sign</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.sf_gamma.lgamma.description"></a><h5>
+<a name="id620556"></a>
+ Description
+ </h5>
+<p>
+ The lgamma function
+ is defined by:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/lgamm1.png"></span>
+ </p>
+<p>
+ The second form of the function takes a pointer to an integer, which if
+ non-null is set on output to the sign of tgamma(z).
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/lgamma.png" alt="lgamma"></span>
+ </p>
+<p>
+ There are effectively two versions of this function internally: a fully
+ generic version that is slow, but reasonably accurate, and a much more
+ efficient approximation that is used where the number of digits in the
+ significand of T correspond to a certain <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a>. In practice, any built-in floating-point type you
+ will encounter has an appropriate <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a> defined for it. It is also possible, given enough
+ machine time, to generate further <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a>'s using the program libs/math/tools/lanczos_generator.cpp.
+ </p>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: the result is of type <code class="computeroutput"><span class="keyword">double</span></code> if T is an integer type, or type
+ T otherwise.
+ </p>
+<a name="math_toolkit.special.sf_gamma.lgamma.accuracy"></a><h5>
+<a name="id620744"></a>
+ Accuracy
+ </h5>
+<p>
+ The following table shows the peak errors (in units of epsilon) found on
+ various platforms with various floating point types, along with comparisons
+ to the GSL-1.9,
+ GNU C Lib, HP-UX C Library
+ and Cephes libraries.
+ Unless otherwise specified any floating point type that is narrower than
+ the one shown will have effectively zero error.
+ </p>
+<p>
+ Note that while the relative errors near the positive roots of lgamma are
+ very low, the lgamma function has an infinite number of irrational roots
+ for negative arguments: very close to these negative roots only a low absolute
+ error can be guaranteed.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ Factorials and Half factorials
+ </p>
+ </th>
+<th>
+ <p>
+ Values Near Zero
+ </p>
+ </th>
+<th>
+ <p>
+ Values Near 1 or 2
+ </p>
+ </th>
+<th>
+ <p>
+ Values Near a Negative Pole
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32 Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.88 Mean=0.14
+ </p>
+ <p>
+ (GSL=33) (Cephes=1.5)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.96 Mean=0.46
+ </p>
+ <p>
+ (GSL=5.2) (Cephes=1.1)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.86 Mean=0.46
+ </p>
+ <p>
+ (GSL=1168) (Cephes~500000)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4.2 Mean=1.3
+ </p>
+ <p>
+ (GSL=25) (Cephes=1.6)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Linux IA32 / GCC
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.9 Mean=0.43
+ </p>
+ <p>
+ (GNU C Lib
+ Peak=1.7 Mean=0.49)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.4 Mean=0.57
+ </p>
+ <p>
+ (GNU C Lib
+ Peak= 0.96 Mean=0.54)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.86 Mean=0.35
+ </p>
+ <p>
+ (GNU C Lib
+ Peak=0.74 Mean=0.26)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=6.0 Mean=1.8
+ </p>
+ <p>
+ (GNU C Lib
+ Peak=3.0 Mean=0.86)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Linux IA64 / GCC
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.99 Mean=0.12
+ </p>
+ <p>
+ (GNU C Lib
+ Peak 0)
+ </p>
+ </td>
+<td>
+ <p>
+ Pek=1.2 Mean=0.6
+ </p>
+ <p>
+ (GNU C Lib
+ Peak 0)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.86 Mean=0.16
+ </p>
+ <p>
+ (GNU C Lib
+ Peak 0)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2.3 Mean=0.69
+ </p>
+ <p>
+ (GNU C Lib
+ Peak 0)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.96 Mean=0.13
+ </p>
+ <p>
+ (<a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX
+ C Library</a> Peak 0)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.99 Mean=0.53
+ </p>
+ <p>
+ (<a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX
+ C Library</a> Peak 0)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=0.9 Mean=0.4
+ </p>
+ <p>
+ (<a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX
+ C Library</a> Peak 0)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=3.0 Mean=0.9
+ </p>
+ <p>
+ (<a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX
+ C Library</a> Peak 0)
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.special.sf_gamma.lgamma.testing"></a><h5>
+<a name="id621267"></a>
+ Testing
+ </h5>
+<p>
+ The main tests for this function involve comparisons against the logs of
+ the factorials which can be independently calculated to very high accuracy.
+ </p>
+<p>
+ Random tests in key problem areas are also used.
+ </p>
+<a name="math_toolkit.special.sf_gamma.lgamma.implementation"></a><h5>
+<a name="id621303"></a>
+ Implementation
+ </h5>
+<p>
+ The generic version of this function is implemented by combining the series
+ and continued fraction representations for the incomplete gamma function:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/lgamm2.png"></span>
+ </p>
+<p>
+ where <span class="emphasis"><em>l</em></span> is an arbitrary integration limit: choosing
+ <code class="literal">l = max(10, a)</code> seems to work fairly well. For negative
+ <span class="emphasis"><em>z</em></span> the logarithm version of the reflection formula
+ is used:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/lgamm3.png"></span>
+ </p>
+<p>
+ For types of known precision, the <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a> is used, a traits class <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">lanczos</span><span class="special">::</span><span class="identifier">lanczos_traits</span></code>
+ maps type T to an appropriate approximation. The logarithmic version of
+ the Lanczos approximation
+ is:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/lgamm4.png"></span>
+ </p>
+<p>
+ Where L<sub>e,g</sub> is the Lanczos sum, scaled by e<sup>g</sup>.
+ </p>
+<p>
+ As before the reflection formula is used for <span class="emphasis"><em>z &lt; 0</em></span>.
+ </p>
+<p>
+ When z is very near 1 or 2, then the logarithmic version of the <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a> suffers very badly from cancellation error: indeed
+ for values sufficiently close to 1 or 2, arbitrarily large relative errors
+ can be obtained (even though the absolute error is tiny).
+ </p>
+<p>
+ For types with up to 113 bits of precision (up to and including 128-bit
+ long doubles), root-preserving rational approximations <a href="../../backgrounders/implementation.html#math_toolkit.backgrounders.implementation.rational_approximations_used">devised
+ by JM</a> are used over the intervals [1,2] and [2,3]. Over the interval
+ [2,3] the approximation form used is:
+ </p>
+<pre class="programlisting">
+<span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">z</span><span class="special">-</span><span class="number">2</span><span class="special">)(</span><span class="identifier">z</span><span class="special">+</span><span class="number">1</span><span class="special">)(</span><span class="identifier">Y</span> <span class="special">+</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">z</span><span class="special">-</span><span class="number">2</span><span class="special">));</span>
+</pre>
+<p>
+ Where Y is a constant, and R(z-2) is the rational approximation: optimised
+ so that it's absolute error is tiny compared to Y. In addition small values
+ of z greater than 3 can handled by argument reduction using the recurrence
+ relation:
+ </p>
+<pre class="programlisting">
+<span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">+</span><span class="number">1</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">log</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">);</span>
+</pre>
+<p>
+ Over the interval [1,2] two approximations have to be used, one for small
+ z uses:
+ </p>
+<pre class="programlisting">
+<span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">z</span><span class="special">-</span><span class="number">1</span><span class="special">)(</span><span class="identifier">z</span><span class="special">-</span><span class="number">2</span><span class="special">)(</span><span class="identifier">Y</span> <span class="special">+</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">z</span><span class="special">-</span><span class="number">1</span><span class="special">));</span>
+</pre>
+<p>
+ Once again Y is a constant, and R(z-1) is optimised for low absolute error
+ compared to Y. For z &gt; 1.5 the above form wouldn't converge to a minimax
+ solution but this similar form does:
+ </p>
+<pre class="programlisting">
+<span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span> <span class="special">=</span> <span class="special">(</span><span class="number">2</span><span class="special">-</span><span class="identifier">z</span><span class="special">)(</span><span class="number">1</span><span class="special">-</span><span class="identifier">z</span><span class="special">)(</span><span class="identifier">Y</span> <span class="special">+</span> <span class="identifier">R</span><span class="special">(</span><span class="number">2</span><span class="special">-</span><span class="identifier">z</span><span class="special">));</span>
+</pre>
+<p>
+ Finally for z &lt; 1 the recurrence relation can be used to move to z &gt;
+ 1:
+ </p>
+<pre class="programlisting">
+<span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">+</span><span class="number">1</span><span class="special">)</span> <span class="special">-</span> <span class="identifier">log</span><span class="special">(</span><span class="identifier">z</span><span class="special">);</span>
+</pre>
+<p>
+ Note that while this involves a subtraction, it appears not to suffer from
+ cancellation error: as z decreases from 1 the <code class="computeroutput"><span class="special">-</span><span class="identifier">log</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span></code> term
+ grows positive much more rapidly than the <code class="computeroutput"><span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">+</span><span class="number">1</span><span class="special">)</span></code> term becomes
+ negative. So in this specific case, significant digits are preserved, rather
+ than cancelled.
+ </p>
+<p>
+ For other types which do have a <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a> defined for them the current solution is as follows:
+ imagine we balance the two terms in the <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a> by dividing the power term by its value at <span class="emphasis"><em>z
+ = 1</em></span>, and then multiplying the Lanczos coefficients by the same
+ value. Now each term will take the value 1 at <span class="emphasis"><em>z = 1</em></span>
+ and we can rearrange the power terms in terms of log1p. Likewise if we
+ subtract 1 from the Lanczos sum part (algebraically, by subtracting the
+ value of each term at <span class="emphasis"><em>z = 1</em></span>), we obtain a new summation
+ that can be also be fed into log1p. Crucially, all of the terms tend to
+ zero, as <span class="emphasis"><em>z -&gt; 1</em></span>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/lgamm5.png"></span>
+ </p>
+<p>
+ The C<sub>k</sub> terms in the above are the same as in the <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a>.
+ </p>
+<p>
+ A similar rearrangement can be performed at <span class="emphasis"><em>z = 2</em></span>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/lgamm6.png"></span>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tgamma.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="digamma.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/tgamma.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_gamma/tgamma.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,479 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Gamma</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_gamma.html" title="Gamma Functions">
+<link rel="prev" href="../sf_gamma.html" title="Gamma Functions">
+<link rel="next" href="lgamma.html" title="Log Gamma">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../sf_gamma.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="lgamma.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_gamma.tgamma"></a> Gamma
+</h4></div></div></div>
+<a name="math_toolkit.special.sf_gamma.tgamma.synopsis"></a><h5>
+<a name="id617610"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma1pm1</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">dz</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma1pm1</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">dz</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.sf_gamma.tgamma.description"></a><h5>
+<a name="id618103"></a>
+ Description
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the "true gamma" (hence name tgamma) of value z:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/gamm1.png"></span>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/gamma.png" alt="gamma"></span>
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ There are effectively two versions of the tgamma
+ function internally: a fully generic version that is slow, but reasonably
+ accurate, and a much more efficient approximation that is used where the
+ number of digits in the significand of T correspond to a certain Lanczos approximation.
+ In practice any built in floating point type you will encounter has an
+ appropriate <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a> defined for it. It is also possible, given enough
+ machine time, to generate further <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a>'s using the program libs/math/tools/lanczos_generator.cpp.
+ </p>
+<p>
+ The return type of this function is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: the result is <code class="computeroutput"><span class="keyword">double</span></code>
+ when T is an integer type, and T otherwise.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma1pm1</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">dz</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">tgamma1pm1</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">dz</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns <code class="computeroutput"><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">dz</span> <span class="special">+</span> <span class="number">1</span><span class="special">)</span> <span class="special">-</span>
+ <span class="number">1</span></code>. Internally the implementation
+ does not make use of the addition and subtraction implied by the definition,
+ leading to accurate results even for very small <code class="computeroutput"><span class="identifier">dz</span></code>.
+ However, the implementation is capped to either 35 digit accuracy, or to
+ the precision of the <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a> associated with type T, whichever is more accurate.
+ </p>
+<p>
+ The return type of this function is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: the result is <code class="computeroutput"><span class="keyword">double</span></code>
+ when T is an integer type, and T otherwise.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<a name="math_toolkit.special.sf_gamma.tgamma.accuracy"></a><h5>
+<a name="id618776"></a>
+ Accuracy
+ </h5>
+<p>
+ The following table shows the peak errors (in units of epsilon) found on
+ various platforms with various floating point types, along with comparisons
+ to the GSL-1.9,
+ GNU C Lib, HP-UX C Library
+ and Cephes libraries.
+ Unless otherwise specified any floating point type that is narrower than
+ the one shown will have effectively zero error.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ Factorials and Half factorials
+ </p>
+ </th>
+<th>
+ <p>
+ Values Near Zero
+ </p>
+ </th>
+<th>
+ <p>
+ Values Near 1 or 2
+ </p>
+ </th>
+<th>
+ <p>
+ Values Near a Negative Pole
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32 Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1.9 Mean=0.7
+ </p>
+ <p>
+ (GSL=3.9)
+ </p>
+ <p>
+ (Cephes=3.0)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2.0 Mean=1.1
+ </p>
+ <p>
+ (GSL=4.5)
+ </p>
+ <p>
+ (Cephes=1)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2.0 Mean=1.1
+ </p>
+ <p>
+ (GSL=7.9)
+ </p>
+ <p>
+ (Cephes=1.0)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2.6 Mean=1.3
+ </p>
+ <p>
+ (GSL=2.5)
+ </p>
+ <p>
+ (Cephes=2.7)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Linux IA32 / GCC
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=300 Mean=49.5
+ </p>
+ <p>
+ (GNU C Lib
+ Peak=395 Mean=89)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=3.0 Mean=1.4
+ </p>
+ <p>
+ (GNU C Lib
+ Peak=11 Mean=3.3)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=5.0 Mean=1.8
+ </p>
+ <p>
+ (GNU C Lib
+ Peak=0.92 Mean=0.2)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=157 Mean=65
+ </p>
+ <p>
+ (GNU C Lib
+ Peak=205 Mean=108)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Linux IA64 / GCC
+ </p>
+ </td>
+<td>
+ <p>
+ GNU C Lib
+ Peak 2.8 Mean=0.9
+ </p>
+ <p>
+ (GNU C Lib
+ Peak 0.7)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4.8 Mean=1.5
+ </p>
+ <p>
+ (GNU C Lib
+ Peak 0)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4.8 Mean=1.5
+ </p>
+ <p>
+ (GNU C Lib
+ Peak 0)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=5.0 Mean=1.7 (<a href="http://www.gnu.org/software/libc/" target="_top">GNU
+ C Lib</a> Peak 0)
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2.5 Mean=1.1
+ </p>
+ <p>
+ (<a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX
+ C Library</a> Peak 0)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=3.5 Mean=1.7
+ </p>
+ <p>
+ (<a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX
+ C Library</a> Peak 0)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=3.5 Mean=1.6
+ </p>
+ <p>
+ (<a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX
+ C Library</a> Peak 0)
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=5.2 Mean=1.92
+ </p>
+ <p>
+ (<a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX
+ C Library</a> Peak 0)
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.special.sf_gamma.tgamma.testing"></a><h5>
+<a name="id619314"></a>
+ Testing
+ </h5>
+<p>
+ The gamma is relatively easy to test: factorials and half-integer factorials
+ can be calculated exactly by other means and compared with the gamma function.
+ In addition, some accuracy tests in known tricky areas were computed at
+ high precision using the generic version of this function.
+ </p>
+<p>
+ The function <code class="computeroutput"><span class="identifier">tgamma1pm1</span></code>
+ is tested against values calculated very naively using the formula <code class="computeroutput"><span class="identifier">tgamma</span><span class="special">(</span><span class="number">1</span><span class="special">+</span><span class="identifier">dz</span><span class="special">)-</span><span class="number">1</span></code> with
+ a lanczos approximation accurate to around 100 decimal digits.
+ </p>
+<a name="math_toolkit.special.sf_gamma.tgamma.implementation"></a><h5>
+<a name="id619406"></a>
+ Implementation
+ </h5>
+<p>
+ The generic version of the <code class="computeroutput"><span class="identifier">tgamma</span></code>
+ function is implemented by combining the series and continued fraction
+ representations for the incomplete gamma function:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/gamm2.png"></span>
+ </p>
+<p>
+ where <span class="emphasis"><em>l</em></span> is an arbitrary integration limit: choosing
+ <code class="literal">l = max(10, a)</code> seems to work fairly well.
+ </p>
+<p>
+ For types of known precision the <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a> is used, a traits class <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">lanczos</span><span class="special">::</span><span class="identifier">lanczos_traits</span></code>
+ maps type T to an appropriate approximation.
+ </p>
+<p>
+ For z in the range -20 &lt; z &lt; 1 then recursion is used to shift to
+ z &gt; 1 via:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/gamm3.png"></span>
+ </p>
+<p>
+ For very small z, this helps to preserve the identity:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/gamm4.png"></span>
+ </p>
+<p>
+ For z &lt; -20 the reflection formula:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/gamm5.png"></span>
+ </p>
+<p>
+ is used. Particular care has to be taken to evaluate the <code class="computeroutput"><span class="identifier">z</span> <span class="special">*</span> <span class="identifier">sin</span><span class="special">([</span><span class="identifier">pi</span><span class="special">][</span><span class="identifier">space</span><span class="special">]</span> <span class="special">*</span> <span class="identifier">z</span><span class="special">)</span></code>
+ part: a special routine is used to reduce z prior to multiplying by &#960; to
+ ensure that the result in is the range [0, &#960;/2]. Without this an excessive
+ amount of error occurs in this region (which is hard enough already, as
+ the rate of change near a negative pole is <span class="emphasis"><em>exceptionally</em></span>
+ high).
+ </p>
+<p>
+ Finally if the argument is a small integer then table lookup of the factorial
+ is used.
+ </p>
+<p>
+ The function <code class="computeroutput"><span class="identifier">tgamma1pm1</span></code>
+ is implemented using rational approximations <a href="../../backgrounders/implementation.html#math_toolkit.backgrounders.implementation.rational_approximations_used">devised
+ by JM</a> in the region <code class="computeroutput"><span class="special">-</span><span class="number">0.5</span> <span class="special">&lt;</span> <span class="identifier">dz</span> <span class="special">&lt;</span> <span class="number">2</span></code>. These are the same approximations (and
+ internal routines) that are used for lgamma,
+ and so aren't detailed further here. The result of the approximation is
+ <code class="computeroutput"><span class="identifier">log</span><span class="special">(</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">dz</span><span class="special">+</span><span class="number">1</span><span class="special">))</span></code> which can fed into expm1
+ to give the desired result. Outside the range <code class="computeroutput"><span class="special">-</span><span class="number">0.5</span> <span class="special">&lt;</span> <span class="identifier">dz</span> <span class="special">&lt;</span> <span class="number">2</span></code> then the naive formula <code class="computeroutput"><span class="identifier">tgamma1pm1</span><span class="special">(</span><span class="identifier">dz</span><span class="special">)</span>
+ <span class="special">=</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">dz</span><span class="special">+</span><span class="number">1</span><span class="special">)-</span><span class="number">1</span></code>
+ can be used directly.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../sf_gamma.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="lgamma.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_poly.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_poly.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,48 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Polynomials</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../special.html" title="Special Functions">
+<link rel="prev" href="sf_erf/error_inv.html" title="Error Function Inverses">
+<link rel="next" href="sf_poly/legendre.html" title="Legendre (and Associated) Polynomials">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_erf/error_inv.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sf_poly/legendre.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.special.sf_poly"></a> Polynomials
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="sf_poly/legendre.html"> Legendre (and
+ Associated) Polynomials</a></span></dt>
+<dt><span class="section"><a href="sf_poly/laguerre.html"> Laguerre (and
+ Associated) Polynomials</a></span></dt>
+<dt><span class="section"> Hermite Polynomials</span></dt>
+<dt><span class="section"> Spherical Harmonics</span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_erf/error_inv.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sf_poly/legendre.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_poly/hermite.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_poly/hermite.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,290 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Hermite Polynomials</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_poly.html" title="Polynomials">
+<link rel="prev" href="laguerre.html" title="Laguerre (and Associated) Polynomials">
+<link rel="next" href="sph_harm.html" title="Spherical Harmonics">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="laguerre.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_poly.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sph_harm.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_poly.hermite"></a> Hermite Polynomials
+</h4></div></div></div>
+<a name="math_toolkit.special.sf_poly.hermite.synopsis"></a><h5>
+<a name="id663717"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">hermite</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">hermite</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">hermite</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">hermite_next</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">Hn</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">Hnm1</span><span class="special">);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.sf_poly.hermite.description"></a><h5>
+<a name="id664226"></a>
+ Description
+ </h5>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: note than when there is a single
+ template argument the result is the same type as that argument or <code class="computeroutput"><span class="keyword">double</span></code> if the template argument is an integer
+ type.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">hermite</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">hermite</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the value of the Hermite Polynomial of order <span class="emphasis"><em>n</em></span>
+ at point <span class="emphasis"><em>x</em></span>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/hermite_0.png"></span>
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ The following graph illustrates the behaviour of the first few Hermite
+ Polynomials:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/hermite.png" alt="hermite"></span>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">hermite_next</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">Hn</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">Hnm1</span><span class="special">);</span>
+</pre>
+<p>
+ Implements the three term recurrence relation for the Hermite polynomials,
+ this function can be used to create a sequence of values evaluated at the
+ same <span class="emphasis"><em>x</em></span>, and for rising <span class="emphasis"><em>n</em></span>.
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/hermite_1.png"></span>
+ </p>
+<p>
+ For example we could produce a vector of the first 10 polynomial values
+ using:
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">0.5</span><span class="special">;</span> <span class="comment">// Abscissa value
+</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">v</span><span class="special">;</span>
+<span class="identifier">v</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">hermite</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="identifier">x</span><span class="special">)).</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">hermite</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="identifier">x</span><span class="special">));</span>
+<span class="keyword">for</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">l</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> <span class="identifier">l</span> <span class="special">&lt;</span> <span class="number">10</span><span class="special">;</span> <span class="special">++</span><span class="identifier">l</span><span class="special">)</span>
+ <span class="identifier">v</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">hermite_next</span><span class="special">(</span><span class="identifier">l</span><span class="special">,</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">v</span><span class="special">[</span><span class="identifier">l</span><span class="special">],</span> <span class="identifier">v</span><span class="special">[</span><span class="identifier">l</span><span class="special">-</span><span class="number">1</span><span class="special">]));</span>
+</pre>
+<p>
+ Formally the arguments are:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">n</span></dt>
+<dd><p>
+ The degree <span class="emphasis"><em>n</em></span> of the last polynomial calculated.
+ </p></dd>
+<dt><span class="term">x</span></dt>
+<dd><p>
+ The abscissa value
+ </p></dd>
+<dt><span class="term">Hn</span></dt>
+<dd><p>
+ The value of the polynomial evaluated at degree <span class="emphasis"><em>n</em></span>.
+ </p></dd>
+<dt><span class="term">Hnm1</span></dt>
+<dd><p>
+ The value of the polynomial evaluated at degree <span class="emphasis"><em>n-1</em></span>.
+ </p></dd>
+</dl>
+</div>
+<a name="math_toolkit.special.sf_poly.hermite.accuracy"></a><h5>
+<a name="id665228"></a>
+ Accuracy
+ </h5>
+<p>
+ The following table shows peak errors (in units of epsilon) for various
+ domains of input arguments. Note that only results for the widest floating
+ point type on the system are given as narrower types have <a href="../../backgrounders/relative_error.html#zero_error">effectively
+ zero error</a>.
+ </p>
+<div class="table">
+<a name="id665258"></a><p class="title"><b>Table 27. Peak Errors In the Hermite Polynomial</b></p>
+<div class="table-contents"><table class="table" summary="Peak Errors In the Hermite Polynomial">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ Errors in range
+ </p>
+ <p>
+ 0 &lt; l &lt; 20
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4.5 Mean=1.5
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux IA32, g++ 4.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=6 Mean=2
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux IA64, g++ 3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=6 Mean=2
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=6 Mean=4
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><p>
+ Note that the worst errors occur when the degree increases, values greater
+ than ~120 are very unlikely to produce sensible results, especially in
+ the associated polynomial case when the order is also large. Further the
+ relative errors are likely to grow arbitrarily large when the function
+ is very close to a root.
+ </p>
+<a name="math_toolkit.special.sf_poly.hermite.testing"></a><h5>
+<a name="id665441"></a>
+ Testing
+ </h5>
+<p>
+ A mixture of spot tests of values calculated using functions.wolfram.com,
+ and randomly generated test data are used: the test data was computed using
+ NTL::RR at 1000-bit
+ precision.
+ </p>
+<a name="math_toolkit.special.sf_poly.hermite.implementation"></a><h5>
+<a name="id665480"></a>
+ Implementation
+ </h5>
+<p>
+ These functions are implemented using the stable three term recurrence
+ relations. These relations guarentee low absolute error but cannot guarentee
+ low relative error near one of the roots of the polynomials.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="laguerre.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_poly.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sph_harm.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_poly/laguerre.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_poly/laguerre.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,469 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Laguerre (and Associated) Polynomials</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_poly.html" title="Polynomials">
+<link rel="prev" href="legendre.html" title="Legendre (and Associated) Polynomials">
+<link rel="next" href="hermite.html" title="Hermite Polynomials">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="legendre.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_poly.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="hermite.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_poly.laguerre"></a><a href="laguerre.html" title="Laguerre (and Associated) Polynomials"> Laguerre (and
+ Associated) Polynomials</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.sf_poly.laguerre.synopsis"></a><h5>
+<a name="id660301"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">laguerre</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">laguerre</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">laguerre</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">laguerre</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">laguerre</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">laguerre_next</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">Ln</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">Lnm1</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">laguerre_next</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">Ln</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">Lnm1</span><span class="special">);</span>
+
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.sf_poly.laguerre.description"></a><h5>
+<a name="id661220"></a>
+ Description
+ </h5>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: note than when there is a single
+ template argument the result is the same type as that argument or <code class="computeroutput"><span class="keyword">double</span></code> if the template argument is an integer
+ type.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">laguerre</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">laguerre</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the value of the Laguerre Polynomial of order <span class="emphasis"><em>n</em></span>
+ at point <span class="emphasis"><em>x</em></span>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/laguerre_0.png"></span>
+ </p>
+<p>
+ The following graph illustrates the behaviour of the first few Laguerre
+ Polynomials:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/laguerre.png" alt="laguerre"></span>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">laguerre</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">laguerre</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the Associated Laguerre polynomial of degree <span class="emphasis"><em>n</em></span>
+ and order <span class="emphasis"><em>m</em></span> at point <span class="emphasis"><em>x</em></span>:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/laguerre_1.png"></span>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">laguerre_next</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">Ln</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">Lnm1</span><span class="special">);</span>
+</pre>
+<p>
+ Implements the three term recurrence relation for the Laguerre polynomials,
+ this function can be used to create a sequence of values evaluated at the
+ same <span class="emphasis"><em>x</em></span>, and for rising <span class="emphasis"><em>n</em></span>.
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/laguerre_2.png"></span>
+ </p>
+<p>
+ For example we could produce a vector of the first 10 polynomial values
+ using:
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">0.5</span><span class="special">;</span> <span class="comment">// Abscissa value
+</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">v</span><span class="special">;</span>
+<span class="identifier">v</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">laguerre</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="identifier">x</span><span class="special">)).</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">laguerre</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="identifier">x</span><span class="special">));</span>
+<span class="keyword">for</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">l</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> <span class="identifier">l</span> <span class="special">&lt;</span> <span class="number">10</span><span class="special">;</span> <span class="special">++</span><span class="identifier">l</span><span class="special">)</span>
+ <span class="identifier">v</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">laguerre_next</span><span class="special">(</span><span class="identifier">l</span><span class="special">,</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">v</span><span class="special">[</span><span class="identifier">l</span><span class="special">],</span> <span class="identifier">v</span><span class="special">[</span><span class="identifier">l</span><span class="special">-</span><span class="number">1</span><span class="special">]));</span>
+</pre>
+<p>
+ Formally the arguments are:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">n</span></dt>
+<dd><p>
+ The degree <span class="emphasis"><em>n</em></span> of the last polynomial calculated.
+ </p></dd>
+<dt><span class="term">x</span></dt>
+<dd><p>
+ The abscissa value
+ </p></dd>
+<dt><span class="term">Ln</span></dt>
+<dd><p>
+ The value of the polynomial evaluated at degree <span class="emphasis"><em>n</em></span>.
+ </p></dd>
+<dt><span class="term">Lnm1</span></dt>
+<dd><p>
+ The value of the polynomial evaluated at degree <span class="emphasis"><em>n-1</em></span>.
+ </p></dd>
+</dl>
+</div>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">laguerre_next</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">Ln</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">Lnm1</span><span class="special">);</span>
+</pre>
+<p>
+ Implements the three term recurrence relation for the Associated Laguerre
+ polynomials, this function can be used to create a sequence of values evaluated
+ at the same <span class="emphasis"><em>x</em></span>, and for rising degree <span class="emphasis"><em>n</em></span>.
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/laguerre_3.png"></span>
+ </p>
+<p>
+ For example we could produce a vector of the first 10 polynomial values
+ using:
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">0.5</span><span class="special">;</span> <span class="comment">// Abscissa value
+</span><span class="keyword">int</span> <span class="identifier">m</span> <span class="special">=</span> <span class="number">10</span><span class="special">;</span> <span class="comment">// order
+</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">v</span><span class="special">;</span>
+<span class="identifier">v</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">laguerre</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">x</span><span class="special">)).</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">laguerre</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">x</span><span class="special">));</span>
+<span class="keyword">for</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">l</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> <span class="identifier">l</span> <span class="special">&lt;</span> <span class="number">10</span><span class="special">;</span> <span class="special">++</span><span class="identifier">l</span><span class="special">)</span>
+ <span class="identifier">v</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">laguerre_next</span><span class="special">(</span><span class="identifier">l</span><span class="special">,</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">v</span><span class="special">[</span><span class="identifier">l</span><span class="special">],</span> <span class="identifier">v</span><span class="special">[</span><span class="identifier">l</span><span class="special">-</span><span class="number">1</span><span class="special">]));</span>
+</pre>
+<p>
+ Formally the arguments are:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">n</span></dt>
+<dd><p>
+ The degree of the last polynomial calculated.
+ </p></dd>
+<dt><span class="term">m</span></dt>
+<dd><p>
+ The order of the Associated Polynomial.
+ </p></dd>
+<dt><span class="term">x</span></dt>
+<dd><p>
+ The abscissa value.
+ </p></dd>
+<dt><span class="term">Ln</span></dt>
+<dd><p>
+ The value of the polynomial evaluated at degree <span class="emphasis"><em>n</em></span>.
+ </p></dd>
+<dt><span class="term">Lnm1</span></dt>
+<dd><p>
+ The value of the polynomial evaluated at degree <span class="emphasis"><em>n-1</em></span>.
+ </p></dd>
+</dl>
+</div>
+<a name="math_toolkit.special.sf_poly.laguerre.accuracy"></a><h5>
+<a name="id663251"></a>
+ Accuracy
+ </h5>
+<p>
+ The following table shows peak errors (in units of epsilon) for various
+ domains of input arguments. Note that only results for the widest floating
+ point type on the system are given as narrower types have <a href="../../backgrounders/relative_error.html#zero_error">effectively
+ zero error</a>.
+ </p>
+<div class="table">
+<a name="id663282"></a><p class="title"><b>Table 25. Peak Errors In the Laguerre Polynomial</b></p>
+<div class="table-contents"><table class="table" summary="Peak Errors In the Laguerre Polynomial">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ Errors in range
+ </p>
+ <p>
+ 0 &lt; l &lt; 20
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=3000 Mean=185
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ SUSE Linux IA32, g++ 4.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1x10<sup>4</sup> Mean=828
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux IA64, g++ 3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1x10<sup>4</sup> Mean=828
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=680 Mean=40
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id663447"></a><p class="title"><b>Table 26. Peak Errors In the Associated Laguerre
+ Polynomial</b></p>
+<div class="table-contents"><table class="table" summary="Peak Errors In the Associated Laguerre
+ Polynomial">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ Errors in range
+ </p>
+ <p>
+ 0 &lt; l &lt; 20
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=433 Mean=11
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ SUSE Linux IA32, g++ 4.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=61.4 Mean=19.5
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux IA64, g++ 3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=61.4 Mean=19.5
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=540 Mean=13.94
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><p>
+ Note that the worst errors occur when the degree increases, values greater
+ than ~120 are very unlikely to produce sensible results, especially in
+ the associated polynomial case when the order is also large. Further the
+ relative errors are likely to grow arbitrarily large when the function
+ is very close to a root.
+ </p>
+<a name="math_toolkit.special.sf_poly.laguerre.testing"></a><h5>
+<a name="id663624"></a>
+ Testing
+ </h5>
+<p>
+ A mixture of spot tests of values calculated using functions.wolfram.com,
+ and randomly generated test data are used: the test data was computed using
+ NTL::RR at 1000-bit
+ precision.
+ </p>
+<a name="math_toolkit.special.sf_poly.laguerre.implementation"></a><h5>
+<a name="id663663"></a>
+ Implementation
+ </h5>
+<p>
+ These functions are implemented using the stable three term recurrence
+ relations. These relations guarentee low absolute error but cannot guarentee
+ low relative error near one of the roots of the polynomials.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="legendre.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_poly.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="hermite.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_poly/legendre.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_poly/legendre.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,716 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Legendre (and Associated) Polynomials</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_poly.html" title="Polynomials">
+<link rel="prev" href="../sf_poly.html" title="Polynomials">
+<link rel="next" href="laguerre.html" title="Laguerre (and Associated) Polynomials">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../sf_poly.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_poly.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="laguerre.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_poly.legendre"></a><a href="legendre.html" title="Legendre (and Associated) Polynomials"> Legendre (and
+ Associated) Polynomials</a>
+</h4></div></div></div>
+<a name="math_toolkit.special.sf_poly.legendre.synopsis"></a><h5>
+<a name="id655988"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">legendre</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">legendre_p</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">legendre_p</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">legendre_p</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">legendre_p</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">legendre_q</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">legendre_q</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">legendre_next</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">l</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">Pl</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">Plm1</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">legendre_next</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">l</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">Pl</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">Plm1</span><span class="special">);</span>
+
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a>: note than when there is a single
+ template argument the result is the same type as that argument or <code class="computeroutput"><span class="keyword">double</span></code> if the template argument is an integer
+ type.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<a name="math_toolkit.special.sf_poly.legendre.description"></a><h5>
+<a name="id657167"></a>
+ Description
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">legendre_p</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">l</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">legendre_p</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">l</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the Legendre Polynomial of the first kind:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/legendre_0.png"></span>
+ </p>
+<p>
+ Requires -1 &lt;= x &lt;= 1, otherwise returns the result of domain_error.
+ </p>
+<p>
+ Negative orders are handled via the reflection formula:
+ </p>
+<p>
+ P<sub>-l-1</sub>(x) = P<sub>l</sub>(x)
+ </p>
+<p>
+ The following graph illustrates the behaviour of the first few Legendre
+ Polynomials:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/legendre_p1.png" alt="legendre_p1"></span>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">legendre_p</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">l</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">legendre_p</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">l</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the associated Legendre polynomial of the first kind:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/legendre_1.png"></span>
+ </p>
+<p>
+ Requires -1 &lt;= x &lt;= 1, otherwise returns the result of domain_error.
+ </p>
+<p>
+ Negative values of <span class="emphasis"><em>l</em></span> and <span class="emphasis"><em>m</em></span> are
+ handled via the identity relations:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/legendre_3.png"></span>
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ The definition of the associated Legendre polynomial used here includes
+ a leading Condon-Shortley phase term of (-1)<sup>m</sup>. This matches the definition
+ given by Abramowitz and Stegun (8.6.6) and that used by Mathworld
+ and <a href="http://documents.wolfram.com/mathematica/functions/LegendreP" target="_top">Mathematica's
+ LegendreP function</a>. However, uses in the literature do not always
+ include this phase term, and strangely the specification for the associated
+ Legendre function in the C++ TR1 (assoc_legendre) also omits it, in spite
+ of stating that it uses Abramowitz and Stegun as the final arbiter on
+ these matters.
+ </p>
+<p>
+ See:
+ </p>
+<p>
+ <a href="http://mathworld.wolfram.com/LegendrePolynomial.html" target="_top">Weisstein,
+ Eric W. "Legendre Polynomial." From MathWorld--A Wolfram Web
+ Resource</a>.
+ </p>
+<p>
+ Abramowitz, M. and Stegun, I. A. (Eds.). "Legendre Functions"
+ and "Orthogonal Polynomials." Ch. 22 in Chs. 8 and 22 in Handbook
+ of Mathematical Functions with Formulas, Graphs, and Mathematical Tables,
+ 9th printing. New York: Dover, pp. 331-339 and 771-802, 1972.
+ </p>
+</td></tr>
+</table></div>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">legendre_q</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">legendre_q</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the value of the Legendre polynomial that is the second solution
+ to the Legendre differential equation, for example:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/legendre_2.png"></span>
+ </p>
+<p>
+ Requires -1 &lt;= x &lt;= 1, otherwise domain_error
+ is called.
+ </p>
+<p>
+ The following graph illustrates the first few Legendre functions of the
+ second kind:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/legendre_q.png" alt="legendre_q"></span>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">legendre_next</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">l</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">Pl</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">Plm1</span><span class="special">);</span>
+</pre>
+<p>
+ Implements the three term recurrence relation for the Legendre polynomials,
+ this function can be used to create a sequence of values evaluated at the
+ same <span class="emphasis"><em>x</em></span>, and for rising <span class="emphasis"><em>l</em></span>. This
+ recurrence relation holds for Legendre Polynomials of both the first and
+ second kinds.
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/legendre_4.png"></span>
+ </p>
+<p>
+ For example we could produce a vector of the first 10 polynomial values
+ using:
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">0.5</span><span class="special">;</span> <span class="comment">// Abscissa value
+</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">v</span><span class="special">;</span>
+<span class="identifier">v</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">legendre_p</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="identifier">x</span><span class="special">)).</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">legendre_p</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="identifier">x</span><span class="special">));</span>
+<span class="keyword">for</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">l</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> <span class="identifier">l</span> <span class="special">&lt;</span> <span class="number">10</span><span class="special">;</span> <span class="special">++</span><span class="identifier">l</span><span class="special">)</span>
+ <span class="identifier">v</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">legendre_next</span><span class="special">(</span><span class="identifier">l</span><span class="special">,</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">v</span><span class="special">[</span><span class="identifier">l</span><span class="special">],</span> <span class="identifier">v</span><span class="special">[</span><span class="identifier">l</span><span class="special">-</span><span class="number">1</span><span class="special">]));</span>
+</pre>
+<p>
+ Formally the arguments are:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">l</span></dt>
+<dd><p>
+ The degree of the last polynomial calculated.
+ </p></dd>
+<dt><span class="term">x</span></dt>
+<dd><p>
+ The abscissa value
+ </p></dd>
+<dt><span class="term">Pl</span></dt>
+<dd><p>
+ The value of the polynomial evaluated at degree <span class="emphasis"><em>l</em></span>.
+ </p></dd>
+<dt><span class="term">Plm1</span></dt>
+<dd><p>
+ The value of the polynomial evaluated at degree <span class="emphasis"><em>l-1</em></span>.
+ </p></dd>
+</dl>
+</div>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">legendre_next</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">l</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">Pl</span><span class="special">,</span> <span class="identifier">T3</span> <span class="identifier">Plm1</span><span class="special">);</span>
+</pre>
+<p>
+ Implements the three term recurrence relation for the Associated Legendre
+ polynomials, this function can be used to create a sequence of values evaluated
+ at the same <span class="emphasis"><em>x</em></span>, and for rising <span class="emphasis"><em>l</em></span>.
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/legendre_5.png"></span>
+ </p>
+<p>
+ For example we could produce a vector of the first m+10 polynomial values
+ using:
+ </p>
+<pre class="programlisting">
+<span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">0.5</span><span class="special">;</span> <span class="comment">// Abscissa value
+</span><span class="keyword">int</span> <span class="identifier">m</span> <span class="special">=</span> <span class="number">10</span><span class="special">;</span> <span class="comment">// order
+</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">v</span><span class="special">;</span>
+<span class="identifier">v</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">legendre_p</span><span class="special">(</span><span class="identifier">m</span><span class="special">,</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">x</span><span class="special">)).</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">legendre_p</span><span class="special">(</span><span class="number">1</span> <span class="special">+</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">x</span><span class="special">));</span>
+<span class="keyword">for</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">l</span> <span class="special">=</span> <span class="number">1</span> <span class="special">+</span> <span class="identifier">m</span><span class="special">;</span> <span class="identifier">l</span> <span class="special">&lt;</span> <span class="identifier">m</span> <span class="special">+</span> <span class="number">10</span><span class="special">;</span> <span class="special">++</span><span class="identifier">l</span><span class="special">)</span>
+ <span class="identifier">v</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">legendre_next</span><span class="special">(</span><span class="identifier">l</span><span class="special">,</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">v</span><span class="special">[</span><span class="identifier">l</span><span class="special">],</span> <span class="identifier">v</span><span class="special">[</span><span class="identifier">l</span><span class="special">-</span><span class="number">1</span><span class="special">]));</span>
+</pre>
+<p>
+ Formally the arguments are:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">l</span></dt>
+<dd><p>
+ The degree of the last polynomial calculated.
+ </p></dd>
+<dt><span class="term">m</span></dt>
+<dd><p>
+ The order of the Associated Polynomial.
+ </p></dd>
+<dt><span class="term">x</span></dt>
+<dd><p>
+ The abscissa value
+ </p></dd>
+<dt><span class="term">Pl</span></dt>
+<dd><p>
+ The value of the polynomial evaluated at degree <span class="emphasis"><em>l</em></span>.
+ </p></dd>
+<dt><span class="term">Plm1</span></dt>
+<dd><p>
+ The value of the polynomial evaluated at degree <span class="emphasis"><em>l-1</em></span>.
+ </p></dd>
+</dl>
+</div>
+<a name="math_toolkit.special.sf_poly.legendre.accuracy"></a><h5>
+<a name="id659594"></a>
+ Accuracy
+ </h5>
+<p>
+ The following table shows peak errors (in units of epsilon) for various
+ domains of input arguments. Note that only results for the widest floating
+ point type on the system are given as narrower types have <a href="../../backgrounders/relative_error.html#zero_error">effectively
+ zero error</a>.
+ </p>
+<div class="table">
+<a name="id659625"></a><p class="title"><b>Table 22. Peak Errors In the Legendre P Function</b></p>
+<div class="table-contents"><table class="table" summary="Peak Errors In the Legendre P Function">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ Errors in range
+ </p>
+ <p>
+ 0 &lt; l &lt; 20
+ </p>
+ </th>
+<th>
+ <p>
+ Errors in range
+ </p>
+ <p>
+ 20 &lt; l &lt; 120
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=211 Mean=20
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=300 Mean=33
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ SUSE Linux IA32, g++ 4.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=70 Mean=10
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=700 Mean=60
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux IA64, g++ 3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=70 Mean=10
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=700 Mean=60
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=35 Mean=6
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=292 Mean=41
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id659824"></a><p class="title"><b>Table 23. Peak Errors In the Associated Legendre
+ P Function</b></p>
+<div class="table-contents"><table class="table" summary="Peak Errors In the Associated Legendre
+ P Function">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ Errors in range
+ </p>
+ <p>
+ 0 &lt; l &lt; 20
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1200 Mean=7
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ SUSE Linux IA32, g++ 4.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=80 Mean=5
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux IA64, g++ 3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=80 Mean=5
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=42 Mean=4
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="id659981"></a><p class="title"><b>Table 24. Peak Errors In the Legendre Q Function</b></p>
+<div class="table-contents"><table class="table" summary="Peak Errors In the Legendre Q Function">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ Errors in range
+ </p>
+ <p>
+ 0 &lt; l &lt; 20
+ </p>
+ </th>
+<th>
+ <p>
+ Errors in range
+ </p>
+ <p>
+ 20 &lt; l &lt; 120
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=50 Mean=7
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=4600 Mean=370
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ SUSE Linux IA32, g++ 4.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=51 Mean=8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=6000 Mean=480
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux IA64, g++ 3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=51 Mean=8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=6000 Mean=480
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=90 Mean=10
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=1700 Mean=140
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><p>
+ Note that the worst errors occur when the order increases, values greater
+ than ~120 are very unlikely to produce sensible results, especially in
+ the associated polynomial case when the degree is also large. Further the
+ relative errors are likely to grow arbitrarily large when the function
+ is very close to a root.
+ </p>
+<p>
+ No comparisons to other libraries are shown here: there appears to be only
+ one viable implementation method for these functions, the comparisons to
+ other libraries that have been run show identical error rates to those
+ given here.
+ </p>
+<a name="math_toolkit.special.sf_poly.legendre.testing"></a><h5>
+<a name="id660207"></a>
+ Testing
+ </h5>
+<p>
+ A mixture of spot tests of values calculated using functions.wolfram.com,
+ and randomly generated test data are used: the test data was computed using
+ NTL::RR at 1000-bit
+ precision.
+ </p>
+<a name="math_toolkit.special.sf_poly.legendre.implementation"></a><h5>
+<a name="id660246"></a>
+ Implementation
+ </h5>
+<p>
+ These functions are implemented using the stable three term recurrence
+ relations. These relations guarentee low absolute error but cannot guarentee
+ low relative error near one of the roots of the polynomials.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../sf_poly.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_poly.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="laguerre.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_poly/sph_harm.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sf_poly/sph_harm.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,317 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Spherical Harmonics</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sf_poly.html" title="Polynomials">
+<link rel="prev" href="hermite.html" title="Hermite Polynomials">
+<link rel="next" href="../bessel.html" title="Bessel Functions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="hermite.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_poly.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../bessel.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sf_poly.sph_harm"></a> Spherical Harmonics
+</h4></div></div></div>
+<a name="math_toolkit.special.sf_poly.sph_harm.synopsis"></a><h5>
+<a name="id665534"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">spheric_harmonic</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">complex</span><span class="special">&lt;</span>calculated-result-type<span class="special">&gt;</span> <span class="identifier">spherical_harmonic</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">theta</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">complex</span><span class="special">&lt;</span>calculated-result-type<span class="special">&gt;</span> <span class="identifier">spherical_harmonic</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">theta</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">spherical_harmonic_r</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">theta</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">spherical_harmonic_r</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">theta</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">spherical_harmonic_i</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">theta</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">spherical_harmonic_i</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">theta</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="special">}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.special.sf_poly.sph_harm.description"></a><h5>
+<a name="id666662"></a>
+ Description
+ </h5>
+<p>
+ The return type of these functions is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when T1 and T2 are different types.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">complex</span><span class="special">&lt;</span>calculated-result-type<span class="special">&gt;</span> <span class="identifier">spherical_harmonic</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">theta</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">complex</span><span class="special">&lt;</span>calculated-result-type<span class="special">&gt;</span> <span class="identifier">spherical_harmonic</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">theta</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the value of the Spherical Harmonic Y<sub>n</sub><sup>m</sup>(theta, phi):
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/spherical_0.png"></span>
+ </p>
+<p>
+ The spherical harmonics Y<sub>n</sub><sup>m</sup>(theta, phi) are the angular portion of the
+ solution to Laplace's equation in spherical coordinates where azimuthal
+ symmetry is not present.
+ </p>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ Care must be taken in correctly identifying the arguments to this function:
+ &#952; is taken as the polar (colatitudinal) coordinate with &#952; in [0, &#960;], and &#966; as
+ the azimuthal (longitudinal) coordinate with &#966; in [0,2&#960;). This is the convention
+ used in Physics, and matches the definition used by <a href="http://documents.wolfram.com/mathematica/functions/SphericalHarmonicY" target="_top">Mathematica
+ in the function SpericalHarmonicY</a>, but is opposite to the usual
+ mathematical conventions.
+ </p>
+<p>
+ Some other sources include an additional Condon-Shortley phase term of
+ (-1)<sup>m</sup> in the definition of this function: note however that our definition
+ of the associated Legendre polynomial already includes this term.
+ </p>
+<p>
+ This implementation returns zero for m &gt; n
+ </p>
+<p>
+ For &#952; outside [0, &#960;] and &#966; outside [0, 2&#960;] this implementation follows the
+ convention used by Mathematica: the function is periodic with period
+ &#960; in &#952; and 2&#960; in &#966;. Please note that this is not the behaviour one would get
+ from a casual application of the function's definition. Cautious users
+ should keep &#952; and &#966; to the range [0, &#960;] and [0, 2&#960;] respectively.
+ </p>
+<p>
+ See: <a href="http://mathworld.wolfram.com/SphericalHarmonic.html" target="_top">Weisstein,
+ Eric W. "Spherical Harmonic." From MathWorld--A Wolfram Web
+ Resource</a>.
+ </p>
+</td></tr>
+</table></div>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">spherical_harmonic_r</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">theta</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">spherical_harmonic_r</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">theta</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the real part of Y<sub>n</sub><sup>m</sup>(theta, phi):
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/spherical_1.png"></span>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">spherical_harmonic_i</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">theta</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">spherical_harmonic_i</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">m</span><span class="special">,</span> <span class="identifier">T1</span> <span class="identifier">theta</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Returns the imaginary part of Y<sub>n</sub><sup>m</sup>(theta, phi):
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/spherical_2.png"></span>
+ </p>
+<a name="math_toolkit.special.sf_poly.sph_harm.accuracy"></a><h5>
+<a name="id667938"></a>
+ Accuracy
+ </h5>
+<p>
+ The following table shows peak errors for various domains of input arguments.
+ Note that only results for the widest floating point type on the system
+ are given as narrower types have <a href="../../backgrounders/relative_error.html#zero_error">effectively
+ zero error</a>. Peak errors are the same for both the real and imaginary
+ parts, as the error is dominated by calculation of the associated Legendre
+ polynomials: especially near the roots of the associated Legendre function.
+ </p>
+<p>
+ All values are in units of epsilon.
+ </p>
+<div class="table">
+<a name="id667977"></a><p class="title"><b>Table 28. Peak Errors In the Sperical Harmonic Functions</b></p>
+<div class="table-contents"><table class="table" summary="Peak Errors In the Sperical Harmonic Functions">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Significand Size
+ </p>
+ </th>
+<th>
+ <p>
+ Platform and Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ Errors in range
+ </p>
+ <p>
+ 0 &lt; l &lt; 20
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ 53
+ </p>
+ </td>
+<td>
+ <p>
+ Win32, Visual C++ 8
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2x10<sup>4</sup> Mean=700
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ SUSE Linux IA32, g++ 4.1
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2900 Mean=100
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 64
+ </p>
+ </td>
+<td>
+ <p>
+ Red Hat Linux IA64, g++ 3.4.4
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=2900 Mean=100
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ 113
+ </p>
+ </td>
+<td>
+ <p>
+ HPUX IA64, aCC A.06.06
+ </p>
+ </td>
+<td>
+ <p>
+ Peak=6700 Mean=230
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><p>
+ Note that the worst errors occur when the degree increases, values greater
+ than ~120 are very unlikely to produce sensible results, especially when
+ the order is also large. Further the relative errors are likely to grow
+ arbitrarily large when the function is very close to a root.
+ </p>
+<a name="math_toolkit.special.sf_poly.sph_harm.testing"></a><h5>
+<a name="id668157"></a>
+ Testing
+ </h5>
+<p>
+ A mixture of spot tests of values calculated using functions.wolfram.com,
+ and randomly generated test data are used: the test data was computed using
+ NTL::RR at 1000-bit
+ precision.
+ </p>
+<a name="math_toolkit.special.sf_poly.sph_harm.implementation"></a><h5>
+<a name="id668196"></a>
+ Implementation
+ </h5>
+<p>
+ These functions are implemented fairly naively using the formulae given
+ above. Some extra care is taken to prevent roundoff error when converting
+ from polar coordinates (so for example the <span class="emphasis"><em>1-x<sup>2</sup></em></span> term
+ used by the associated Legendre functions is calculated without roundoff
+ error using <span class="emphasis"><em>x = cos(theta)</em></span>, and <span class="emphasis"><em>1-x<sup>2</sup> = sin<sup>2</sup>(theta)</em></span>).
+ The limiting factor in the error rates for these functions is the need
+ to calculate values near the roots of the associated Legendre functions.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="hermite.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_poly.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../bessel.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sinc.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sinc.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,47 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Sinus Cardinal and Hyperbolic Sinus Cardinal Functions</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../special.html" title="Special Functions">
+<link rel="prev" href="powers/hypot.html" title="hypot">
+<link rel="next" href="sinc/sinc_overview.html" title="Sinus Cardinal and Hyperbolic Sinus Cardinal Functions Overview">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="powers/hypot.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sinc/sinc_overview.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.special.sinc"></a><a href="sinc.html" title="Sinus Cardinal and Hyperbolic Sinus Cardinal Functions"> Sinus Cardinal and Hyperbolic
+ Sinus Cardinal Functions</a>
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="sinc/sinc_overview.html"> Sinus Cardinal
+ and Hyperbolic Sinus Cardinal Functions Overview</a></span></dt>
+<dt><span class="section">sinc_pi</span></dt>
+<dt><span class="section">sinhc_pi</span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="powers/hypot.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../special.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sinc/sinc_overview.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sinc/sinc_overview.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sinc/sinc_overview.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,81 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Sinus Cardinal and Hyperbolic Sinus Cardinal Functions Overview</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sinc.html" title="Sinus Cardinal and Hyperbolic Sinus Cardinal Functions">
+<link rel="prev" href="../sinc.html" title="Sinus Cardinal and Hyperbolic Sinus Cardinal Functions">
+<link rel="next" href="sinc_pi.html" title="sinc_pi">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../sinc.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sinc.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sinc_pi.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sinc.sinc_overview"></a><a href="sinc_overview.html" title="Sinus Cardinal and Hyperbolic Sinus Cardinal Functions Overview"> Sinus Cardinal
+ and Hyperbolic Sinus Cardinal Functions Overview</a>
+</h4></div></div></div>
+<p>
+ The <a href="http://mathworld.wolfram.com/SincFunction.html" target="_top">Sinus Cardinal
+ family of functions</a> (indexed by the family of indices <code class="literal">a
+ &gt; 0</code>) is defined by <span class="inlinemediaobject"><img src="../../../../equations/special_functions_blurb20.png"></span>;
+ it sees heavy use in signal processing tasks.
+ </p>
+<p>
+ By analogy, the <a href="http://mathworld.wolfram.com/SinhcFunction.htm" target="_top">Hyperbolic
+ Sinus Cardinal</a> family of functions (also indexed by the family
+ of indices <code class="literal">a &gt; 0</code>) is defined by <span class="inlinemediaobject"><img src="../../../../equations/special_functions_blurb22.png"></span>.
+ </p>
+<p>
+ These two families of functions are composed of entire functions.
+ </p>
+<p>
+ These functions (sinc_pi
+ and sinhc_pi)
+ are needed by <a href="http://www.boost.org/libs/math/quaternion/quaternion.html" target="_top">our
+ implementation</a> of quaternions
+ and octonions.
+ </p>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ <span class="emphasis"><em><span class="bold"><strong>Sinus Cardinal of index pi (purple)
+ and Hyperbolic Sinus Cardinal of index pi (red) on R</strong></span></em></span>
+ </p>
+<p>
+ </p>
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+<p>
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/sinc_pi_and_sinhc_pi_on_r.png" alt="sinc_pi_and_sinhc_pi_on_r"></span>
+ </p>
+<p>
+ </p>
+</blockquote></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../sinc.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sinc.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sinc_pi.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sinc/sinc_pi.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sinc/sinc_pi.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,82 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>sinc_pi</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sinc.html" title="Sinus Cardinal and Hyperbolic Sinus Cardinal Functions">
+<link rel="prev" href="sinc_overview.html" title="Sinus Cardinal and Hyperbolic Sinus Cardinal Functions Overview">
+<link rel="next" href="sinhc_pi.html" title="sinhc_pi">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sinc_overview.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sinc.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sinhc_pi.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sinc.sinc_pi"></a>sinc_pi
+</h4></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">sinc</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">sinc_pi</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">sinc_pi</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span><span class="special">&gt;</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+<span class="identifier">U</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">sinc_pi</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">U</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span><span class="special">&gt;</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">U</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">sinc_pi</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">U</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Computes <a href="sinc_overview.html" title="Sinus Cardinal and Hyperbolic Sinus Cardinal Functions Overview">the Sinus
+ Cardinal</a> of x:
+ </p>
+<pre class="programlisting">
+<span class="identifier">sinc_pi</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">sin</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">/</span> <span class="identifier">x</span>
+</pre>
+<p>
+ The second form is for complex numbers, quaternions, octonions etc. Taylor
+ series are used at the origin to ensure accuracy.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sinc_overview.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sinc.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="sinhc_pi.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sinc/sinhc_pi.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/special/sinc/sinhc_pi.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,86 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>sinhc_pi</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../sinc.html" title="Sinus Cardinal and Hyperbolic Sinus Cardinal Functions">
+<link rel="prev" href="sinc_pi.html" title="sinc_pi">
+<link rel="next" href="../inv_hyper.html" title="Inverse Hyperbolic Functions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sinc_pi.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sinc.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../inv_hyper.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.special.sinc.sinhc_pi"></a>sinhc_pi
+</h4></div></div></div>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">sinhc</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+calculated-result-type <span class="identifier">sinhc_pi</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+calculated-result-type <span class="identifier">sinhc_pi</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span><span class="special">&gt;</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+<span class="identifier">U</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">sinhc_pi</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">U</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">x</span><span class="special">);</span>
+
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span><span class="special">&gt;</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">U</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">sinhc_pi</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">U</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ Computes http://mathworld.wolfram.com/SinhcFunction.html <a href="sinc_overview.html" title="Sinus Cardinal and Hyperbolic Sinus Cardinal Functions Overview">the
+ Hyperbolic Sinus Cardinal</a> of x:
+ </p>
+<pre class="programlisting">
+<span class="identifier">sinhc_pi</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">sinh</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">/</span> <span class="identifier">x</span>
+</pre>
+<p>
+ The second form is for complex numbers, quaternions, octonions etc. Taylor
+ series are used at the origin to ensure accuracy.
+ </p>
+<p>
+ The return type of the first form is computed using the <a href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
+ type calculation rules</em></span></a> when T is an integer type.
+ </p>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sinc_pi.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sinc.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../inv_hyper.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/status.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/status.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,46 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Library Status</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../index.html" title="Math Toolkit">
+<link rel="up" href="../index.html" title="Math Toolkit">
+<link rel="prev" href="backgrounders/refs.html" title="References">
+<link rel="next" href="status/history1.html" title="History and What's New">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="backgrounders/refs.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="status/history1.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="math_toolkit.status"></a> Library Status
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"> History and What's New</span></dt>
+<dt><span class="section"> Compilers</span></dt>
+<dt><span class="section"> Known Issues, and Todo List</span></dt>
+<dt><span class="section"> Credits and Acknowledgements</span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="backgrounders/refs.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="status/history1.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/status/compilers.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/status/compilers.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,174 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Compilers</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../status.html" title="Library Status">
+<link rel="prev" href="history1.html" title="History and What's New">
+<link rel="next" href="issues.html" title="Known Issues, and Todo List">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="history1.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../status.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="issues.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.status.compilers"></a> Compilers
+</h3></div></div></div>
+<p>
+ This section contains some information about how various compilers work with
+ this library. It is not comprehensive and updated experiences are always
+ welcome. Some effort has been made to suppress unhelpful warnings but it
+ is difficult to achieve this on all systems.
+ </p>
+<p>
+ The code has been compiled and tested with:
+ </p>
+<div class="table">
+<a name="id791316"></a><p class="title"><b>Table 45. Compiler Notes</b></p>
+<div class="table-contents"><table class="table" summary="Compiler Notes">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Compiler
+ </p>
+ </th>
+<th>
+ <p>
+ Platform
+ </p>
+ </th>
+<th>
+ <p>
+ Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ Intel 9.1, 8.1
+ </p>
+ </td>
+<td>
+ <p>
+ Win32 and Linux
+ </p>
+ </td>
+<td>
+ <p>
+ The tests cases tend to generate a lot of warnings relating to numeric
+ underflow of the test data: these are harmless. The headers all appear
+ to be warning free.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ g++
+ </p>
+ </td>
+<td>
+ <p>
+ Linux and HP-UX
+ </p>
+ </td>
+<td>
+ <p>
+ The test suite doesn't compile with -pedantic (a problem with system
+ headers included by Boost.Test not compiling with that option), otherwise
+ our headers should be warning free.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ HP aCC
+ </p>
+ </td>
+<td>
+ <p>
+ HP-UX
+ </p>
+ </td>
+<td>
+ <p>
+ Unfortunately this emits quite a few warnings from libraries upon which
+ we depend (TR1, Array etc).
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Borland 5.8.2
+ </p>
+ </td>
+<td>
+ <p>
+ Windows
+ </p>
+ </td>
+<td>
+ <p>
+ Almost works: some effort has been put into porting to this compiler.
+ However, during testing a number of instances were encountered where
+ this compiler generated incorrect code: completely omitting a function
+ call seemingly at random. For this reason, <span class="bold"><strong>we
+ cannot recommend using this library with this compiler</strong></span>,
+ as the correct operation of the code cannot be guaranteed.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ MSVC 8.0
+ </p>
+ </td>
+<td>
+ <p>
+ Windows
+ </p>
+ </td>
+<td>
+ <p>
+ Warning free at level 4
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break">
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="history1.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../status.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="issues.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/status/credits.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/status/credits.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,80 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Credits and Acknowledgements</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../status.html" title="Library Status">
+<link rel="prev" href="issues.html" title="Known Issues, and Todo List">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="issues.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../status.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.status.credits"></a> Credits and Acknowledgements
+</h3></div></div></div>
+<p>
+ Hubert Holin started the Boost.Math library. The inverse hyperbolic functions,
+ and the sinus cardinal functions are his.
+ </p>
+<p>
+ John Maddock started this library, the beta, gamma, erf, polynomial, and
+ factorial functions are his, as is the "Toolkit" section, and many
+ of the statistical distributions.
+ </p>
+<p>
+ Paul A. Bristow threw down the challenge in <a href="http://www2.open-std.org/JTC1/SC22/WG21/docs/papers/2004/n1668.pdf" target="_top">A
+ Proposal to add Mathematical Functions for Statistics to the C++ Standard
+ Library</a> to add the key math functions, especially those essential
+ for statistics. After JM accepted and solved the difficult problems, not
+ only numerically, but in full C++ template style, PAB implemented a few of
+ the statistical distributions. PAB also tirelessly proof-read everything
+ that JM threw at him (so that all remaining editorial mistakes are his fault).
+ </p>
+<p>
+ Xiaogang Zhang worked on the Bessel functions and elliptic integrals for
+ his Google Summer of Code project 2006.
+ </p>
+<p>
+ Professor Nico Temme for advice on the inverse incomplete beta function.
+ </p>
+<p>
+ Victor Shoup for NTL, without which
+ it would have much difficult to produce high accuracy constants, and especially
+ the tables of accurate values for testing.
+ </p>
+<p>
+ We are grateful to Joel Guzman for helping us stress-test his Boost.Quickbook
+ program used to generate the html and pdf versions of this document, adding
+ several new features en route.
+ </p>
+<p>
+ 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.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="issues.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../status.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/status/history1.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/status/history1.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,213 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>History and What's New</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../status.html" title="Library Status">
+<link rel="prev" href="../status.html" title="Library Status">
+<link rel="next" href="compilers.html" title="Compilers">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../status.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../status.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="compilers.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.status.history1"></a> History and What's New
+</h3></div></div></div>
+<p>
+ <a name="math_toolkit.status.history1.milestone_5__post_review_first_official_release"></a>
+ </p>
+<h5>
+<a name="id790935"></a>
+ <a href="history1.html#math_toolkit.status.history1.milestone_5__post_review_first_official_release">Milestone
+ 5: Post Review First Official Release</a>
+ </h5>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Added Policy based framework that allows fine grained control over function
+ behaviour.
+ </li>
+<li>
+<span class="bold"><strong>Breaking change:</strong></span> Changed default behaviour
+ for domain, pole and overflow errors to throw an exception (based on
+ review feedback), this behaviour can be customised using Policy's.
+ </li>
+<li>
+<span class="bold"><strong>Breaking change:</strong></span> Changed exception thrown
+ when an internal evaluation error occurs to boost::math::evaluation_error.
+ </li>
+<li>
+<span class="bold"><strong>Breaking change:</strong></span> Changed discrete quantiles
+ to return an integer result: this is anything up to 20 times faster than
+ finding the true root, this behaviour can be customised using Policy's.
+ </li>
+<li>
+ Polynomial/rational function evaluation is now customisable and hopefully
+ faster than before.
+ </li>
+<li>
+ Added performance test program.
+ </li>
+</ul></div>
+<p>
+ <a name="math_toolkit.status.history1.milestone_4__second_review_candidate__1st_march_2007_"></a>
+ </p>
+<h5>
+<a name="id791038"></a>
+ <a href="history1.html#math_toolkit.status.history1.milestone_4__second_review_candidate__1st_march_2007_">Milestone
+ 4: Second Review Candidate (1st March 2007)</a>
+ </h5>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Moved Xiaogang Zhang's Bessel Functions code into the library, and brought
+ them into line with the rest of the code.
+ </li>
+<li>
+ Added C# "Distribution Explorer" demo application.
+ </li>
+</ul></div>
+<p>
+ <a name="math_toolkit.status.history1.milestone_3__first_review_candidate__31st_dec_2006_"></a>
+ </p>
+<h5>
+<a name="id791079"></a>
+ <a href="history1.html#math_toolkit.status.history1.milestone_3__first_review_candidate__31st_dec_2006_">Milestone
+ 3: First Review Candidate (31st Dec 2006)</a>
+ </h5>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Implemented the main probability distribution and density functions.
+ </li>
+<li>
+ Implemented digamma.
+ </li>
+<li>
+ Added more factorial functions.
+ </li>
+<li>
+ Implemented the Hermite, Legendre and Laguerre polynomials plus the spherical
+ harmonic functions from TR1.
+ </li>
+<li>
+ Moved Xiaogang Zhang's elliptic integral code into the library, and brought
+ them into line with the rest of the code.
+ </li>
+<li>
+ Moved Hubert Holin's existing Boost.Math special functions into this
+ library and brought them into line with the rest of the code.
+ </li>
+</ul></div>
+<p>
+ <a name="math_toolkit.status.history1.milestone_2__released_september_10th_2006"></a>
+ </p>
+<h5>
+<a name="id791145"></a>
+ <a href="history1.html#math_toolkit.status.history1.milestone_2__released_september_10th_2006">Milestone
+ 2: Released September 10th 2006</a>
+ </h5>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Implement preview release of the statistical distributions.
+ </li>
+<li>
+ Added statistical distributions tutorial.
+ </li>
+<li>
+ Implemented root finding algorithms.
+ </li>
+<li>
+ Implemented the inverses of the incomplete gamma and beta functions.
+ </li>
+<li>
+ Rewrite erf/erfc as rational approximations (valid to 128-bit precision).
+ </li>
+<li>
+ Integrated the statistical results generated from the test data with
+ Boost.Test: uses a database of expected results, indexed by test, floating
+ point type, platform, and compiler.
+ </li>
+<li>
+ Improved lgamma near 1 and 2 (rational approximations).
+ </li>
+<li>
+ Improved erf/erfc inverses (rational approximations).
+ </li>
+<li>
+ Implemented Rational function generation (the Remez method).
+ </li>
+</ul></div>
+<p>
+ <a name="math_toolkit.status.history1.milestone_1__released_march_31st_2006"></a>
+ </p>
+<h5>
+<a name="id791222"></a>
+ <a href="history1.html#math_toolkit.status.history1.milestone_1__released_march_31st_2006">Milestone
+ 1: Released March 31st 2006</a>
+ </h5>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Implement gamma/beta/erf functions along with their incomplete counterparts.
+ </li>
+<li>
+ Generate high quality test data, against which future improvements can
+ be judged.
+ </li>
+<li>
+ Provide tools for the evaluation of infinite series, continued fractions,
+ and rational functions.
+ </li>
+<li>
+ Provide tools for testing against tabulated test data, and collecting
+ statistics on error rates.
+ </li>
+<li>
+ Provide sufficient docs for people to be able to find their way around
+ the library.
+ </li>
+</ul></div>
+<p>
+ </p>
+<p>
+ SVN Revisions:
+ </p>
+<p>
+ </p>
+<p>
+ Sandbox revision merged to trunk: 39833. Trunk revision: 39833.
+ </p>
+<p>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../status.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../status.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="compilers.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/status/issues.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/status/issues.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,159 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Known Issues, and Todo List</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../status.html" title="Library Status">
+<link rel="prev" href="compilers.html" title="Compilers">
+<link rel="next" href="credits.html" title="Credits and Acknowledgements">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="compilers.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../status.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="credits.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.status.issues"></a> Known Issues, and Todo List
+</h3></div></div></div>
+<p>
+ This section lists those issues that are known about.
+ </p>
+<p>
+ Predominantly this is a TODO list, or a list of possible future enhancements.
+ Items labled "High Priority" effect the proper functioning of the
+ component, and should be fixed as soon as possible. Items labled "Medium
+ Priority" are desirable enhancements, often pertaining to the performance
+ of the component, but do not effect it's accuracy or functionality. Items
+ labled "Low Priority" should probably be investigated at some point.
+ Such classifications are obviously highly subjective.
+ </p>
+<p>
+ If you don't see a component listed here, then we don't have any known issues
+ with it.
+ </p>
+<a name="math_toolkit.status.issues.tgamma"></a><h5>
+<a name="id791562"></a>
+ tgamma
+ </h5>
+<div class="itemizedlist"><ul type="disc"><li>
+ Can the Lanczos approximation
+ be optimized any further? (low priority)
+ </li></ul></div>
+<a name="math_toolkit.status.issues.incomplete_beta"></a><h5>
+<a name="id791604"></a>
+ Incomplete Beta
+ </h5>
+<div class="itemizedlist"><ul type="disc"><li>
+ Investigate Didonato and Morris' asymptotic expansion for large a and b
+ (medium priority).
+ </li></ul></div>
+<a name="math_toolkit.status.issues.inverse_gamma"></a><h5>
+<a name="id791637"></a>
+ Inverse Gamma
+ </h5>
+<div class="itemizedlist"><ul type="disc"><li>
+ Investigate whether we can skip iteration altogether if the first approximation
+ is good enough (Medium Priority).
+ </li></ul></div>
+<a name="math_toolkit.status.issues.polynomials"></a><h5>
+<a name="id791669"></a>
+ Polynomials
+ </h5>
+<div class="itemizedlist"><ul type="disc"><li>
+ The Legendre and Laguerre Polynomials have surprisingly different error
+ rates on different platforms, considering they are evaluated with only
+ basic arithmetic operations. Maybe this is telling us something, or maybe
+ not (Low Priority).
+ </li></ul></div>
+<a name="math_toolkit.status.issues.elliptic_integrals"></a><h5>
+<a name="id791706"></a>
+ Elliptic Integrals
+ </h5>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Carlson's algorithms are essentially unchanged from Xiaogang Zhang's Google
+ Summer of Code student project, and are based on Carlson's original papers.
+ However, Carlson has revised his algorithms since then (refer to the references
+ in the elliptic integral docs for a list), to improve performance and accuracy,
+ we may be able to take advantage of these improvements too (Low Priority).
+ </li>
+<li>
+<p>Carlson's algorithms (mainly R<sub>J</sub>) are somewhat prone to internal overflow/underflow
+ when the arguments are very large or small. The homogeneity relations:</p>
+<p>R<sub>F</sub>(ka,
+ kb, kc) = k<sup>-1/2</sup> R<sub>F</sub>(a, b, c)</p>
+<p>and</p>
+<p>R<sub>J</sub>(ka, kb, kc, kr) = k<sup>-3/2</sup> R<sub>J</sub>(a, b, c, r)</p>
+<p>could
+ be used to sidestep trouble here: provided the problem domains can be accurately
+ identified. (Medium Priority).</p>
+</li>
+<li>
+ Carlson's R<sub>C</sub> can be reduced to elementary funtions (asin and log), would
+ it be more efficient evaluated this way, rather than by Carlson's algorithms?
+ (Low Priority).
+ </li>
+<li>
+ Should we add an implementation of Carlson's R<sub>G</sub>? It's not required for
+ the Legendre form integrals, but some people may find it useful (Low Priority).
+ </li>
+<li>
+ There are a several other integrals: D(&#966;, k), Z(&#946;, k), &#923;<sub>0</sub>(&#946;, k) and Bulirsch's
+ <span class="emphasis"><em>el</em></span> functions that could be implemented using Carlson's
+ integrals (Low Priority).
+ </li>
+<li>
+ The integrals K(k) and E(k) could be implemented using rational approximations
+ (both for efficiency and accuracy), assuming we can find them. (Medium
+ Priority).
+ </li>
+<li>
+ There is a sub-domain of ellint_3
+ that is unimplemented (see the docs for details), currently it's not clear
+ how to solve this issue, or if it's ever likely to be an real problem in
+ practice - especially as most other implementations don't support this
+ domain either (Medium Priority).
+ </li>
+</ul></div>
+<a name="math_toolkit.status.issues.inverse_hyperbolic_functions"></a><h5>
+<a name="id791864"></a>
+ <a href="issues.html#math_toolkit.status.issues.inverse_hyperbolic_functions">Inverse
+ Hyperbolic Functions</a>
+ </h5>
+<div class="itemizedlist"><ul type="disc"><li>
+ These functions are inherited from previous Boost versions, before log1p became widely
+ available. Would they be better expressed in terms of this function? This
+ is probably only an issue for very high precision types (Low Priority).
+ </li></ul></div>
+<a name="math_toolkit.status.issues.statistical_distributions"></a><h5>
+<a name="id791909"></a>
+ <a href="issues.html#math_toolkit.status.issues.statistical_distributions">Statistical
+ distributions</a>
+ </h5>
+<div class="itemizedlist"><ul type="disc"><li>
+ Student's t Perhaps switch to normal distribution as a better approximation
+ for very large degrees of freedom?
+ </li></ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="compilers.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../status.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="credits.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,68 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Internal Details and Tools (Experimental)</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../index.html" title="Math Toolkit">
+<link rel="up" href="../index.html" title="Math Toolkit">
+<link rel="prev" href="special/fpclass.html" title="Floating Point Classification: Infinities and NaN's">
+<link rel="next" href="toolkit/internals_overview.html" title="Overview">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="special/fpclass.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="toolkit/internals_overview.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="math_toolkit.toolkit"></a> Internal Details and Tools (Experimental)
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"> Overview</span></dt>
+<dt><span class="section"> Reused Utilities</span></dt>
+<dd><dl>
+<dt><span class="section"><a href="toolkit/internals1/series_evaluation.html">
+ Series Evaluation</a></span></dt>
+<dt><span class="section"><a href="toolkit/internals1/cf.html"> Continued Fraction
+ Evaluation</a></span></dt>
+<dt><span class="section"><a href="toolkit/internals1/rational.html"> Polynomial
+ and Rational Function Evaluation</a></span></dt>
+<dt><span class="section"><a href="toolkit/internals1/roots.html"> Root Finding
+ With Derivatives</a></span></dt>
+<dt><span class="section"><a href="toolkit/internals1/roots2.html"> Root Finding
+ Without Derivatives</a></span></dt>
+<dt><span class="section"><a href="toolkit/internals1/minima.html"> Locating Function
+ Minima</a></span></dt>
+</dl></dd>
+<dt><span class="section"> Testing and Development</span></dt>
+<dd><dl>
+<dt><span class="section"> Polynomials</span></dt>
+<dt><span class="section"><a href="toolkit/internals2/minimax.html"> Minimax Approximations
+ and the Remez Algorithm</a></span></dt>
+<dt><span class="section"><a href="toolkit/internals2/error_test.html"> Relative
+ Error and Testing</a></span></dt>
+<dt><span class="section"><a href="toolkit/internals2/test_data.html"> Graphing,
+ Profiling, and Generating Test Data for Special Functions</a></span></dt>
+</dl></dd>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="special/fpclass.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="toolkit/internals_overview.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,54 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Reused Utilities</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../toolkit.html" title="Internal Details and Tools (Experimental)">
+<link rel="prev" href="internals_overview.html" title="Overview">
+<link rel="next" href="internals1/series_evaluation.html" title="Series Evaluation">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="internals_overview.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../toolkit.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="internals1/series_evaluation.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.toolkit.internals1"></a> Reused Utilities
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="internals1/series_evaluation.html">
+ Series Evaluation</a></span></dt>
+<dt><span class="section"><a href="internals1/cf.html"> Continued Fraction
+ Evaluation</a></span></dt>
+<dt><span class="section"><a href="internals1/rational.html"> Polynomial
+ and Rational Function Evaluation</a></span></dt>
+<dt><span class="section"><a href="internals1/roots.html"> Root Finding
+ With Derivatives</a></span></dt>
+<dt><span class="section"><a href="internals1/roots2.html"> Root Finding
+ Without Derivatives</a></span></dt>
+<dt><span class="section"><a href="internals1/minima.html"> Locating Function
+ Minima</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="internals_overview.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../toolkit.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="internals1/series_evaluation.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/cf.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/cf.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,267 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Continued Fraction Evaluation</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../internals1.html" title="Reused Utilities">
+<link rel="prev" href="series_evaluation.html" title="Series Evaluation">
+<link rel="next" href="rational.html" title="Polynomial and Rational Function Evaluation">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="series_evaluation.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals1.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="rational.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.toolkit.internals1.cf"></a><a href="cf.html" title="Continued Fraction Evaluation"> Continued Fraction
+ Evaluation</a>
+</h4></div></div></div>
+<a name="math_toolkit.toolkit.internals1.cf.synopsis"></a><h5>
+<a name="id699817"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">fraction</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">tools</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Gen</span><span class="special">&gt;</span>
+<span class="keyword">typename</span> <span class="identifier">detail</span><span class="special">::</span><span class="identifier">fraction_traits</span><span class="special">&lt;</span><span class="identifier">Gen</span><span class="special">&gt;::</span><span class="identifier">result_type</span>
+ <span class="identifier">continued_fraction_b</span><span class="special">(</span><span class="identifier">Gen</span><span class="special">&amp;</span> <span class="identifier">g</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">bits</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Gen</span><span class="special">&gt;</span>
+<span class="keyword">typename</span> <span class="identifier">detail</span><span class="special">::</span><span class="identifier">fraction_traits</span><span class="special">&lt;</span><span class="identifier">Gen</span><span class="special">&gt;::</span><span class="identifier">result_type</span>
+ <span class="identifier">continued_fraction_b</span><span class="special">(</span><span class="identifier">Gen</span><span class="special">&amp;</span> <span class="identifier">g</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">bits</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_terms</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Gen</span><span class="special">&gt;</span>
+<span class="keyword">typename</span> <span class="identifier">detail</span><span class="special">::</span><span class="identifier">fraction_traits</span><span class="special">&lt;</span><span class="identifier">Gen</span><span class="special">&gt;::</span><span class="identifier">result_type</span>
+ <span class="identifier">continued_fraction_a</span><span class="special">(</span><span class="identifier">Gen</span><span class="special">&amp;</span> <span class="identifier">g</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">bits</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Gen</span><span class="special">&gt;</span>
+<span class="keyword">typename</span> <span class="identifier">detail</span><span class="special">::</span><span class="identifier">fraction_traits</span><span class="special">&lt;</span><span class="identifier">Gen</span><span class="special">&gt;::</span><span class="identifier">result_type</span>
+ <span class="identifier">continued_fraction_a</span><span class="special">(</span><span class="identifier">Gen</span><span class="special">&amp;</span> <span class="identifier">g</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">bits</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_terms</span><span class="special">);</span>
+
+<span class="special">}}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.toolkit.internals1.cf.description"></a><h5>
+<a name="id700540"></a>
+ Description
+ </h5>
+<p>
+ <a href="http://en.wikipedia.org/wiki/Continued_fraction" target="_top">Continued
+ fractions are a common method of approximation. </a> These functions
+ all evaluate the continued fraction described by the <span class="emphasis"><em>generator</em></span>
+ type argument. The functions with an "_a" suffix evaluate the
+ fraction:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/fraction2.png"></span>
+ </p>
+<p>
+ and those with a "_b" suffix evaluate the fraction:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/fraction1.png"></span>
+ </p>
+<p>
+ This latter form is somewhat more natural in that it corresponds with the
+ usual definition of a continued fraction, but note that the first <span class="emphasis"><em>a</em></span>
+ value returned by the generator is discarded. Further, often the first
+ <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span> values in a continued
+ fraction have different defining equations to the remaining terms, which
+ may make the "_a" suffixed form more appropriate.
+ </p>
+<p>
+ The generator type should be a function object which supports the following
+ operations:
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Expression
+ </p>
+ </th>
+<th>
+ <p>
+ Description
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ Gen::result_type
+ </p>
+ </td>
+<td>
+ <p>
+ The type that is the result of invoking operator(). This can be
+ either an arithmetic type, or a std::pair&lt;&gt; of arithmetic
+ types.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ g()
+ </p>
+ </td>
+<td>
+ <p>
+ Returns an object of type Gen::result_type.
+ </p>
+ <p>
+ Each time this operator is called then the next pair of <span class="emphasis"><em>a</em></span>
+ and <span class="emphasis"><em>b</em></span> values is returned. Or, if result_type
+ is an arithmetic type, then the next <span class="emphasis"><em>b</em></span> value
+ is returned and all the <span class="emphasis"><em>a</em></span> values are assumed
+ to 1.
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<p>
+ In all the continued fraction evaluation functions the <span class="emphasis"><em>bits</em></span>
+ parameter is the number of bits precision desired in the result, evaluation
+ of the fraction will continue until the last term evaluated leaves the
+ first <span class="emphasis"><em>bits</em></span> bits in the result unchanged.
+ </p>
+<p>
+ If the optional <span class="emphasis"><em>max_terms</em></span> parameter is specified then
+ no more than <span class="emphasis"><em>max_terms</em></span> calls to the generator will
+ be made, and on output, <span class="emphasis"><em>max_terms</em></span> will be set to actual
+ number of calls made. This facility is particularly useful when profiling
+ a continued fraction for convergence.
+ </p>
+<a name="math_toolkit.toolkit.internals1.cf.implementation"></a><h5>
+<a name="id700818"></a>
+ Implementation
+ </h5>
+<p>
+ Internally these algorithms all use the modified Lentz algorithm: refer
+ to Numeric Recipes in C++, W. H. Press et all, chapter 5, (especially 5.2
+ Evaluation of continued fractions, p 175 - 179) for more information, also
+ Lentz, W.J. 1976, Applied Optics, vol. 15, pp. 668-671.
+ </p>
+<a name="math_toolkit.toolkit.internals1.cf.examples"></a><h5>
+<a name="id700852"></a>
+ Examples
+ </h5>
+<p>
+ The <a href="http://en.wikipedia.org/wiki/Golden_ratio" target="_top">golden ratio
+ phi = 1.618033989...</a> can be computed from the simplest continued
+ fraction of all:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/fraction3.png"></span>
+ </p>
+<p>
+ We begin by defining a generator function:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">golden_ratio_fraction</span>
+<span class="special">{</span>
+ <span class="keyword">typedef</span> <span class="identifier">T</span> <span class="identifier">result_type</span><span class="special">;</span>
+
+ <span class="identifier">result_type</span> <span class="keyword">operator</span><span class="special">()</span>
+ <span class="special">{</span>
+ <span class="keyword">return</span> <span class="number">1</span><span class="special">;</span>
+ <span class="special">}</span>
+<span class="special">};</span>
+</pre>
+<p>
+ The golden ratio can then be computed to double precision using:
+ </p>
+<pre class="programlisting">
+<span class="identifier">continued_fraction_a</span><span class="special">(</span>
+ <span class="identifier">golden_ratio_fraction</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;(),</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">digits</span><span class="special">);</span>
+</pre>
+<p>
+ It's more usual though to have to define both the <span class="emphasis"><em>a</em></span>'s
+ and the <span class="emphasis"><em>b</em></span>'s when evaluating special functions by continued
+ fractions, for example the tan function is defined by:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/fraction4.png"></span>
+ </p>
+<p>
+ So it's generator object would look like:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">tan_fraction</span>
+<span class="special">{</span>
+<span class="keyword">private</span><span class="special">:</span>
+ <span class="identifier">T</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">;</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="identifier">tan_fraction</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">v</span><span class="special">)</span>
+ <span class="special">:</span> <span class="identifier">a</span><span class="special">(-</span><span class="identifier">v</span><span class="special">*</span><span class="identifier">v</span><span class="special">),</span> <span class="identifier">b</span><span class="special">(-</span><span class="number">1</span><span class="special">)</span>
+ <span class="special">{}</span>
+
+ <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">result_type</span><span class="special">;</span>
+
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">operator</span><span class="special">()()</span>
+ <span class="special">{</span>
+ <span class="identifier">b</span> <span class="special">+=</span> <span class="number">2</span><span class="special">;</span>
+ <span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">);</span>
+ <span class="special">}</span>
+<span class="special">};</span>
+</pre>
+<p>
+ Notice that if the continuant is subtracted from the <span class="emphasis"><em>b</em></span>
+ terms, as is the case here, then all the <span class="emphasis"><em>a</em></span> terms returned
+ by the generator will be negative. The tangent function can now be evaluated
+ using:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">tan</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">a</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="identifier">tan_fraction</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">fract</span><span class="special">(</span><span class="identifier">a</span><span class="special">);</span>
+ <span class="keyword">return</span> <span class="identifier">a</span> <span class="special">/</span> <span class="identifier">continued_fraction_b</span><span class="special">(</span><span class="identifier">fract</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">digits</span><span class="special">);</span>
+<span class="special">}</span>
+</pre>
+<p>
+ Notice that this time we're using the "_b" suffixed version to
+ evaluate the fraction: we're removing the leading <span class="emphasis"><em>a</em></span>
+ term during fraction evaluation as it's different from all the others.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="series_evaluation.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals1.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="rational.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/minima.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/minima.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,124 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Locating Function Minima</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../internals1.html" title="Reused Utilities">
+<link rel="prev" href="roots2.html" title="Root Finding Without Derivatives">
+<link rel="next" href="../internals2.html" title="Testing and Development">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="roots2.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals1.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../internals2.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.toolkit.internals1.minima"></a><a href="minima.html" title="Locating Function Minima"> Locating Function
+ Minima</a>
+</h4></div></div></div>
+<a name="math_toolkit.toolkit.internals1.minima.synopsis"></a><h5>
+<a name="id717575"></a>
+ synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">minima</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">brent_find_minima</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">min</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">max</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">bits</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">brent_find_minima</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">min</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">max</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">bits</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">);</span>
+</pre>
+<a name="math_toolkit.toolkit.internals1.minima.description"></a><h5>
+<a name="id718047"></a>
+ Description
+ </h5>
+<p>
+ These two functions locate the minima of the continuous function <span class="emphasis"><em>f</em></span>
+ using Brent's algorithm. Parameters are:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">f</span></dt>
+<dd><p>
+ The function to minimise. The function should be smooth over the range
+ [min,max], with no maxima occurring in that interval.
+ </p></dd>
+<dt><span class="term">min</span></dt>
+<dd><p>
+ The lower endpoint of the range in which to search for the minima.
+ </p></dd>
+<dt><span class="term">max</span></dt>
+<dd><p>
+ The upper endpoint of the range in which to search for the minima.
+ </p></dd>
+<dt><span class="term">bits</span></dt>
+<dd><p>
+ The number of bits precision to which the minima should be found. Note
+ that in principle, the minima can not be located to greater accuracy
+ than the square root of machine epsilon, therefore if <span class="emphasis"><em>bits</em></span>
+ is set to a value greater than one half of the bits in type T, then
+ the value will be ignored.
+ </p></dd>
+<dt><span class="term">max_iter</span></dt>
+<dd><p>
+ The maximum number of iterations to use in the algorithm, if not provided
+ the algorithm will just keep on going until the minima is found.
+ </p></dd>
+</dl>
+</div>
+<p>
+ <span class="bold"><strong>Returns:</strong></span> a pair containing the value of
+ the abscissa at the minima and the value of f(x) at the minima.
+ </p>
+<a name="math_toolkit.toolkit.internals1.minima.implementation"></a><h5>
+<a name="id718186"></a>
+ Implementation
+ </h5>
+<p>
+ This is a reasonably faithful implementation of Brent's algorithm, refer
+ to:
+ </p>
+<p>
+ Brent, R.P. 1973, Algorithms for Minimization without Derivatives (Englewood
+ Cliffs, NJ: Prentice-Hall), Chapter 5.
+ </p>
+<p>
+ Numerical Recipes in C, The Art of Scientific Computing, Second Edition,
+ William H. Press, Saul A. Teukolsky, William T. Vetterling, and Brian P.
+ Flannery. Cambridge University Press. 1988, 1992.
+ </p>
+<p>
+ An algorithm with guaranteed convergence for finding a zero of a function,
+ R. P. Brent, The Computer Journal, Vol 44, 1971.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="roots2.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals1.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../internals2.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/rational.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/rational.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,239 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Polynomial and Rational Function Evaluation</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../internals1.html" title="Reused Utilities">
+<link rel="prev" href="cf.html" title="Continued Fraction Evaluation">
+<link rel="next" href="roots.html" title="Root Finding With Derivatives">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="cf.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals1.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="roots.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.toolkit.internals1.rational"></a><a href="rational.html" title="Polynomial and Rational Function Evaluation"> Polynomial
+ and Rational Function Evaluation</a>
+</h4></div></div></div>
+<a name="math_toolkit.toolkit.internals1.rational.synopsis"></a><h5>
+<a name="id701838"></a>
+ synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">rational</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="comment">// Polynomials:
+</span><span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">(&amp;</span><span class="identifier">poly</span><span class="special">)[</span><span class="identifier">N</span><span class="special">],</span> <span class="keyword">const</span> <span class="identifier">V</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">N</span><span class="special">&gt;&amp;</span> <span class="identifier">poly</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">V</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+<span class="identifier">U</span> <span class="identifier">evaluate_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">*</span> <span class="identifier">poly</span><span class="special">,</span> <span class="identifier">U</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">count</span><span class="special">);</span>
+
+<span class="comment">// Even polynomials:
+</span><span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_even_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">(&amp;</span><span class="identifier">poly</span><span class="special">)[</span><span class="identifier">N</span><span class="special">],</span> <span class="keyword">const</span> <span class="identifier">V</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_even_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">N</span><span class="special">&gt;&amp;</span> <span class="identifier">poly</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">V</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+<span class="identifier">U</span> <span class="identifier">evaluate_even_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">*</span> <span class="identifier">poly</span><span class="special">,</span> <span class="identifier">U</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">count</span><span class="special">);</span>
+
+<span class="comment">// Odd polynomials
+</span><span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_odd_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">(&amp;</span><span class="identifier">a</span><span class="special">)[</span><span class="identifier">N</span><span class="special">],</span> <span class="keyword">const</span> <span class="identifier">V</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_odd_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">N</span><span class="special">&gt;&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">V</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+<span class="identifier">U</span> <span class="identifier">evaluate_odd_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">*</span> <span class="identifier">poly</span><span class="special">,</span> <span class="identifier">U</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">count</span><span class="special">);</span>
+
+<span class="comment">// Rational Functions:
+</span><span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_rational</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">(&amp;</span><span class="identifier">a</span><span class="special">)[</span><span class="identifier">N</span><span class="special">],</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">(&amp;</span><span class="identifier">b</span><span class="special">)[</span><span class="identifier">N</span><span class="special">],</span> <span class="keyword">const</span> <span class="identifier">V</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_rational</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">N</span><span class="special">&gt;&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">N</span><span class="special">&gt;&amp;</span> <span class="identifier">b</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">V</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">);</spa
n>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_rational</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">*</span> <span class="identifier">num</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">U</span><span class="special">*</span> <span class="identifier">denom</span><span class="special">,</span> <span class="identifier">V</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">count</span><span class="special">);</span>
+</pre>
+<a name="math_toolkit.toolkit.internals1.rational.description"></a><h5>
+<a name="id703965"></a>
+ Description
+ </h5>
+<p>
+ Each of the functions come in three variants: a pair of overloaded functions
+ where the order of the polynomial or rational function is evaluated at
+ compile time, and an overload that accepts a runtime variable for the size
+ of the coefficient array. Generally speaking, compile time evaluation of
+ the array size results in better type safety, is less prone to programmer
+ errors, and may result in better optimised code. The polynomial evaluation
+ functions in particular, are specialised for various array sizes, allowing
+ for loop unrolling, and one hopes, optimal inline expansion.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">(&amp;</span><span class="identifier">poly</span><span class="special">)[</span><span class="identifier">N</span><span class="special">],</span> <span class="keyword">const</span> <span class="identifier">V</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">N</span><span class="special">&gt;&amp;</span> <span class="identifier">poly</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">V</span><span class="special">&amp;</span> <span class="identifier">val</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+<span class="identifier">U</span> <span class="identifier">evaluate_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">*</span> <span class="identifier">poly</span><span class="special">,</span> <span class="identifier">U</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">count</span><span class="special">);</span>
+</pre>
+<p>
+ Evaluates the polynomial
+ described by the coefficients stored in <span class="emphasis"><em>poly</em></span>.
+ </p>
+<p>
+ If the size of the array is specified at runtime, then the polynomial most
+ have order <span class="emphasis"><em>count-1</em></span> with <span class="emphasis"><em>count</em></span>
+ coefficients. Otherwise it has order <span class="emphasis"><em>N-1</em></span> with <span class="emphasis"><em>N</em></span>
+ coefficients.
+ </p>
+<p>
+ Coefficients should be stored such that the coefficients for the x<sup>i </sup> terms
+ are in poly[i].
+ </p>
+<p>
+ The types of the coefficients and of variable <span class="emphasis"><em>z</em></span> may
+ differ as long as <span class="emphasis"><em>*poly</em></span> is convertible to type <span class="emphasis"><em>U</em></span>.
+ This allows, for example, for the coefficient table to be a table of integers
+ if this is appropriate.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_even_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">(&amp;</span><span class="identifier">poly</span><span class="special">)[</span><span class="identifier">N</span><span class="special">],</span> <span class="keyword">const</span> <span class="identifier">V</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_even_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">N</span><span class="special">&gt;&amp;</span> <span class="identifier">poly</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">V</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+<span class="identifier">U</span> <span class="identifier">evaluate_even_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">*</span> <span class="identifier">poly</span><span class="special">,</span> <span class="identifier">U</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">count</span><span class="special">);</span>
+</pre>
+<p>
+ As above, but evaluates an even polynomial: one where all the powers of
+ <span class="emphasis"><em>z</em></span> are even numbers. Equivalent to calling <code class="computeroutput"><span class="identifier">evaluate_polynomial</span><span class="special">(</span><span class="identifier">poly</span><span class="special">,</span> <span class="identifier">z</span><span class="special">*</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">count</span><span class="special">)</span></code>.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_odd_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">(&amp;</span><span class="identifier">a</span><span class="special">)[</span><span class="identifier">N</span><span class="special">],</span> <span class="keyword">const</span> <span class="identifier">V</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_odd_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">N</span><span class="special">&gt;&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">V</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+<span class="identifier">U</span> <span class="identifier">evaluate_odd_polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">*</span> <span class="identifier">poly</span><span class="special">,</span> <span class="identifier">U</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">count</span><span class="special">);</span>
+</pre>
+<p>
+ As above but evaluates a polynomial where all the powers are odd numbers.
+ Equivalent to <code class="computeroutput"><span class="identifier">evaluate_polynomial</span><span class="special">(</span><span class="identifier">poly</span><span class="special">+</span><span class="number">1</span><span class="special">,</span>
+ <span class="identifier">z</span><span class="special">*</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">count</span><span class="special">-</span><span class="number">1</span><span class="special">)</span>
+ <span class="special">*</span> <span class="identifier">z</span>
+ <span class="special">+</span> <span class="identifier">poly</span><span class="special">[</span><span class="number">0</span><span class="special">]</span></code>.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_rational</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">(&amp;</span><span class="identifier">num</span><span class="special">)[</span><span class="identifier">N</span><span class="special">],</span> <span class="keyword">const</span> <span class="identifier">U</span><span class="special">(&amp;</span><span class="identifier">denom</span><span class="special">)[</span><span class="identifier">N</span><span class="special">],</span> <span class="keyword">const</span> <span class="identifier">V</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">N</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_rational</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">N</span><span class="special">&gt;&amp;</span> <span class="identifier">num</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">U</span><span class="special">,</span><span class="identifier">N</span><span class="special">&gt;&amp;</span> <span class="identifier">denom</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">V</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">)
;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">V</span><span class="special">&gt;</span>
+<span class="identifier">V</span> <span class="identifier">evaluate_rational</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">*</span> <span class="identifier">num</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">U</span><span class="special">*</span> <span class="identifier">denom</span><span class="special">,</span> <span class="identifier">V</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">count</span><span class="special">);</span>
+</pre>
+<p>
+ Evaluates the rational function (the ratio of two polynomials) described
+ by the coefficients stored in <span class="emphasis"><em>num</em></span> and <span class="emphasis"><em>demom</em></span>.
+ </p>
+<p>
+ If the size of the array is specified at runtime then both polynomials
+ most have order <span class="emphasis"><em>count-1</em></span> with <span class="emphasis"><em>count</em></span>
+ coefficients. Otherwise both polynomials have order <span class="emphasis"><em>N-1</em></span>
+ with <span class="emphasis"><em>N</em></span> coefficients.
+ </p>
+<p>
+ Array <span class="emphasis"><em>num</em></span> describes the numerator, and <span class="emphasis"><em>demon</em></span>
+ the denominator.
+ </p>
+<p>
+ Coefficients should be stored such that the coefficients for the x<sup>i </sup> terms
+ are in num[i] and denom[i].
+ </p>
+<p>
+ The types of the coefficients and of variable <span class="emphasis"><em>v</em></span> may
+ differ as long as <span class="emphasis"><em>*num</em></span> and <span class="emphasis"><em>*denom</em></span>
+ are convertible to type <span class="emphasis"><em>V</em></span>. This allows, for example,
+ for one or both of the coefficient tables to be a table of integers if
+ this is appropriate.
+ </p>
+<p>
+ These functions are designed to safely evaluate the result, even when the
+ value <span class="emphasis"><em>z</em></span> is very large. As such they do not take advantage
+ of compile time array sizes to make any optimisations. These functions
+ are best reserved for situations where <span class="emphasis"><em>z</em></span> may be large:
+ if you can be sure that numerical overflow will not occur then polynomial
+ evaluation with compile-time array sizes may offer slightly better performance.
+ </p>
+<a name="math_toolkit.toolkit.internals1.rational.implementation"></a><h5>
+<a name="id706434"></a>
+ Implementation
+ </h5>
+<p>
+ Polynomials are evaluated by <a href="http://en.wikipedia.org/wiki/Horner_algorithm" target="_top">Horners
+ method</a>. If the array size is known at compile time then the functions
+ dispatch to size-specific implementations that unroll the evaluation loop.
+ </p>
+<p>
+ Rational evaluation is by <a href="http://en.wikipedia.org/wiki/Horner_algorithm" target="_top">Horners
+ method</a>: with the two polynomials being evaluated in parallel to
+ make the most of the processors floating-point pipeline. If <span class="emphasis"><em>v</em></span>
+ is greater than one, then the polynomials are evaluated in reverse order
+ as polynomials in <span class="emphasis"><em>1/v</em></span>: this avoids unnecessary numerical
+ overflow when the coefficients are large.
+ </p>
+<p>
+ Both the polynomial and rational function evaluation algorithms can be
+ tuned using various configuration macros to provide optimal performance
+ for a particular combination of compiler and platform. This includes support
+ for second-order Horner's methods. The various options are <a href="../../perf/tuning.html" title="Performance Tuning Macros">documented
+ here</a>. However, the performance benefits to be gained from these
+ are marginal on most current hardware, consequently it's best to run the
+ performance test application
+ before changing the default settings.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="cf.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals1.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="roots.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/roots.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/roots.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,386 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Root Finding With Derivatives</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../internals1.html" title="Reused Utilities">
+<link rel="prev" href="rational.html" title="Polynomial and Rational Function Evaluation">
+<link rel="next" href="roots2.html" title="Root Finding Without Derivatives">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="rational.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals1.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="roots2.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.toolkit.internals1.roots"></a><a href="roots.html" title="Root Finding With Derivatives"> Root Finding
+ With Derivatives</a>
+</h4></div></div></div>
+<a name="math_toolkit.toolkit.internals1.roots.synopsis"></a><h5>
+<a name="id706552"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">roots</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">tools</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">newton_raphson_iterate</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">guess</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">min</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">max</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">digits</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">newton_raphson_iterate</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">guess</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">min</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">max</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">digits</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">halley_iterate</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">guess</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">min</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">max</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">digits</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">halley_iterate</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">guess</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">min</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">max</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">digits</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">schroeder_iterate</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">guess</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">min</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">max</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">digits</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">schroeder_iterate</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">guess</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">min</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">max</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">digits</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">);</span>
+
+<span class="special">}}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.toolkit.internals1.roots.description"></a><h5>
+<a name="id707710"></a>
+ Description
+ </h5>
+<p>
+ These functions all perform iterative root finding: <code class="computeroutput"><span class="identifier">newton_raphson_iterate</span></code>
+ performs second order Newton Raphson iteration,
+ while <code class="computeroutput"><span class="identifier">halley_iterate</span></code> and
+ <code class="computeroutput"><span class="identifier">schroeder_iterate</span></code> perform
+ third order Halley and Schroeder
+ iteration respectively.
+ </p>
+<p>
+ The functions all take the same parameters:
+ </p>
+<div class="variablelist">
+<p class="title"><b>Parameters of the root finding functions</b></p>
+<dl>
+<dt><span class="term">F
+ f</span></dt>
+<dd>
+<p>
+ Type F must be a callable function object that accepts one parameter
+ and returns a tuple:
+ </p>
+<p>
+ For the second order iterative methods (Newton Raphson) the tuple should
+ have two elements containing the evaluation of the function and it's
+ first derivative.
+ </p>
+<p>
+ For the third order methods (Halley and Schroeder) the tuple should
+ have three elements containing the evaluation of the function and its
+ first and second derivatives.
+ </p>
+</dd>
+<dt><span class="term">T guess</span></dt>
+<dd><p>
+ The initial starting value.
+ </p></dd>
+<dt><span class="term">T min</span></dt>
+<dd><p>
+ The minimum possible value for the result, this is used as an initial
+ lower bracket.
+ </p></dd>
+<dt><span class="term">T max</span></dt>
+<dd><p>
+ The maximum possible value for the result, this is used as an initial
+ upper bracket.
+ </p></dd>
+<dt><span class="term">int digits</span></dt>
+<dd><p>
+ The desired number of binary digits.
+ </p></dd>
+<dt><span class="term">uintmax_t max_iter</span></dt>
+<dd><p>
+ An optional maximum number of iterations to perform.
+ </p></dd>
+</dl>
+</div>
+<p>
+ When using these functions you should note that:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ They may be very sensitive to the initial guess, typically they converge
+ very rapidly if the initial guess has two or three decimal digits correct.
+ However convergence can be no better than bisection, or in some rare
+ cases even worse than bisection if the initial guess is a long way from
+ the correct value and the derivatives are close to zero.
+ </li>
+<li>
+ These functions include special cases to handle zero first (and second
+ where appropriate) derivatives, and fall back to bisection in this case.
+ However, it is helpful if F is defined to return an arbitrarily small
+ value <span class="emphasis"><em>of the correct sign</em></span> rather than zero.
+ </li>
+<li>
+ If the derivative at the current best guess for the result is infinite
+ (or very close to being infinite) then these functions may terminate
+ prematurely. A large first derivative leads to a very small next step,
+ triggering the termination condition. Derivative based iteration may
+ not be appropriate in such cases.
+ </li>
+<li>
+ These functions fall back to bisection if the next computed step would
+ take the next value out of bounds. The bounds are updated after each
+ step to ensure this leads to convergence. However, a good initial guess
+ backed up by asymptotically-tight bounds will improve performance no
+ end rather than relying on bisection.
+ </li>
+<li>
+ The value of <span class="emphasis"><em>digits</em></span> is crucial to good performance
+ of these functions, if it is set too high then at best you will get one
+ extra (unnecessary) iteration, and at worst the last few steps will proceed
+ by bisection. Remember that the returned value can never be more accurate
+ than f(x) can be evaluated, and that if f(x) suffers from cancellation
+ errors as it tends to zero then the computed steps will be effectively
+ random. The value of <span class="emphasis"><em>digits</em></span> should be set so that
+ iteration terminates before this point: remember that for second and
+ third order methods the number of correct digits in the result is increasing
+ quite substantially with each iteration, <span class="emphasis"><em>digits</em></span>
+ should be set by experiment so that the final iteration just takes the
+ next value into the zone where f(x) becomes inaccurate.
+ </li>
+<li>
+ Finally: you may well be able to do better than these functions by hand-coding
+ the heuristics used so that they are tailored to a specific function.
+ You may also be able to compute the ratio of derivatives used by these
+ methods more efficiently than computing the derivatives themselves. As
+ ever, algebraic simplification can be a big win.
+ </li>
+</ul></div>
+<a name="newton"></a><p>
+ </p>
+<a name="math_toolkit.toolkit.internals1.roots.newton_raphson_method"></a><h5>
+<a name="id708030"></a>
+ <a href="roots.html#math_toolkit.toolkit.internals1.roots.newton_raphson_method">Newton
+ Raphson Method</a>
+ </h5>
+<p>
+ Given an initial guess x0 the subsequent values are computed using:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/roots1.png"></span>
+ </p>
+<p>
+ Out of bounds steps revert to bisection of the current bounds.
+ </p>
+<p>
+ Under ideal conditions, the number of correct digits doubles with each
+ iteration.
+ </p>
+<a name="halley"></a><p>
+ </p>
+<a name="math_toolkit.toolkit.internals1.roots.halley_s_method"></a><h5>
+<a name="id708112"></a>
+ <a href="roots.html#math_toolkit.toolkit.internals1.roots.halley_s_method">Halley's
+ Method</a>
+ </h5>
+<p>
+ Given an initial guess x0 the subsequent values are computed using:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/roots2.png"></span>
+ </p>
+<p>
+ Over-compensation by the second derivative (one which would proceed in
+ the wrong direction) causes the method to revert to a Newton-Raphson step.
+ </p>
+<p>
+ Out of bounds steps revert to bisection of the current bounds.
+ </p>
+<p>
+ Under ideal conditions, the number of correct digits trebles with each
+ iteration.
+ </p>
+<a name="schroeder"></a><p>
+ </p>
+<a name="math_toolkit.toolkit.internals1.roots.schroeder_s_method"></a><h5>
+<a name="id708199"></a>
+ <a href="roots.html#math_toolkit.toolkit.internals1.roots.schroeder_s_method">Schroeder's
+ Method</a>
+ </h5>
+<p>
+ Given an initial guess x0 the subsequent values are computed using:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/roots3.png"></span>
+ </p>
+<p>
+ Over-compensation by the second derivative (one which would proceed in
+ the wrong direction) causes the method to revert to a Newton-Raphson step.
+ Likewise a Newton step is used whenever that Newton step would change the
+ next value by more than 10%.
+ </p>
+<p>
+ Out of bounds steps revert to bisection of the current bounds.
+ </p>
+<p>
+ Under ideal conditions, the number of correct digits trebles with each
+ iteration.
+ </p>
+<a name="math_toolkit.toolkit.internals1.roots.example"></a><h5>
+<a name="id708279"></a>
+ Example
+ </h5>
+<p>
+ Lets suppose we want to find the cube root of a number, the equation we
+ want to solve along with its derivatives are:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/roots4.png"></span>
+ </p>
+<p>
+ To begin with lets solve the problem using Newton Raphson iterations, we'll
+ begin be defining a function object that returns the evaluation of the
+ function to solve, along with its first derivative:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">cbrt_functor</span>
+<span class="special">{</span>
+ <span class="identifier">cbrt_functor</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">target</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">a</span><span class="special">(</span><span class="identifier">target</span><span class="special">){}</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">tr1</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="identifier">T</span> <span class="identifier">sqr</span> <span class="special">=</span> <span class="identifier">z</span> <span class="special">*</span> <span class="identifier">z</span><span class="special">;</span>
+ <span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">tr1</span><span class="special">::</span><span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">sqr</span> <span class="special">*</span> <span class="identifier">z</span> <span class="special">-</span> <span class="identifier">a</span><span class="special">,</span> <span class="number">3</span> <span class="special">*</span> <span class="identifier">sqr</span><span class="special">);</span>
+ <span class="special">}</span>
+<span class="keyword">private</span><span class="special">:</span>
+ <span class="identifier">T</span> <span class="identifier">a</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ Implementing the cube root is fairly trivial now, the hardest part is finding
+ a good approximation to begin with: in this case we'll just divide the
+ exponent by three:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">cbrt</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">std</span><span class="special">;</span>
+ <span class="keyword">int</span> <span class="identifier">exp</span><span class="special">;</span>
+ <span class="identifier">frexp</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">exp</span><span class="special">);</span>
+ <span class="identifier">T</span> <span class="identifier">min</span> <span class="special">=</span> <span class="identifier">ldexp</span><span class="special">(</span><span class="number">0.5</span><span class="special">,</span> <span class="identifier">exp</span><span class="special">/</span><span class="number">3</span><span class="special">);</span>
+ <span class="identifier">T</span> <span class="identifier">max</span> <span class="special">=</span> <span class="identifier">ldexp</span><span class="special">(</span><span class="number">2.0</span><span class="special">,</span> <span class="identifier">exp</span><span class="special">/</span><span class="number">3</span><span class="special">);</span>
+ <span class="identifier">T</span> <span class="identifier">guess</span> <span class="special">=</span> <span class="identifier">ldexp</span><span class="special">(</span><span class="number">1.0</span><span class="special">,</span> <span class="identifier">exp</span><span class="special">/</span><span class="number">3</span><span class="special">);</span>
+ <span class="keyword">int</span> <span class="identifier">digits</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">digits</span><span class="special">;</span>
+ <span class="keyword">return</span> <span class="identifier">tools</span><span class="special">::</span><span class="identifier">newton_raphson_iterate</span><span class="special">(</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">cbrt_functor</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</span><span class="identifier">z</span><span class="special">),</span> <span class="identifier">guess</span><span class="special">,</span> <span class="identifier">min</span><span class="special">,</span> <span class="identifier">max</span><span class="special">,</span> <span class="identifier">digits</span><span class="special">);</span>
+<span class="special">}</span>
+</pre>
+<p>
+ Using the test data in libs/math/test/cbrt_test.cpp this found the cube
+ root exact to the last digit in every case, and in no more than 6 iterations
+ at double precision. However, you will note that a high precision was used
+ in this example, exactly what was warned against earlier on in these docs!
+ In this particular case its possible to compute f(x) exactly and without
+ undue cancellation error, so a high limit is not too much of an issue.
+ However, reducing the limit to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">digits</span>
+ <span class="special">*</span> <span class="number">2</span> <span class="special">/</span> <span class="number">3</span></code> gave
+ full precision in all but one of the test cases (and that one was out by
+ just one bit). The maximum number of iterations remained 6, but in most
+ cases was reduced by one.
+ </p>
+<p>
+ Note also that the above code omits error handling, and does not handle
+ negative values of z correctly. That will be left as an exercise for the
+ reader!
+ </p>
+<p>
+ Now lets adapt the functor slightly to return the second derivative as
+ well:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">cbrt_functor</span>
+<span class="special">{</span>
+ <span class="identifier">cbrt_functor</span><span class="special">(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">target</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">a</span><span class="special">(</span><span class="identifier">target</span><span class="special">){}</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">tr1</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="identifier">T</span> <span class="identifier">sqr</span> <span class="special">=</span> <span class="identifier">z</span> <span class="special">*</span> <span class="identifier">z</span><span class="special">;</span>
+ <span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">tr1</span><span class="special">::</span><span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">sqr</span> <span class="special">*</span> <span class="identifier">z</span> <span class="special">-</span> <span class="identifier">a</span><span class="special">,</span> <span class="number">3</span> <span class="special">*</span> <span class="identifier">sqr</span><span class="special">,</span> <span class="number">6</span> <span class="special">*</span> <span class="identifier">z</span><span class="special">);</span>
+ <span class="special">}</span>
+<span class="keyword">private</span><span class="special">:</span>
+ <span class="identifier">T</span> <span class="identifier">a</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ And then adapt the <code class="computeroutput"><span class="identifier">cbrt</span></code>
+ function to use Halley iterations:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">cbrt</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">z</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">std</span><span class="special">;</span>
+ <span class="keyword">int</span> <span class="identifier">exp</span><span class="special">;</span>
+ <span class="identifier">frexp</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">exp</span><span class="special">);</span>
+ <span class="identifier">T</span> <span class="identifier">min</span> <span class="special">=</span> <span class="identifier">ldexp</span><span class="special">(</span><span class="number">0.5</span><span class="special">,</span> <span class="identifier">exp</span><span class="special">/</span><span class="number">3</span><span class="special">);</span>
+ <span class="identifier">T</span> <span class="identifier">max</span> <span class="special">=</span> <span class="identifier">ldexp</span><span class="special">(</span><span class="number">2.0</span><span class="special">,</span> <span class="identifier">exp</span><span class="special">/</span><span class="number">3</span><span class="special">);</span>
+ <span class="identifier">T</span> <span class="identifier">guess</span> <span class="special">=</span> <span class="identifier">ldexp</span><span class="special">(</span><span class="number">1.0</span><span class="special">,</span> <span class="identifier">exp</span><span class="special">/</span><span class="number">3</span><span class="special">);</span>
+ <span class="keyword">int</span> <span class="identifier">digits</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">digits</span> <span class="special">/</span> <span class="number">2</span><span class="special">;</span>
+ <span class="keyword">return</span> <span class="identifier">tools</span><span class="special">::</span><span class="identifier">halley_iterate</span><span class="special">(</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">cbrt_functor</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</span><span class="identifier">z</span><span class="special">),</span> <span class="identifier">guess</span><span class="special">,</span> <span class="identifier">min</span><span class="special">,</span> <span class="identifier">max</span><span class="special">,</span> <span class="identifier">digits</span><span class="special">);</span>
+<span class="special">}</span>
+</pre>
+<p>
+ Note that the iterations are set to stop at just one-half of full precision,
+ and yet even so not one of the test cases had a single bit wrong. What's
+ more, the maximum number of iterations was now just 4.
+ </p>
+<p>
+ Just to complete the picture, we could have called <code class="computeroutput"><span class="identifier">schroeder_iterate</span></code>
+ in the last example: and in fact it makes no difference to the accuracy
+ or number of iterations in this particular case. However, the relative
+ performance of these two methods may vary depending upon the nature of
+ f(x), and the accuracy to which the initial guess can be computed. There
+ appear to be no generalisations that can be made except "try them
+ and see".
+ </p>
+<p>
+ Finally, had we called cbrt with NTL::RR
+ set to 1000 bit precision, then full precision can be obtained with just
+ 7 iterations. To put that in perspective an increase in precision by a
+ factor of 20, has less than doubled the number of iterations. That just
+ goes to emphasise that most of the iterations are used up getting the first
+ few digits correct: after that these methods can churn out further digits
+ with remarkable efficiency. Or to put it another way: <span class="emphasis"><em>nothing
+ beats a really good initial guess!</em></span>
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="rational.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals1.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="roots2.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/roots2.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/roots2.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,606 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Root Finding Without Derivatives</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../internals1.html" title="Reused Utilities">
+<link rel="prev" href="roots.html" title="Root Finding With Derivatives">
+<link rel="next" href="minima.html" title="Locating Function Minima">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="roots.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals1.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="minima.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.toolkit.internals1.roots2"></a><a href="roots2.html" title="Root Finding Without Derivatives"> Root Finding
+ Without Derivatives</a>
+</h4></div></div></div>
+<a name="math_toolkit.toolkit.internals1.roots2.synopsis"></a><h5>
+<a name="id710400"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">roots</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">tools</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">bisect</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="identifier">T</span> <span class="identifier">min</span><span class="special">,</span>
+ <span class="identifier">T</span> <span class="identifier">max</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">bisect</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="identifier">T</span> <span class="identifier">min</span><span class="special">,</span>
+ <span class="identifier">T</span> <span class="identifier">max</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">bisect</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="identifier">T</span> <span class="identifier">min</span><span class="special">,</span>
+ <span class="identifier">T</span> <span class="identifier">max</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">,</span>
+ <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">bracket_and_solve_root</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">guess</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">factor</span><span class="special">,</span>
+ <span class="keyword">bool</span> <span class="identifier">rising</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">bracket_and_solve_root</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">guess</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">factor</span><span class="special">,</span>
+ <span class="keyword">bool</span> <span class="identifier">rising</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">,</span>
+ <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">toms748_solve</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">toms748_solve</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">,</span>
+ <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">toms748_solve</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">fa</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">fb</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">toms748_solve</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">fa</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">fb</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">,</span>
+ <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="comment">// Termination conditions:
+</span><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">eps_tolerance</span><span class="special">;</span>
+
+<span class="keyword">struct</span> <span class="identifier">equal_floor</span><span class="special">;</span>
+<span class="keyword">struct</span> <span class="identifier">equal_ceil</span><span class="special">;</span>
+<span class="keyword">struct</span> <span class="identifier">equal_nearest_integer</span><span class="special">;</span>
+
+<span class="special">}}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.toolkit.internals1.roots2.description"></a><h5>
+<a name="id713044"></a>
+ Description
+ </h5>
+<p>
+ These functions solve the root of some function <span class="emphasis"><em>f(x)</em></span>
+ without the need for the derivatives of <span class="emphasis"><em>f(x)</em></span>. The
+ functions here that use TOMS Algorithm 748 are asymptotically the most
+ efficient known, and have been shown to be optimal for a certain classes
+ of smooth functions.
+ </p>
+<p>
+ Alternatively, there is a simple bisection routine which can be useful
+ in its own right in some situations, or alternatively for narrowing down
+ the range containing the root, prior to calling a more advanced algorithm.
+ </p>
+<p>
+ All the algorithms in this section reduce the diameter of the enclosing
+ interval with the same asymptotic efficiency with which they locate the
+ root. This is in contrast to the derivative based methods which may <span class="emphasis"><em>never</em></span>
+ significantly reduce the enclosing interval, even though they rapidly approach
+ the root. This is also in contrast to some other derivative-free methods
+ (for example the methods of <a href="http://en.wikipedia.org/wiki/Brent%27s_method" target="_top">Brent
+ or Dekker)</a> which only reduce the enclosing interval on the final
+ step. Therefore these methods return a std::pair containing the enclosing
+ interval found, and accept a function object specifying the termination
+ condition. Three function objects are provided for ready-made termination
+ conditions: <span class="emphasis"><em>eps_tolerance</em></span> causes termination when
+ the relative error in the enclosing interval is below a certain threshold,
+ while <span class="emphasis"><em>equal_floor</em></span> and <span class="emphasis"><em>equal_ceil</em></span>
+ are useful for certain statistical applications where the result is known
+ to be an integer. Other user-defined termination conditions are likely
+ to be used only rarely, but may be useful in some specific circumstances.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">bisect</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="identifier">T</span> <span class="identifier">min</span><span class="special">,</span>
+ <span class="identifier">T</span> <span class="identifier">max</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">bisect</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="identifier">T</span> <span class="identifier">min</span><span class="special">,</span>
+ <span class="identifier">T</span> <span class="identifier">max</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">bisect</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="identifier">T</span> <span class="identifier">min</span><span class="special">,</span>
+ <span class="identifier">T</span> <span class="identifier">max</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">,</span>
+ <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ These functions locate the root using bisection, function arguments are:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">f</span></dt>
+<dd><p>
+ A unary functor which is the function whose root is to be found.
+ </p></dd>
+<dt><span class="term">min</span></dt>
+<dd><p>
+ The left bracket of the interval known to contain the root.
+ </p></dd>
+<dt><span class="term">max</span></dt>
+<dd><p>
+ The right bracket of the interval known to contain the root. It is
+ a precondition that <span class="emphasis"><em>min &lt; max</em></span> and <span class="emphasis"><em>f(min)*f(max)
+ &lt;= 0</em></span>, the function signals evaluation error if these
+ preconditions are violated. The action taken is controlled by the evaluation
+ error policy. A best guess may be returned, perhaps significantly wrong.
+ </p></dd>
+<dt><span class="term">tol</span></dt>
+<dd><p>
+ A binary functor that specifies the termination condition: the function
+ will return the current brackets enclosing the root when <span class="emphasis"><em>tol(min,max)</em></span>
+ becomes true.
+ </p></dd>
+<dt><span class="term">max_iter</span></dt>
+<dd><p>
+ The maximum number of invocations of <span class="emphasis"><em>f(x)</em></span> to make
+ while searching for the root.
+ </p></dd>
+</dl>
+</div>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ Returns: a pair of values <span class="emphasis"><em>r</em></span> that bracket the root
+ so that:
+ </p>
+<pre class="programlisting">
+<span class="identifier">f</span><span class="special">(</span><span class="identifier">r</span><span class="special">.</span><span class="identifier">first</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">r</span><span class="special">.</span><span class="identifier">second</span><span class="special">)</span> <span class="special">&lt;=</span> <span class="number">0</span>
+</pre>
+<p>
+ and either
+ </p>
+<pre class="programlisting">
+<span class="identifier">tol</span><span class="special">(</span><span class="identifier">r</span><span class="special">.</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">r</span><span class="special">.</span><span class="identifier">second</span><span class="special">)</span> <span class="special">==</span> <span class="keyword">true</span>
+</pre>
+<p>
+ or
+ </p>
+<pre class="programlisting">
+<span class="identifier">max_iter</span> <span class="special">&gt;=</span> <span class="identifier">m</span>
+</pre>
+<p>
+ where <span class="emphasis"><em>m</em></span> is the initial value of <span class="emphasis"><em>max_iter</em></span>
+ passed to the function.
+ </p>
+<p>
+ In other words, it's up to the caller to verify whether termination occurred
+ as a result of exceeding <span class="emphasis"><em>max_iter</em></span> function invocations
+ (easily done by checking the value of <span class="emphasis"><em>max_iter</em></span> when
+ the function returns), rather than because the termination condition <span class="emphasis"><em>tol</em></span>
+ was satisfied.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">bracket_and_solve_root</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">guess</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">factor</span><span class="special">,</span>
+ <span class="keyword">bool</span> <span class="identifier">rising</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">bracket_and_solve_root</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">guess</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">factor</span><span class="special">,</span>
+ <span class="keyword">bool</span> <span class="identifier">rising</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">,</span>
+ <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ This is a convenience function that calls <span class="emphasis"><em>toms748_solve</em></span>
+ internally to find the root of <span class="emphasis"><em>f(x)</em></span>. It's usable only
+ when <span class="emphasis"><em>f(x)</em></span> is a monotonic function, and the location
+ of the root is known approximately, and in particular it is known whether
+ the root is occurs for positive or negative <span class="emphasis"><em>x</em></span>. The
+ parameters are:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">f</span></dt>
+<dd><p>
+ A unary functor that is the function whose root is to be solved. f(x)
+ must be uniformly increasing or decreasing on <span class="emphasis"><em>x</em></span>.
+ </p></dd>
+<dt><span class="term">guess</span></dt>
+<dd><p>
+ An initial approximation to the root
+ </p></dd>
+<dt><span class="term">factor</span></dt>
+<dd><p>
+ A scaling factor that is used to bracket the root: the value <span class="emphasis"><em>guess</em></span>
+ is multiplied (or divided as appropriate) by <span class="emphasis"><em>factor</em></span>
+ until two values are found that bracket the root. A value such as 2
+ is a typical choice for <span class="emphasis"><em>factor</em></span>.
+ </p></dd>
+<dt><span class="term">rising</span></dt>
+<dd><p>
+ Set to <span class="emphasis"><em>true</em></span> if <span class="emphasis"><em>f(x)</em></span> is rising
+ on <span class="emphasis"><em>x</em></span> and <span class="emphasis"><em>false</em></span> if <span class="emphasis"><em>f(x)</em></span>
+ is falling on <span class="emphasis"><em>x</em></span>. This value is used along with
+ the result of <span class="emphasis"><em>f(guess)</em></span> to determine if <span class="emphasis"><em>guess</em></span>
+ is above or below the root.
+ </p></dd>
+<dt><span class="term">tol</span></dt>
+<dd><p>
+ A binary functor that determines the termination condition for the
+ search for the root. <span class="emphasis"><em>tol</em></span> is passed the current
+ brackets at each step, when it returns true then the current brackets
+ are returned as the result.
+ </p></dd>
+<dt><span class="term">max_iter</span></dt>
+<dd><p>
+ The maximum number of function invocations to perform in the search
+ for the root.
+ </p></dd>
+</dl>
+</div>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ Returns: a pair of values <span class="emphasis"><em>r</em></span> that bracket the root
+ so that:
+ </p>
+<pre class="programlisting">
+<span class="identifier">f</span><span class="special">(</span><span class="identifier">r</span><span class="special">.</span><span class="identifier">first</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">r</span><span class="special">.</span><span class="identifier">second</span><span class="special">)</span> <span class="special">&lt;=</span> <span class="number">0</span>
+</pre>
+<p>
+ and either
+ </p>
+<pre class="programlisting">
+<span class="identifier">tol</span><span class="special">(</span><span class="identifier">r</span><span class="special">.</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">r</span><span class="special">.</span><span class="identifier">second</span><span class="special">)</span> <span class="special">==</span> <span class="keyword">true</span>
+</pre>
+<p>
+ or
+ </p>
+<pre class="programlisting">
+<span class="identifier">max_iter</span> <span class="special">&gt;=</span> <span class="identifier">m</span>
+</pre>
+<p>
+ where <span class="emphasis"><em>m</em></span> is the initial value of <span class="emphasis"><em>max_iter</em></span>
+ passed to the function.
+ </p>
+<p>
+ In other words, it's up to the caller to verify whether termination occurred
+ as a result of exceeding <span class="emphasis"><em>max_iter</em></span> function invocations
+ (easily done by checking the value of <span class="emphasis"><em>max_iter</em></span> when
+ the function returns), rather than because the termination condition <span class="emphasis"><em>tol</em></span>
+ was satisfied.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">toms748_solve</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">toms748_solve</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">,</span>
+ <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">toms748_solve</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">fa</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">fb</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Tol</span><span class="special">,</span> <span class="keyword">class</span> Policy<span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span>
+ <span class="identifier">toms748_solve</span><span class="special">(</span>
+ <span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">fa</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">fb</span><span class="special">,</span>
+ <span class="identifier">Tol</span> <span class="identifier">tol</span><span class="special">,</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_iter</span><span class="special">,</span>
+ <span class="keyword">const</span> Policy<span class="special">&amp;);</span>
+</pre>
+<p>
+ These two functions implement TOMS Algorithm 748: it uses a mixture of
+ cubic, quadratic and linear (secant) interpolation to locate the root of
+ <span class="emphasis"><em>f(x)</em></span>. The two functions differ only by whether values
+ for <span class="emphasis"><em>f(a)</em></span> and <span class="emphasis"><em>f(b)</em></span> are already
+ available. The parameters are:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">f</span></dt>
+<dd><p>
+ A unary functor that is the function whose root is to be solved. f(x)
+ need not be uniformly increasing or decreasing on <span class="emphasis"><em>x</em></span>
+ and may have multiple roots.
+ </p></dd>
+<dt><span class="term">a</span></dt>
+<dd><p>
+ The lower bound for the initial bracket of the root.
+ </p></dd>
+<dt><span class="term">b</span></dt>
+<dd><p>
+ The upper bound for the initial bracket of the root. It is a precondition
+ that <span class="emphasis"><em>a &lt; b</em></span> and that <span class="emphasis"><em>a</em></span>
+ and <span class="emphasis"><em>b</em></span> bracket the root to find so that <span class="emphasis"><em>f(a)*f(b)
+ &lt; 0</em></span>.
+ </p></dd>
+<dt><span class="term">fa</span></dt>
+<dd><p>
+ Optional: the value of <span class="emphasis"><em>f(a)</em></span>.
+ </p></dd>
+<dt><span class="term">fb</span></dt>
+<dd><p>
+ Optional: the value of <span class="emphasis"><em>f(b)</em></span>.
+ </p></dd>
+<dt><span class="term">tol</span></dt>
+<dd><p>
+ A binary functor that determines the termination condition for the
+ search for the root. <span class="emphasis"><em>tol</em></span> is passed the current
+ brackets at each step, when it returns true then the current brackets
+ are returned as the result.
+ </p></dd>
+<dt><span class="term">max_iter</span></dt>
+<dd><p>
+ The maximum number of function invocations to perform in the search
+ for the root. On exit <span class="emphasis"><em>max_iter</em></span> is set to actual
+ number of function invocations used.
+ </p></dd>
+</dl>
+</div>
+<p>
+ </p>
+<p>
+ 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
+ policy documentation for more details.
+ </p>
+<p>
+ </p>
+<p>
+ Returns: a pair of values <span class="emphasis"><em>r</em></span> that bracket the root
+ so that:
+ </p>
+<pre class="programlisting">
+<span class="identifier">f</span><span class="special">(</span><span class="identifier">r</span><span class="special">.</span><span class="identifier">first</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">r</span><span class="special">.</span><span class="identifier">second</span><span class="special">)</span> <span class="special">&lt;=</span> <span class="number">0</span>
+</pre>
+<p>
+ and either
+ </p>
+<pre class="programlisting">
+<span class="identifier">tol</span><span class="special">(</span><span class="identifier">r</span><span class="special">.</span><span class="identifier">first</span><span class="special">,</span> <span class="identifier">r</span><span class="special">.</span><span class="identifier">second</span><span class="special">)</span> <span class="special">==</span> <span class="keyword">true</span>
+</pre>
+<p>
+ or
+ </p>
+<pre class="programlisting">
+<span class="identifier">max_iter</span> <span class="special">&gt;=</span> <span class="identifier">m</span>
+</pre>
+<p>
+ where <span class="emphasis"><em>m</em></span> is the initial value of <span class="emphasis"><em>max_iter</em></span>
+ passed to the function.
+ </p>
+<p>
+ In other words, it's up to the caller to verify whether termination occurred
+ as a result of exceeding <span class="emphasis"><em>max_iter</em></span> function invocations
+ (easily done by checking the value of <span class="emphasis"><em>max_iter</em></span>), rather
+ than because the termination condition <span class="emphasis"><em>tol</em></span> was satisfied.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">eps_tolerance</span>
+<span class="special">{</span>
+ <span class="identifier">eps_tolerance</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">bits</span><span class="special">);</span>
+ <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">)</span><span class="keyword">const</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ This is the usual termination condition used with these root finding functions.
+ Its operator() will return true when the relative distance between <span class="emphasis"><em>a</em></span>
+ and <span class="emphasis"><em>b</em></span> is less than twice the machine epsilon for T,
+ or 2<sup>1-bits</sup>, whichever is the larger. In other words you set <span class="emphasis"><em>bits</em></span>
+ to the number of bits of precision you want in the result. The minimal
+ tolerance of twice the machine epsilon of T is required to ensure that
+ we get back a bracketing interval: since this must clearly be at least
+ 1 epsilon in size.
+ </p>
+<pre class="programlisting">
+<span class="keyword">struct</span> <span class="identifier">equal_floor</span>
+<span class="special">{</span>
+ <span class="identifier">equal_floor</span><span class="special">();</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">)</span><span class="keyword">const</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ This termination condition is used when you want to find an integer result
+ that is the <span class="emphasis"><em>floor</em></span> of the true root. It will terminate
+ as soon as both ends of the interval have the same <span class="emphasis"><em>floor</em></span>.
+ </p>
+<pre class="programlisting">
+<span class="keyword">struct</span> <span class="identifier">equal_ceil</span>
+<span class="special">{</span>
+ <span class="identifier">equal_ceil</span><span class="special">();</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">)</span><span class="keyword">const</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ This termination condition is used when you want to find an integer result
+ that is the <span class="emphasis"><em>ceil</em></span> of the true root. It will terminate
+ as soon as both ends of the interval have the same <span class="emphasis"><em>ceil</em></span>.
+ </p>
+<pre class="programlisting">
+<span class="keyword">struct</span> <span class="identifier">equal_nearest_integer</span>
+<span class="special">{</span>
+ <span class="identifier">equal_nearest_integer</span><span class="special">();</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">)</span><span class="keyword">const</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ This termination condition is used when you want to find an integer result
+ that is the <span class="emphasis"><em>closest</em></span> to the true root. It will terminate
+ as soon as both ends of the interval round to the same nearest integer.
+ </p>
+<a name="math_toolkit.toolkit.internals1.roots2.implementation"></a><h5>
+<a name="id717509"></a>
+ Implementation
+ </h5>
+<p>
+ The implementation of the bisection algorithm is extremely straightforward
+ and not detailed here. TOMS algorithm 748 is described in detail in:
+ </p>
+<p>
+ <span class="emphasis"><em>Algorithm 748: Enclosing Zeros of Continuous Functions, G. E.
+ Alefeld, F. A. Potra and Yixun Shi, ACM Transactions on Mathematica1 Software,
+ Vol. 21. No. 3. September 1995. Pages 327-344.</em></span>
+ </p>
+<p>
+ The implementation here is a faithful translation of this paper into C++.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="roots.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals1.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="minima.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/series_evaluation.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals1/series_evaluation.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,190 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Series Evaluation</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../internals1.html" title="Reused Utilities">
+<link rel="prev" href="../internals1.html" title="Reused Utilities">
+<link rel="next" href="cf.html" title="Continued Fraction Evaluation">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../internals1.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals1.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="cf.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.toolkit.internals1.series_evaluation"></a><a href="series_evaluation.html" title="Series Evaluation">
+ Series Evaluation</a>
+</h4></div></div></div>
+<a name="math_toolkit.toolkit.internals1.series_evaluation.synopsis"></a><h5>
+<a name="id697956"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">series</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">tools</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Functor</span><span class="special">&gt;</span>
+<span class="keyword">typename</span> <span class="identifier">Functor</span><span class="special">::</span><span class="identifier">result_type</span> <span class="identifier">sum_series</span><span class="special">(</span><span class="identifier">Functor</span><span class="special">&amp;</span> <span class="identifier">func</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">bits</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Functor</span><span class="special">&gt;</span>
+<span class="keyword">typename</span> <span class="identifier">Functor</span><span class="special">::</span><span class="identifier">result_type</span> <span class="identifier">sum_series</span><span class="special">(</span><span class="identifier">Functor</span><span class="special">&amp;</span> <span class="identifier">func</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">bits</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_terms</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Functor</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+<span class="keyword">typename</span> <span class="identifier">Functor</span><span class="special">::</span><span class="identifier">result_type</span> <span class="identifier">sum_series</span><span class="special">(</span><span class="identifier">Functor</span><span class="special">&amp;</span> <span class="identifier">func</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">bits</span><span class="special">,</span> <span class="identifier">U</span> <span class="identifier">init_value</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Functor</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+<span class="keyword">typename</span> <span class="identifier">Functor</span><span class="special">::</span><span class="identifier">result_type</span> <span class="identifier">sum_series</span><span class="special">(</span><span class="identifier">Functor</span><span class="special">&amp;</span> <span class="identifier">func</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">bits</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_terms</span><span class="special">,</span> <span class="identifier">U</span> <span class="identifier">init_value</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Functor</span><span class="special">&gt;</span>
+<span class="keyword">typename</span> <span class="identifier">Functor</span><span class="special">::</span><span class="identifier">result_type</span> <span class="identifier">kahan_sum_series</span><span class="special">(</span><span class="identifier">Functor</span><span class="special">&amp;</span> <span class="identifier">func</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">bits</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Functor</span><span class="special">&gt;</span>
+<span class="keyword">typename</span> <span class="identifier">Functor</span><span class="special">::</span><span class="identifier">result_type</span> <span class="identifier">kahan_sum_series</span><span class="special">(</span><span class="identifier">Functor</span><span class="special">&amp;</span> <span class="identifier">func</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">bits</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&amp;</span> <span class="identifier">max_terms</span><span class="special">);</span>
+
+<span class="special">}}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.toolkit.internals1.series_evaluation.description"></a><h5>
+<a name="id698908"></a>
+ Description
+ </h5>
+<p>
+ These algorithms are intended for the <a href="http://en.wikipedia.org/wiki/Series_%28mathematics%29" target="_top">summation
+ of infinite series</a>.
+ </p>
+<p>
+ Each of the algorithms takes a nullary-function object as the first argument:
+ the function object will be repeatedly invoked to pull successive terms
+ from the series being summed.
+ </p>
+<p>
+ The second argument is the number of binary bits of precision required,
+ summation will stop when the next term is too small to have any effect
+ on the first <span class="emphasis"><em>bits</em></span> bits of the result.
+ </p>
+<p>
+ The optional third argument <span class="emphasis"><em>max_terms</em></span> sets an upper
+ limit on the number of terms of the series to evaluate. In addition, on
+ exit the function will set <span class="emphasis"><em>max_terms</em></span> to the actual
+ number of terms of the series that were evaluated: this is particularly
+ useful for profiling the convergence properties of a new series.
+ </p>
+<p>
+ The final optional argument <span class="emphasis"><em>init_value</em></span> is the initial
+ value of the sum to which the terms of the series should be added. This
+ is useful in two situations:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Where the first value of the series has a different formula to successive
+ terms. In this case the first value in the series can be passed as the
+ last argument and the logic of the function object can then be simplified
+ to return subsequent terms.
+ </li>
+<li>
+ Where the series is being added (or subtracted) from some other value:
+ termination of the series will likely occur much more rapidly if that
+ other value is passed as the last argument. For example, there are several
+ functions that can be expressed as <span class="emphasis"><em>1 - S(z)</em></span> where
+ S(z) is an infinite series. In this case, pass -1 as the last argument
+ and then negate the result of the summation to get the result of <span class="emphasis"><em>1
+ - S(z)</em></span>.
+ </li>
+</ul></div>
+<p>
+ The two <span class="emphasis"><em>kahan_sum_series</em></span> variants of these algorithms
+ maintain a carry term that corrects for roundoff error during summation.
+ They are inspired by the <a href="http://en.wikipedia.org/wiki/Kahan_Summation_Algorithm" target="_top"><span class="emphasis"><em>Kahan
+ Summation Formula</em></span></a> that appears in <a href="http://docs.sun.com/source/806-3568/ncg_goldberg.html" target="_top">What
+ Every Computer Scientist Should Know About Floating-Point Arithmetic</a>.
+ However, it should be pointed out that there are very few series that require
+ summation in this way.
+ </p>
+<a name="math_toolkit.toolkit.internals1.series_evaluation.example"></a><h5>
+<a name="id699056"></a>
+ Example
+ </h5>
+<p>
+ Let's suppose we want to implement <span class="emphasis"><em>log(1+x)</em></span> via its
+ infinite series,
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/log1pseries.png"></span>
+ </p>
+<p>
+ We begin by writing a small function object to return successive terms
+ of the series:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">log1p_series</span>
+<span class="special">{</span>
+ <span class="comment">// we must define a result_type typedef:
+</span> <span class="keyword">typedef</span> <span class="identifier">T</span> <span class="identifier">result_type</span><span class="special">;</span>
+
+ <span class="identifier">log1p_series</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">)</span>
+ <span class="special">:</span> <span class="identifier">k</span><span class="special">(</span><span class="number">0</span><span class="special">),</span> <span class="identifier">m_mult</span><span class="special">(-</span><span class="identifier">x</span><span class="special">),</span> <span class="identifier">m_prod</span><span class="special">(-</span><span class="number">1</span><span class="special">){}</span>
+
+ <span class="identifier">T</span> <span class="keyword">operator</span><span class="special">()()</span>
+ <span class="special">{</span>
+ <span class="comment">// This is the function operator invoked by the summation
+</span> <span class="comment">// algorithm, the first call to this operator should return
+</span> <span class="comment">// the first term of the series, the second call the second
+</span> <span class="comment">// term and so on.
+</span> <span class="identifier">m_prod</span> <span class="special">*=</span> <span class="identifier">m_mult</span><span class="special">;</span>
+ <span class="keyword">return</span> <span class="identifier">m_prod</span> <span class="special">/</span> <span class="special">++</span><span class="identifier">k</span><span class="special">;</span>
+ <span class="special">}</span>
+
+<span class="keyword">private</span><span class="special">:</span>
+ <span class="keyword">int</span> <span class="identifier">k</span><span class="special">;</span>
+ <span class="keyword">const</span> <span class="identifier">T</span> <span class="identifier">m_mult</span><span class="special">;</span>
+ <span class="identifier">T</span> <span class="identifier">m_prod</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ Implementing log(1+x) is now fairly trivial:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">log1p</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">)</span>
+<span class="special">{</span>
+ <span class="comment">// We really should add some error checking on x here!
+</span> <span class="identifier">assert</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">fabs</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">&lt;</span> <span class="number">1</span><span class="special">);</span>
+
+ <span class="comment">// construct the series functor:
+</span> <span class="identifier">log1p_series</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">s</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span>
+ <span class="comment">// and add it up, with enough digits for full machine precision
+</span> <span class="comment">// plus a couple more for luck.... !
+</span> <span class="keyword">return</span> <span class="identifier">tools</span><span class="special">::</span><span class="identifier">sum_series</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="identifier">tools</span><span class="special">::</span><span class="identifier">digits</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">+</span> <span class="number">2</span><span class="special">);</span>
+<span class="special">}</span>
+</pre>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../internals1.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals1.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="cf.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,49 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Testing and Development</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../toolkit.html" title="Internal Details and Tools (Experimental)">
+<link rel="prev" href="internals1/minima.html" title="Locating Function Minima">
+<link rel="next" href="internals2/polynomials.html" title="Polynomials">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="internals1/minima.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../toolkit.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="internals2/polynomials.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.toolkit.internals2"></a> Testing and Development
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"> Polynomials</span></dt>
+<dt><span class="section"><a href="internals2/minimax.html"> Minimax Approximations
+ and the Remez Algorithm</a></span></dt>
+<dt><span class="section"><a href="internals2/error_test.html"> Relative
+ Error and Testing</a></span></dt>
+<dt><span class="section"><a href="internals2/test_data.html"> Graphing,
+ Profiling, and Generating Test Data for Special Functions</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="internals1/minima.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../toolkit.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="internals2/polynomials.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2/error_test.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2/error_test.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,237 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Relative Error and Testing</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../internals2.html" title="Testing and Development">
+<link rel="prev" href="minimax.html" title="Minimax Approximations and the Remez Algorithm">
+<link rel="next" href="test_data.html" title="Graphing, Profiling, and Generating Test Data for Special Functions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="minimax.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals2.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="test_data.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.toolkit.internals2.error_test"></a><a href="error_test.html" title="Relative Error and Testing"> Relative
+ Error and Testing</a>
+</h4></div></div></div>
+<a name="math_toolkit.toolkit.internals2.error_test.synopsis"></a><h5>
+<a name="id722115"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">relative_error</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">b</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">A</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F2</span><span class="special">&gt;</span>
+<span class="identifier">test_result</span><span class="special">&lt;</span><span class="identifier">see</span><span class="special">-</span><span class="identifier">below</span><span class="special">&gt;</span> <span class="identifier">test</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">F1</span> <span class="identifier">test_func</span><span class="special">,</span> <span class="identifier">F2</span> <span class="identifier">expect_func</span><span class="special">);</span>
+</pre>
+<a name="math_toolkit.toolkit.internals2.error_test.description"></a><h5>
+<a name="id722468"></a>
+ Description
+ </h5>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">T</span> <span class="identifier">relative_error</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">v</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the relative error between <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>v</em></span>
+ using the usual formula:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../equations/error1.png"></span>
+ </p>
+<p>
+ In addition the value returned is zero if:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Both <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>v</em></span> are infinite.
+ </li>
+<li>
+ Both <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>v</em></span> are denormalised
+ numbers or zero.
+ </li>
+</ul></div>
+<p>
+ Otherwise if only one of <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>v</em></span>
+ is zero then the value returned is 1.
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">A</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F2</span><span class="special">&gt;</span>
+<span class="identifier">test_result</span><span class="special">&lt;</span><span class="identifier">see</span><span class="special">-</span><span class="identifier">below</span><span class="special">&gt;</span> <span class="identifier">test</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">F1</span> <span class="identifier">test_func</span><span class="special">,</span> <span class="identifier">F2</span> <span class="identifier">expect_func</span><span class="special">);</span>
+</pre>
+<p>
+ This function is used for testing a function against tabulated test data.
+ </p>
+<p>
+ The return type contains statistical data on the relative errors (max,
+ mean, variance, and the number of test cases etc), as well as the row of
+ test data that caused the largest relative error. Public members of type
+ test_result are:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term"><code class="computeroutput"><span class="keyword">unsigned</span>
+ <span class="identifier">worst</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span></code></span></dt>
+<dd><p>
+ Returns the row at which the worst error occurred.
+ </p></dd>
+<dt><span class="term"><code class="computeroutput"><span class="identifier">T</span>
+ <span class="identifier">min</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span></code></span></dt>
+<dd><p>
+ Returns the smallest relative error found.
+ </p></dd>
+<dt><span class="term"><code class="computeroutput"><span class="identifier">T</span>
+ <span class="identifier">max</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span></code></span></dt>
+<dd><p>
+ Returns the largest relative error found.
+ </p></dd>
+<dt><span class="term"><code class="computeroutput"><span class="identifier">T</span>
+ <span class="identifier">mean</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span></code></span></dt>
+<dd><p>
+ Returns the mean error found.
+ </p></dd>
+<dt><span class="term"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span>
+ <span class="identifier">count</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span></code></span></dt>
+<dd><p>
+ Returns the number of test cases.
+ </p></dd>
+<dt><span class="term"><code class="computeroutput"><span class="identifier">T</span>
+ <span class="identifier">variance</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span></code></span></dt>
+<dd><p>
+ Returns the variance of the errors found.
+ </p></dd>
+<dt><span class="term"><code class="computeroutput"><span class="identifier">T</span>
+ <span class="identifier">variance1</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span></code></span></dt>
+<dd><p>
+ Returns the unbiased variance of the errors found.
+ </p></dd>
+<dt><span class="term"><code class="computeroutput"><span class="identifier">T</span>
+ <span class="identifier">rms</span><span class="special">()</span><span class="keyword">const</span></code></span></dt>
+<dd><p>
+ Returns the Root Mean Square, or quadratic mean of the errors.
+ </p></dd>
+<dt><span class="term"><code class="computeroutput"><span class="identifier">test_result</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">+=(</span><span class="keyword">const</span> <span class="identifier">test_result</span><span class="special">&amp;</span>
+ <span class="identifier">t</span><span class="special">)</span></code></span></dt>
+<dd><p>
+ Combines two test_result's into a single result.
+ </p></dd>
+</dl>
+</div>
+<p>
+ The template parameter of test_result, is the same type as the values in
+ the two dimensional array passed to function <span class="emphasis"><em>test</em></span>,
+ roughly that's <code class="computeroutput"><span class="identifier">A</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">::</span><span class="identifier">value_type</span></code>.
+ </p>
+<p>
+ Parameter <span class="emphasis"><em>a</em></span> is a matrix of test data: and must be
+ a standard library Sequence type, that contains another Sequence type:
+ typically it will be a two dimensional instance of <code class="literal">boost::array</code>.
+ Each row of <span class="emphasis"><em>a</em></span> should contain all the parameters that
+ are passed to the function under test as well as the expected result.
+ </p>
+<p>
+ Parameter <span class="emphasis"><em>test_func</em></span> is the function under test, it
+ is invoked with each row of test data in <span class="emphasis"><em>a</em></span>. Typically
+ type F1 is created with Boost.Lambda: see the example below.
+ </p>
+<p>
+ Parameter <span class="emphasis"><em>expect_func</em></span> is a functor that extracts the
+ expected result from a row of test data in <span class="emphasis"><em>a</em></span>. Typically
+ type F2 is created with Boost.Lambda: see the example below.
+ </p>
+<p>
+ If the function under test returns a non-finite value when a finite result
+ is expected, or if a gross error is found, then a message is sent to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code>, and a call to BOOST_ERROR() made
+ (which means that including this header requires you use Boost.Test). This
+ is mainly a debugging/development aid (and a good place for a breakpoint).
+ </p>
+<a name="math_toolkit.toolkit.internals2.error_test.example"></a><h5>
+<a name="id723422"></a>
+ Example
+ </h5>
+<p>
+ Suppose we want to test the tgamma and lgamma functions, we can create
+ a two dimensional matrix of test data, each row is one test case, and contains
+ three elements: the input value, and the expected results for the tgamma
+ and lgamma functions respectively.
+ </p>
+<pre class="programlisting">
+<span class="keyword">static</span> <span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">TestType</span><span class="special">,</span> <span class="number">3</span><span class="special">&gt;,</span> <span class="identifier">NumberOfTests</span><span class="special">&gt;</span>
+ <span class="identifier">factorials</span> <span class="special">=</span> <span class="special">{</span>
+ <span class="comment">/* big array of test data goes here */</span>
+ <span class="special">};</span>
+</pre>
+<p>
+ Now we can invoke the test function to test tgamma:
+ </p>
+<pre class="programlisting">
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">lambda</span><span class="special">;</span>
+
+<span class="comment">// get a pointer to the function under test:
+</span><span class="identifier">TestType</span> <span class="special">(*</span><span class="identifier">funcp</span><span class="special">)(</span><span class="identifier">TestType</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">;</span>
+
+<span class="comment">// declare something to hold the result:
+</span><span class="identifier">test_result</span><span class="special">&lt;</span><span class="identifier">TestType</span><span class="special">&gt;</span> <span class="identifier">result</span><span class="special">;</span>
+<span class="comment">//
+</span><span class="comment">// and test tgamma against data:
+</span><span class="comment">//
+</span><span class="identifier">result</span> <span class="special">=</span> <span class="identifier">test</span><span class="special">(</span>
+ <span class="identifier">factorials</span><span class="special">,</span>
+ <span class="identifier">bind</span><span class="special">(</span><span class="identifier">funcp</span><span class="special">,</span> <span class="identifier">ret</span><span class="special">&lt;</span><span class="identifier">TestType</span><span class="special">&gt;(</span><span class="identifier">_1</span><span class="special">[</span><span class="number">0</span><span class="special">])),</span> <span class="comment">// calls tgamma with factorials[row][0]
+</span> <span class="identifier">ret</span><span class="special">&lt;</span><span class="identifier">TestType</span><span class="special">&gt;(</span><span class="identifier">_1</span><span class="special">[</span><span class="number">1</span><span class="special">])</span> <span class="comment">// extracts the expected result from factorials[row][1]
+</span><span class="special">);</span>
+<span class="comment">//
+</span><span class="comment">// Print out some results:
+</span><span class="comment">//
+</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"The Mean was "</span> <span class="special">&lt;&lt;</span> <span class="identifier">result</span><span class="special">.</span><span class="identifier">mean</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"The worst error was "</span> <span class="special">&lt;&lt;</span> <span class="special">(</span><span class="identifier">result</span><span class="special">.</span><span class="identifier">max</span><span class="special">)()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"The worst error was at row "</span> <span class="special">&lt;&lt;</span> <span class="identifier">result</span><span class="special">.</span><span class="identifier">worst_case</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+<span class="comment">//
+</span><span class="comment">// same again with lgamma this time:
+</span><span class="comment">//
+</span><span class="identifier">funcp</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">lgamma</span><span class="special">;</span>
+<span class="identifier">result</span> <span class="special">=</span> <span class="identifier">test</span><span class="special">(</span>
+ <span class="identifier">factorials</span><span class="special">,</span>
+ <span class="identifier">bind</span><span class="special">(</span><span class="identifier">funcp</span><span class="special">,</span> <span class="identifier">ret</span><span class="special">&lt;</span><span class="identifier">TestType</span><span class="special">&gt;(</span><span class="identifier">_1</span><span class="special">[</span><span class="number">0</span><span class="special">])),</span> <span class="comment">// calls tgamma with factorials[row][0]
+</span> <span class="identifier">ret</span><span class="special">&lt;</span><span class="identifier">TestType</span><span class="special">&gt;(</span><span class="identifier">_1</span><span class="special">[</span><span class="number">2</span><span class="special">])</span> <span class="comment">// extracts the expected result from factorials[row][2]
+</span><span class="special">);</span>
+<span class="comment">//
+</span><span class="comment">// etc ...
+</span><span class="comment">//
+</span></pre>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="minimax.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals2.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="test_data.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2/minimax.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2/minimax.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,269 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Minimax Approximations and the Remez Algorithm</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../internals2.html" title="Testing and Development">
+<link rel="prev" href="polynomials.html" title="Polynomials">
+<link rel="next" href="error_test.html" title="Relative Error and Testing">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="polynomials.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals2.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="error_test.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.toolkit.internals2.minimax"></a><a href="minimax.html" title="Minimax Approximations and the Remez Algorithm"> Minimax Approximations
+ and the Remez Algorithm</a>
+</h4></div></div></div>
+<p>
+ The directory libs/math/minimax contains a command line driven program
+ for the generation of minimax approximations using the Remez algorithm.
+ Both polynomial and rational approximations are supported, although the
+ latter are tricky to converge: it is not uncommon for convergence of rational
+ forms to fail. No such limitations are present for polynomial approximations
+ which should always converge smoothly.
+ </p>
+<p>
+ It's worth stressing that developing rational approximations to functions
+ is often not an easy task, and one to which many books have been devoted.
+ To use this tool, you will need to have a reasonable grasp of what the
+ Remez algorithm is, and the general form of the approximation you want
+ to achieve.
+ </p>
+<p>
+ Unless you already familar with the Remez method you should first read
+ the <a href="../../backgrounders/remez.html" title="The Remez Method">brief background article
+ explaining the principals behind the Remez algorithm</a>.
+ </p>
+<p>
+ The program consists of two parts:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">main.cpp</span></dt>
+<dd><p>
+ Contains the command line parser, and all the calls to the Remez code.
+ </p></dd>
+<dt><span class="term">f.cpp</span></dt>
+<dd><p>
+ Contains the function to approximate.
+ </p></dd>
+</dl>
+</div>
+<p>
+ Therefore to use this tool, you must modify f.cpp to return the function
+ to approximate. The tools supports multiple function approximations within
+ the same compiled program: each as a separate variant:
+ </p>
+<pre class="programlisting">
+<span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span><span class="special">&amp;</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">variant</span><span class="special">);</span>
+</pre>
+<p>
+ Returns the value of the function <span class="emphasis"><em>variant</em></span> at point
+ <span class="emphasis"><em>x</em></span>. So if you wish you can just add the function to
+ approximate as a new variant after the existing examples.
+ </p>
+<p>
+ In addition to those two files, the program needs to be linked to a patched NTL library to compile.
+ </p>
+<p>
+ Note that the function <span class="emphasis"><em>f</em></span> must return the rational
+ part of the approximation: for example if you are approximating a function
+ <span class="emphasis"><em>f(x)</em></span> then it is quite common to use:
+ </p>
+<pre class="programlisting">
+<span class="identifier">f</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">g</span><span class="special">(</span><span class="identifier">x</span><span class="special">)(</span><span class="identifier">Y</span> <span class="special">+</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">x</span><span class="special">))</span>
+</pre>
+<p>
+ where <span class="emphasis"><em>g(x)</em></span> is the dominant part of <span class="emphasis"><em>f(x)</em></span>,
+ <span class="emphasis"><em>Y</em></span> is some constant, and <span class="emphasis"><em>R(x)</em></span>
+ is the rational approximation part, usually optimised for a low absolute
+ error compared to |Y|.
+ </p>
+<p>
+ In this case you would define <span class="emphasis"><em>f</em></span> to return <span class="emphasis"><em>f(x)/g(x)</em></span>
+ and then set the y-offset of the approximation to <span class="emphasis"><em>Y</em></span>
+ (see command line options below).
+ </p>
+<p>
+ Many other forms are possible, but in all cases the objective is to split
+ <span class="emphasis"><em>f(x)</em></span> into a dominant part that you can evaluate easily
+ using standard math functions, and a smooth and slowly changing rational
+ approximation part. Refer to your favourite textbook for more examples.
+ </p>
+<p>
+ Command line options for the program are as follows:
+ </p>
+<div class="variablelist">
+<p class="title"><b></b></p>
+<dl>
+<dt><span class="term">variant N</span></dt>
+<dd><p>
+ Sets the current function variant to N. This allows multiple functions
+ that are to be approximated to be compiled into the same executable.
+ Defaults to 0.
+ </p></dd>
+<dt><span class="term">range a b</span></dt>
+<dd><p>
+ Sets the domain for the approximation to the range [a,b], defaults
+ to [0,1].
+ </p></dd>
+<dt><span class="term">relative</span></dt>
+<dd><p>
+ Sets the Remez code to optimise for relative error. This is the default
+ at program startup. Note that relative error can only be used if f(x)
+ has no roots over the range being optimised.
+ </p></dd>
+<dt><span class="term">absolute</span></dt>
+<dd><p>
+ Sets the Remez code to optimise for absolute error.
+ </p></dd>
+<dt><span class="term">pin [true|false]</span></dt>
+<dd><p>
+ "Pins" the code so that the rational approximation passes
+ through the origin. Obviously only set this to <span class="emphasis"><em>true</em></span>
+ if R(0) must be zero. This is typically used when trying to preserve
+ a root at [0,0] while also optimising for relative error.
+ </p></dd>
+<dt><span class="term">order N D</span></dt>
+<dd><p>
+ Sets the order of the approximation to <span class="emphasis"><em>N</em></span> in the
+ numerator and <span class="emphasis"><em>D</em></span> in the denominator. If <span class="emphasis"><em>D</em></span>
+ is zero then the result will be a polynomial approximation. There will
+ be N+D+2 coefficients in total, the first coefficient of the numerator
+ is zero if <span class="emphasis"><em>pin</em></span> was set to true, and the first
+ coefficient of the denominator is always one.
+ </p></dd>
+<dt><span class="term">working-precision N</span></dt>
+<dd><p>
+ Sets the working precision of NTL::RR to <span class="emphasis"><em>N</em></span> binary
+ digits. Defaults to 250.
+ </p></dd>
+<dt><span class="term">target-precision N</span></dt>
+<dd><p>
+ Sets the precision of printed output to <span class="emphasis"><em>N</em></span> binary
+ digits: set to the same number of digits as the type that will be used
+ to evaluate the approximation. Defaults to 53 (for double precision).
+ </p></dd>
+<dt><span class="term">skew val</span></dt>
+<dd><p>
+ "Skews" the initial interpolated control points towards one
+ end or the other of the range. Positive values skew the initial control
+ points towards the left hand side of the range, and negative values
+ towards the right hand side. If an approximation won't converge (a
+ common situation) try adjusting the skew parameter until the first
+ step yields the smallest possible error. <span class="emphasis"><em>val</em></span> should
+ be in the range [-100,+100], the default is zero.
+ </p></dd>
+<dt><span class="term">brake val</span></dt>
+<dd><p>
+ Sets a brake on each step so that the change in the control points
+ is braked by <span class="emphasis"><em>val%</em></span>. Defaults to 50, try a higher
+ value if an approximation won't converge, or a lower value to get speedier
+ convergence.
+ </p></dd>
+<dt><span class="term">x-offset val</span></dt>
+<dd><p>
+ Sets the x-offset to <span class="emphasis"><em>val</em></span>: the approximation will
+ be generated for <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="identifier">x</span> <span class="special">+</span> <span class="identifier">X</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">Y</span></code> where <span class="emphasis"><em>X</em></span> is
+ the x-offset and <span class="emphasis"><em>Y</em></span> is the y-offset. Defaults to
+ zero. To avoid rounding errors, take care to specify a value that can
+ be exactly represented as a floating point number.
+ </p></dd>
+<dt><span class="term">y-offset val</span></dt>
+<dd><p>
+ Sets the y-offset to <span class="emphasis"><em>val</em></span>: the approximation will
+ be generated for <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="identifier">x</span> <span class="special">+</span> <span class="identifier">X</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">Y</span></code> where <span class="emphasis"><em>X</em></span> is
+ the x-offset and <span class="emphasis"><em>Y</em></span> is the y-offset. Defaults to
+ zero. To avoid rounding errors, take care to specify a value that can
+ be exactly represented as a floating point number.
+ </p></dd>
+<dt><span class="term">y-offset auto</span></dt>
+<dd><p>
+ Sets the y-offset to the average value of f(x) evaluated at the two
+ endpoints of the range plus the midpoint of the range. The calculated
+ value is deliberately truncated to <span class="emphasis"><em>float</em></span> precision
+ (and should be stored as a <span class="emphasis"><em>float</em></span> in your code).
+ The approximation will be generated for <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="identifier">x</span> <span class="special">+</span> <span class="identifier">X</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">Y</span></code> where <span class="emphasis"><em>X</em></span> is
+ the x-offset and <span class="emphasis"><em>Y</em></span> is the y-offset. Defaults to
+ zero.
+ </p></dd>
+<dt><span class="term">graph N</span></dt>
+<dd><p>
+ Prints N evaluations of f(x) at evenly spaced points over the range
+ being optimised. If unspecified then <span class="emphasis"><em>N</em></span> defaults
+ to 3. Use to check that f(x) is indeed smooth over the range of interest.
+ </p></dd>
+<dt><span class="term">step N</span></dt>
+<dd><p>
+ Performs <span class="emphasis"><em>N</em></span> steps, or one step if <span class="emphasis"><em>N</em></span>
+ is unspecified. After each step prints: the peek error at the extrema
+ of the error function of the approximation, the theoretical error term
+ solved for on the last step, and the maximum relative change in the
+ location of the Chebyshev control points. The approximation is converged
+ on the minimax solution when the two error terms are (approximately)
+ equal, and the change in the control points has decreased to a suitably
+ small value.
+ </p></dd>
+<dt><span class="term">test [float|double|long]</span></dt>
+<dd><p>
+ Tests the current approximation at float, double, or long double precision.
+ Useful to check for rounding errors in evaluating the approximation
+ at fixed precision. Tests are conducted at the extrema of the error
+ function of the approximation, and at the zeros of the error function.
+ </p></dd>
+<dt><span class="term">test [float|double|long] N</span></dt>
+<dd><p>
+ Tests the current approximation at float, double, or long double precision.
+ Useful to check for rounding errors in evaluating the approximation
+ at fixed precision. Tests are conducted at N evenly spaced points over
+ the range of the approximation. If none of [float|double|long] are
+ specified then tests using NTL::RR, this can be used to obtain the
+ error function of the approximation.
+ </p></dd>
+<dt><span class="term">rescale a b</span></dt>
+<dd><p>
+ Takes the current Chebeshev control points, and rescales them over
+ a new interval [a,b]. Sometimes this can be used to obtain starting
+ control points for an approximation that can not otherwise be converged.
+ </p></dd>
+<dt><span class="term">rotate</span></dt>
+<dd><p>
+ Moves one term from the numerator to the denominator, but keeps the
+ Chebyshev control points the same. Sometimes this can be used to obtain
+ starting control points for an approximation that can not otherwise
+ be converged.
+ </p></dd>
+<dt><span class="term">info</span></dt>
+<dd><p>
+ Prints out the current approximation: the location of the zeros of
+ the error function, the location of the Chebyshev control points, the
+ x and y offsets, and of course the coefficients of the polynomials.
+ </p></dd>
+</dl>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="polynomials.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals2.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="error_test.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2/polynomials.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2/polynomials.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,135 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Polynomials</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../internals2.html" title="Testing and Development">
+<link rel="prev" href="../internals2.html" title="Testing and Development">
+<link rel="next" href="minimax.html" title="Minimax Approximations and the Remez Algorithm">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../internals2.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals2.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="minimax.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.toolkit.internals2.polynomials"></a> Polynomials
+</h4></div></div></div>
+<a name="math_toolkit.toolkit.internals2.polynomials.synopsis"></a><h5>
+<a name="id718276"></a>
+ Synopsis
+ </h5>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">polynomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">tools</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">polynomial</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="comment">// typedefs:
+</span> <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">value_type</span> <span class="identifier">value_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">size_type</span> <span class="identifier">size_type</span><span class="special">;</span>
+
+ <span class="comment">// construct:
+</span> <span class="identifier">polynomial</span><span class="special">(){}</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+ <span class="identifier">polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">U</span><span class="special">*</span> <span class="identifier">data</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">order</span><span class="special">);</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+ <span class="identifier">polynomial</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">U</span><span class="special">&amp;</span> <span class="identifier">point</span><span class="special">);</span>
+
+ <span class="comment">// access:
+</span> <span class="identifier">size_type</span> <span class="identifier">size</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">size_type</span> <span class="identifier">degree</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">value_type</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">[](</span><span class="identifier">size_type</span> <span class="identifier">i</span><span class="special">);</span>
+ <span class="keyword">const</span> <span class="identifier">value_type</span><span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">[](</span><span class="identifier">size_type</span> <span class="identifier">i</span><span class="special">)</span><span class="keyword">const</span><span class="special">;</span>
+
+ <span class="comment">// operators:
+</span> <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+ <span class="identifier">polynomial</span><span class="special">&amp;</span> <span class="keyword">operator</span> <span class="special">+=(</span><span class="keyword">const</span> <span class="identifier">U</span><span class="special">&amp;</span> <span class="identifier">value</span><span class="special">);</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+ <span class="identifier">polynomial</span><span class="special">&amp;</span> <span class="keyword">operator</span> <span class="special">-=(</span><span class="keyword">const</span> <span class="identifier">U</span><span class="special">&amp;</span> <span class="identifier">value</span><span class="special">);</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+ <span class="identifier">polynomial</span><span class="special">&amp;</span> <span class="keyword">operator</span> <span class="special">*=(</span><span class="keyword">const</span> <span class="identifier">U</span><span class="special">&amp;</span> <span class="identifier">value</span><span class="special">);</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+ <span class="identifier">polynomial</span><span class="special">&amp;</span> <span class="keyword">operator</span> <span class="special">+=(</span><span class="keyword">const</span> <span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">U</span><span class="special">&gt;&amp;</span> <span class="identifier">value</span><span class="special">);</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+ <span class="identifier">polynomial</span><span class="special">&amp;</span> <span class="keyword">operator</span> <span class="special">-=(</span><span class="keyword">const</span> <span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">U</span><span class="special">&gt;&amp;</span> <span class="identifier">value</span><span class="special">);</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+ <span class="identifier">polynomial</span><span class="special">&amp;</span> <span class="keyword">operator</span> <span class="special">*=(</span><span class="keyword">const</span> <span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">U</span><span class="special">&gt;&amp;</span> <span class="identifier">value</span><span class="special">);</span>
+<span class="special">};</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">operator</span> <span class="special">+</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">b</span><span class="special">);</span>
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">operator</span> <span class="special">-</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">b</span><span class="special">);</span>
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">operator</span> <span class="special">*</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">b</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+<span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">operator</span> <span class="special">+</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">U</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">);</span>
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+<span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">operator</span> <span class="special">-</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">U</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">);</span>
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span>
+<span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">operator</span> <span class="special">*</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">U</span><span class="special">&amp;</span> <span class="identifier">b</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">operator</span> <span class="special">+</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">U</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">b</span><span class="special">);</span>
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">operator</span> <span class="special">-</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">U</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">b</span><span class="special">);</span>
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">operator</span> <span class="special">*</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">U</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">b</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">charT</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">traits</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_ostream</span><span class="special">&lt;</span><span class="identifier">charT</span><span class="special">,</span> <span class="identifier">traits</span><span class="special">&gt;&amp;</span> <span class="keyword">operator</span> <span class="special">&lt;&lt;</span>
+ <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_ostream</span><span class="special">&lt;</span><span class="identifier">charT</span><span class="special">,</span> <span class="identifier">traits</span><span class="special">&gt;&amp;</span> <span class="identifier">os</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">polynomial</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">poly</span><span class="special">);</span>
+
+<span class="special">}}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.toolkit.internals2.polynomials.description"></a><h5>
+<a name="id721052"></a>
+ Description
+ </h5>
+<p>
+ This is a fairly trivial class for polynomial manipulation.
+ </p>
+<p>
+ Implementation is currently of the "naive" variety, with O(N^2)
+ multiplication for example. This class should not be used in high-performance
+ computing environments: it is intended for the simple manipulation of small
+ polynomials, typically generated for special function approximation.
+ </p>
+<p>
+ Advanced manipulations: the FFT, division, GCD, factorisation etc are not
+ currently provided. Submissions for these are of course welcome :-)
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../internals2.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals2.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="minimax.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2/test_data.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2/test_data.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,560 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Graphing, Profiling, and Generating Test Data for Special Functions</title>
+<link rel="stylesheet" href="../../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../../index.html" title="Math Toolkit">
+<link rel="up" href="../internals2.html" title="Testing and Development">
+<link rel="prev" href="error_test.html" title="Relative Error and Testing">
+<link rel="next" href="../../using_udt.html" title="Use with User Defined Floating-Point Types">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="error_test.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals2.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../../using_udt.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="math_toolkit.toolkit.internals2.test_data"></a><a href="test_data.html" title="Graphing, Profiling, and Generating Test Data for Special Functions"> Graphing,
+ Profiling, and Generating Test Data for Special Functions</a>
+</h4></div></div></div>
+<p>
+ The class <code class="computeroutput"><span class="identifier">test_data</span></code> and
+ associated helper functions are designed so that in just a few lines of
+ code you should be able to:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Profile a continued fraction, or infinite series for convergence and
+ accuracy.
+ </li>
+<li>
+ Generate csv data from a special function that can be imported into your
+ favorite graphing program (or spreadsheet) for further analysis.
+ </li>
+<li>
+ Generate high precision test data.
+ </li>
+</ul></div>
+<a name="math_toolkit.toolkit.internals2.test_data.synopsis"></a><h5>
+<a name="id724520"></a>
+ Synopsis
+ </h5>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">tools</span><span class="special">{</span>
+
+<span class="keyword">enum</span> <span class="identifier">parameter_type</span>
+<span class="special">{</span>
+ <span class="identifier">random_in_range</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span>
+ <span class="identifier">periodic_in_range</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span>
+ <span class="identifier">power_series</span> <span class="special">=</span> <span class="number">2</span><span class="special">,</span>
+ <span class="identifier">dummy_param</span> <span class="special">=</span> <span class="number">0x80</span><span class="special">,</span>
+<span class="special">};</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">parameter_info</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">make_random_param</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">start_range</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">end_range</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">n_points</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">make_periodic_param</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">start_range</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">end_range</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">n_points</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">make_power_param</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">basis</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">start_exponent</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">end_exponent</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">bool</span> <span class="identifier">get_user_parameter_info</span><span class="special">(</span><span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">info</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">param_name</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">test_data</span>
+<span class="special">{</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">row_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">row_type</span> <span class="identifier">value_type</span><span class="special">;</span>
+<span class="keyword">private</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">set</span><span class="special">&lt;</span><span class="identifier">row_type</span><span class="special">&gt;</span> <span class="identifier">container_type</span><span class="special">;</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">container_type</span><span class="special">::</span><span class="identifier">reference</span> <span class="identifier">reference</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">container_type</span><span class="special">::</span><span class="identifier">const_reference</span> <span class="identifier">const_reference</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">container_type</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">iterator</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">container_type</span><span class="special">::</span><span class="identifier">const_iterator</span> <span class="identifier">const_iterator</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">container_type</span><span class="special">::</span><span class="identifier">difference_type</span> <span class="identifier">difference_type</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="keyword">typename</span> <span class="identifier">container_type</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">size_type</span><span class="special">;</span>
+
+ <span class="comment">// creation:
+</span> <span class="identifier">test_data</span><span class="special">(){}</span>
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">&gt;</span>
+ <span class="identifier">test_data</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">func</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">arg1</span><span class="special">);</span>
+
+ <span class="comment">// insertion:
+</span> <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">&gt;</span>
+ <span class="identifier">test_data</span><span class="special">&amp;</span> <span class="identifier">insert</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">func</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">arg1</span><span class="special">);</span>
+
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">&gt;</span>
+ <span class="identifier">test_data</span><span class="special">&amp;</span> <span class="identifier">insert</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">func</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">arg1</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">arg2</span><span class="special">);</span>
+
+ <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">&gt;</span>
+ <span class="identifier">test_data</span><span class="special">&amp;</span> <span class="identifier">insert</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">func</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">arg1</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">arg2</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">arg3</span><span class="special">);</span>
+
+ <span class="keyword">void</span> <span class="identifier">clear</span><span class="special">();</span>
+
+ <span class="comment">// access:
+</span> <span class="identifier">iterator</span> <span class="identifier">begin</span><span class="special">();</span>
+ <span class="identifier">iterator</span> <span class="identifier">end</span><span class="special">();</span>
+ <span class="identifier">const_iterator</span> <span class="identifier">begin</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">const_iterator</span> <span class="identifier">end</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">==(</span><span class="keyword">const</span> <span class="identifier">test_data</span><span class="special">&amp;</span> <span class="identifier">d</span><span class="special">)</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">!=(</span><span class="keyword">const</span> <span class="identifier">test_data</span><span class="special">&amp;</span> <span class="identifier">d</span><span class="special">)</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="keyword">void</span> <span class="identifier">swap</span><span class="special">(</span><span class="identifier">test_data</span><span class="special">&amp;</span> <span class="identifier">other</span><span class="special">);</span>
+ <span class="identifier">size_type</span> <span class="identifier">size</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="identifier">size_type</span> <span class="identifier">max_size</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="keyword">bool</span> <span class="identifier">empty</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
+
+ <span class="keyword">bool</span> <span class="keyword">operator</span> <span class="special">&lt;</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">test_data</span><span class="special">&amp;</span> <span class="identifier">dat</span><span class="special">)</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="keyword">bool</span> <span class="keyword">operator</span> <span class="special">&lt;=</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">test_data</span><span class="special">&amp;</span> <span class="identifier">dat</span><span class="special">)</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="keyword">bool</span> <span class="keyword">operator</span> <span class="special">&gt;</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">test_data</span><span class="special">&amp;</span> <span class="identifier">dat</span><span class="special">)</span><span class="keyword">const</span><span class="special">;</span>
+ <span class="keyword">bool</span> <span class="keyword">operator</span> <span class="special">&gt;=</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">test_data</span><span class="special">&amp;</span> <span class="identifier">dat</span><span class="special">)</span><span class="keyword">const</span><span class="special">;</span>
+<span class="special">};</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">charT</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">traits</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_ostream</span><span class="special">&lt;</span><span class="identifier">charT</span><span class="special">,</span> <span class="identifier">traits</span><span class="special">&gt;&amp;</span> <span class="identifier">write_csv</span><span class="special">(</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_ostream</span><span class="special">&lt;</span><span class="identifier">charT</span><span class="special">,</span> <span class="identifier">traits</span><span class="special">&gt;&amp;</span> <span class="identifier">os</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">test_data</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">data</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">charT</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">traits</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_ostream</span><span class="special">&lt;</span><span class="identifier">charT</span><span class="special">,</span> <span class="identifier">traits</span><span class="special">&gt;&amp;</span> <span class="identifier">write_csv</span><span class="special">(</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_ostream</span><span class="special">&lt;</span><span class="identifier">charT</span><span class="special">,</span> <span class="identifier">traits</span><span class="special">&gt;&amp;</span> <span class="identifier">os</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">test_data</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">data</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">charT</span><span class="special">*</span> <span class="identifier">separator</span><span class="special">);</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&amp;</span> <span class="identifier">write_code</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span><span class="special">&amp;</span> <span class="identifier">os</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="identifier">test_data</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">data</span><span class="special">,</span>
+ <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">name</span><span class="special">);</span>
+
+<span class="special">}}}</span> <span class="comment">// namespaces
+</span></pre>
+<a name="math_toolkit.toolkit.internals2.test_data.description"></a><h5>
+<a name="id727446"></a>
+ Description
+ </h5>
+<p>
+ This tool is best illustrated with the following series of examples.
+ </p>
+<p>
+ The functionality of test_data is split into the following parts:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ A functor that implements the function for which data is being generated:
+ this is the bit you have to write.
+ </li>
+<li>
+ One of more parameters that are to be passed to the functor, these are
+ described in fairly abstract terms: give me N points distributed like
+ <span class="emphasis"><em>this</em></span> etc.
+ </li>
+<li>
+ The class test_data, that takes the functor and descriptions of the parameters
+ and computes how ever many output points have been requested, these are
+ stored in a sorted container.
+ </li>
+<li>
+ Routines to iterate over the test_data container and output the data
+ in either csv format, or as C++ source code (as a table using Boost.Array).
+ </li>
+</ul></div>
+<a name="math_toolkit.toolkit.internals2.test_data.example_1__output_data_for_graph_plotting"></a><h6>
+<a name="id727519"></a>
+ <a href="test_data.html#math_toolkit.toolkit.internals2.test_data.example_1__output_data_for_graph_plotting">Example
+ 1: Output Data for Graph Plotting</a>
+ </h6>
+<p>
+ For example, lets say we want to graph the lgamma function between -3 and
+ 100, one could do this like so:
+ </p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">test_data</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">;</span>
+
+ <span class="comment">// create an object to hold the data:
+</span> <span class="identifier">test_data</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">data</span><span class="special">;</span>
+
+ <span class="comment">// insert 500 points at uniform intervals between just after -3 and 100:
+</span> <span class="keyword">double</span> <span class="special">(*</span><span class="identifier">pf</span><span class="special">)(</span><span class="keyword">double</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">lgamma</span><span class="special">;</span>
+ <span class="identifier">data</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span><span class="identifier">pf</span><span class="special">,</span> <span class="identifier">make_periodic_param</span><span class="special">(-</span><span class="number">3.0</span> <span class="special">+</span> <span class="number">0.00001</span><span class="special">,</span> <span class="number">100.0</span><span class="special">,</span> <span class="number">500</span><span class="special">));</span>
+
+ <span class="comment">// print out in csv format:
+</span> <span class="identifier">write_csv</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span> <span class="identifier">data</span><span class="special">,</span> <span class="string">", "</span><span class="special">);</span>
+ <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ Which, when plotted, results in:
+ </p>
+<p>
+ <span class="inlinemediaobject"><img src="../../../../graphs/lgamma.png" alt="lgamma"></span>
+ </p>
+<a name="math_toolkit.toolkit.internals2.test_data.example_2__creating_test_data"></a><h6>
+<a name="id728064"></a>
+ <a href="test_data.html#math_toolkit.toolkit.internals2.test_data.example_2__creating_test_data">Example
+ 2: Creating Test Data</a>
+ </h6>
+<p>
+ As a second example, let's suppose we want to create highly accurate test
+ data for a special function. Since many special functions have two or more
+ independent parameters, it's very hard to effectively cover all of the
+ possible parameter space without generating gigabytes of data at great
+ computational expense. A second best approach is to provide the tools by
+ which a user (or the library maintainer) can quickly generate more data
+ on demand to probe the function over a particular domain of interest.
+ </p>
+<p>
+ In this example we'll generate test data for the beta function using NTL::RR at 1000 bit precision.
+ Rather than call our generic version of the beta function, we'll implement
+ a deliberately naive version of the beta function using lgamma, and rely
+ on the high precision of the data type used to get results accurate to
+ at least 128-bit precision. In this way our test data is independent of
+ whatever clever tricks we may wish to use inside the our beta function.
+ </p>
+<p>
+ To start with then, here's the function object that creates the test data:
+ </p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">ntl</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">test_data</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">fstream</span><span class="special">&gt;</span>
+
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">test_data</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">;</span>
+
+<span class="keyword">struct</span> <span class="identifier">beta_data_generator</span>
+<span class="special">{</span>
+ <span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span> <span class="identifier">b</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="comment">//
+</span> <span class="comment">// If we throw a domain error then test_data will
+</span> <span class="comment">// ignore this input point. We'll use this to filter
+</span> <span class="comment">// out all cases where a &lt; b since the beta function
+</span> <span class="comment">// is symmetrical in a and b:
+</span> <span class="comment">//
+</span> <span class="keyword">if</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span><span class="special">)</span>
+ <span class="keyword">throw</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span><span class="special">(</span><span class="string">""</span><span class="special">);</span>
+
+ <span class="comment">// very naively calculate spots with lgamma:
+</span> <span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span> <span class="identifier">g1</span><span class="special">,</span> <span class="identifier">g2</span><span class="special">,</span> <span class="identifier">g3</span><span class="special">;</span>
+ <span class="keyword">int</span> <span class="identifier">s1</span><span class="special">,</span> <span class="identifier">s2</span><span class="special">,</span> <span class="identifier">s3</span><span class="special">;</span>
+ <span class="identifier">g1</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">s1</span><span class="special">);</span>
+ <span class="identifier">g2</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">s2</span><span class="special">);</span>
+ <span class="identifier">g3</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">lgamma</span><span class="special">(</span><span class="identifier">a</span><span class="special">+</span><span class="identifier">b</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">s3</span><span class="special">);</span>
+ <span class="identifier">g1</span> <span class="special">+=</span> <span class="identifier">g2</span> <span class="special">-</span> <span class="identifier">g3</span><span class="special">;</span>
+ <span class="identifier">g1</span> <span class="special">=</span> <span class="identifier">exp</span><span class="special">(</span><span class="identifier">g1</span><span class="special">);</span>
+ <span class="identifier">g1</span> <span class="special">*=</span> <span class="identifier">s1</span> <span class="special">*</span> <span class="identifier">s2</span> <span class="special">*</span> <span class="identifier">s3</span><span class="special">;</span>
+ <span class="keyword">return</span> <span class="identifier">g1</span><span class="special">;</span>
+ <span class="special">}</span>
+<span class="special">};</span>
+</pre>
+<p>
+ To create the data, we'll need to input the domains for a and b for which
+ the function will be tested: the function <code class="computeroutput"><span class="identifier">get_user_parameter_info</span></code>
+ is designed for just that purpose. The start of main will look something
+ like:
+ </p>
+<pre class="programlisting">
+<span class="comment">// Set the precision on RR:
+</span><span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span><span class="special">::</span><span class="identifier">SetPrecision</span><span class="special">(</span><span class="number">1000</span><span class="special">);</span> <span class="comment">// bits.
+</span><span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span><span class="special">::</span><span class="identifier">SetOutputPrecision</span><span class="special">(</span><span class="number">40</span><span class="special">);</span> <span class="comment">// decimal digits.
+</span>
+<span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span><span class="special">&gt;</span> <span class="identifier">arg1</span><span class="special">,</span> <span class="identifier">arg2</span><span class="special">;</span>
+<span class="identifier">test_data</span><span class="special">&lt;</span><span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span><span class="special">&gt;</span> <span class="identifier">data</span><span class="special">;</span>
+
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Welcome.\n"</span>
+ <span class="string">"This program will generate spot tests for the beta function:\n"</span>
+ <span class="string">" beta(a, b)\n\n"</span><span class="special">;</span>
+
+<span class="keyword">bool</span> <span class="identifier">cont</span><span class="special">;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">line</span><span class="special">;</span>
+
+<span class="keyword">do</span><span class="special">{</span>
+ <span class="comment">// prompt the user for the domain of a and b to test:
+</span> <span class="identifier">get_user_parameter_info</span><span class="special">(</span><span class="identifier">arg1</span><span class="special">,</span> <span class="string">"a"</span><span class="special">);</span>
+ <span class="identifier">get_user_parameter_info</span><span class="special">(</span><span class="identifier">arg2</span><span class="special">,</span> <span class="string">"b"</span><span class="special">);</span>
+
+ <span class="comment">// create the data:
+</span> <span class="identifier">data</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span><span class="identifier">beta_data_generator</span><span class="special">(),</span> <span class="identifier">arg1</span><span class="special">,</span> <span class="identifier">arg2</span><span class="special">);</span>
+
+ <span class="comment">// see if the user want's any more domains tested:
+</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Any more data [y/n]?"</span><span class="special">;</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">getline</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cin</span><span class="special">,</span> <span class="identifier">line</span><span class="special">);</span>
+ <span class="identifier">boost</span><span class="special">::</span><span class="identifier">algorithm</span><span class="special">::</span><span class="identifier">trim</span><span class="special">(</span><span class="identifier">line</span><span class="special">);</span>
+ <span class="identifier">cont</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">line</span> <span class="special">==</span> <span class="string">"y"</span><span class="special">);</span>
+<span class="special">}</span><span class="keyword">while</span><span class="special">(</span><span class="identifier">cont</span><span class="special">);</span>
+</pre>
+<div class="caution"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../doc/html/images/caution.png"></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ At this point one potential stumbling block should be mentioned: test_data&lt;&gt;::insert
+ will create a matrix of test data when there are two or more parameters,
+ so if we have two parameters and we're asked for a thousand points on
+ each, that's a <span class="emphasis"><em>million test points in total</em></span>. Don't
+ say you weren't warned!
+ </p></td></tr>
+</table></div>
+<p>
+ There's just one final step now, and that's to write the test data to file:
+ </p>
+<pre class="programlisting">
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Enter name of test data file [default=beta_data.ipp]"</span><span class="special">;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">getline</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cin</span><span class="special">,</span> <span class="identifier">line</span><span class="special">);</span>
+<span class="identifier">boost</span><span class="special">::</span><span class="identifier">algorithm</span><span class="special">::</span><span class="identifier">trim</span><span class="special">(</span><span class="identifier">line</span><span class="special">);</span>
+<span class="keyword">if</span><span class="special">(</span><span class="identifier">line</span> <span class="special">==</span> <span class="string">""</span><span class="special">)</span>
+ <span class="identifier">line</span> <span class="special">=</span> <span class="string">"beta_data.ipp"</span><span class="special">;</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">ofstream</span> <span class="identifier">ofs</span><span class="special">(</span><span class="identifier">line</span><span class="special">.</span><span class="identifier">c_str</span><span class="special">());</span>
+<span class="identifier">write_code</span><span class="special">(</span><span class="identifier">ofs</span><span class="special">,</span> <span class="identifier">data</span><span class="special">,</span> <span class="string">"beta_data"</span><span class="special">);</span>
+</pre>
+<p>
+ The format of the test data looks something like:
+ </p>
+<pre class="programlisting">
+<span class="preprocessor">#define</span> <span class="identifier">SC_</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</span><span class="identifier">BOOST_JOIN</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">L</span><span class="special">))</span>
+ <span class="keyword">static</span> <span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="number">3</span><span class="special">&gt;,</span> <span class="number">1830</span><span class="special">&gt;</span>
+ <span class="identifier">beta_med_data</span> <span class="special">=</span> <span class="special">{</span>
+ <span class="identifier">SC_</span><span class="special">(</span><span class="number">0.4883005917072296142578125</span><span class="special">),</span>
+ <span class="identifier">SC_</span><span class="special">(</span><span class="number">0.4883005917072296142578125</span><span class="special">),</span>
+ <span class="identifier">SC_</span><span class="special">(</span><span class="number">3.245912809500479157065104747353807392371</span><span class="special">),</span>
+ <span class="identifier">SC_</span><span class="special">(</span><span class="number">3.5808107852935791015625</span><span class="special">),</span>
+ <span class="identifier">SC_</span><span class="special">(</span><span class="number">0.4883005917072296142578125</span><span class="special">),</span>
+ <span class="identifier">SC_</span><span class="special">(</span><span class="number">1.007653173802923954909901438393379243537</span><span class="special">),</span>
+ <span class="comment">/* ... lots of rows skipped */</span>
+<span class="special">};</span>
+</pre>
+<p>
+ The first two values in each row are the input parameters that were passed
+ to our functor and the last value is the return value from the functor.
+ Had our functor returned a tuple rather than a value, then we would have
+ had one entry for each element in the tuple in addition to the input parameters.
+ </p>
+<p>
+ The first #define serves two purposes:
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ It reduces the file sizes considerably: all those <code class="computeroutput"><span class="keyword">static_cast</span></code>'s
+ add up to a lot of bytes otherwise (they are needed to suppress compiler
+ warnings when <code class="computeroutput"><span class="identifier">T</span></code> is narrower
+ than a <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>).
+ </li>
+<li>
+ It provides a useful customisation point: for example if we were testing
+ a user-defined type that has more precision than a <code class="computeroutput"><span class="keyword">long</span>
+ <span class="keyword">double</span></code> we could change it to:
+ </li>
+</ul></div>
+<p>
+ <code class="literal">#define SC_(x) lexical_cast&lt;T&gt;(BOOST_STRINGIZE(x))</code>
+ </p>
+<p>
+ in order to ensure that no truncation of the values occurs prior to conversion
+ to <code class="computeroutput"><span class="identifier">T</span></code>. Note that this isn't
+ used by default as it's rather hard on the compiler when the table is large.
+ </p>
+<a name="math_toolkit.toolkit.internals2.test_data.example_3__profiling_a_continued_fraction_for_convergence_and_accuracy"></a><h6>
+<a name="id730555"></a>
+ <a href="test_data.html#math_toolkit.toolkit.internals2.test_data.example_3__profiling_a_continued_fraction_for_convergence_and_accuracy">Example
+ 3: Profiling a Continued Fraction for Convergence and Accuracy</a>
+ </h6>
+<p>
+ Alternatively, lets say we want to profile a continued fraction for convergence
+ and error. As an example, we'll use the continued fraction for the upper
+ incomplete gamma function, the following function object returns the next
+ a<sub>N </sub> and b<sub>N </sub> of the continued fraction each time it's invoked:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">upper_incomplete_gamma_fract</span>
+<span class="special">{</span>
+<span class="keyword">private</span><span class="special">:</span>
+ <span class="identifier">T</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">a</span><span class="special">;</span>
+ <span class="keyword">int</span> <span class="identifier">k</span><span class="special">;</span>
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">result_type</span><span class="special">;</span>
+
+ <span class="identifier">upper_incomplete_gamma_fract</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">a1</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">z1</span><span class="special">)</span>
+ <span class="special">:</span> <span class="identifier">z</span><span class="special">(</span><span class="identifier">z1</span><span class="special">-</span><span class="identifier">a1</span><span class="special">+</span><span class="number">1</span><span class="special">),</span> <span class="identifier">a</span><span class="special">(</span><span class="identifier">a1</span><span class="special">),</span> <span class="identifier">k</span><span class="special">(</span><span class="number">0</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="special">}</span>
+
+ <span class="identifier">result_type</span> <span class="keyword">operator</span><span class="special">()()</span>
+ <span class="special">{</span>
+ <span class="special">++</span><span class="identifier">k</span><span class="special">;</span>
+ <span class="identifier">z</span> <span class="special">+=</span> <span class="number">2</span><span class="special">;</span>
+ <span class="keyword">return</span> <span class="identifier">result_type</span><span class="special">(</span><span class="identifier">k</span> <span class="special">*</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">-</span> <span class="identifier">k</span><span class="special">),</span> <span class="identifier">z</span><span class="special">);</span>
+ <span class="special">}</span>
+<span class="special">};</span>
+</pre>
+<p>
+ We want to measure both the relative error, and the rate of convergence
+ of this fraction, so we'll write a functor that returns both as a tuple:
+ class test_data will unpack the tuple for us, and create one column of
+ data for each element in the tuple (in addition to the input parameters):
+ </p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">test_data</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">ntl</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">tr1</span><span class="special">/</span><span class="identifier">tuple</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">profile_gamma_fraction</span>
+<span class="special">{</span>
+ <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">tr1</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">result_type</span><span class="special">;</span>
+
+ <span class="identifier">result_type</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">T</span> <span class="identifier">val</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">;</span>
+ <span class="comment">// estimate the true value, using arbitary precision
+</span> <span class="comment">// arithmetic and NTL::RR:
+</span> <span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span> <span class="identifier">rval</span><span class="special">(</span><span class="identifier">val</span><span class="special">);</span>
+ <span class="identifier">upper_incomplete_gamma_fract</span><span class="special">&lt;</span><span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span><span class="special">&gt;</span> <span class="identifier">f1</span><span class="special">(</span><span class="identifier">rval</span><span class="special">,</span> <span class="identifier">rval</span><span class="special">);</span>
+ <span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span> <span class="identifier">true_val</span> <span class="special">=</span> <span class="identifier">continued_fraction_a</span><span class="special">(</span><span class="identifier">f1</span><span class="special">,</span> <span class="number">1000</span><span class="special">);</span>
+ <span class="comment">//
+</span> <span class="comment">// Now get the aproximation at double precision, along with the number of
+</span> <span class="comment">// iterations required:
+</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span> <span class="identifier">iters</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span><span class="special">&gt;::</span><span class="identifier">max</span><span class="special">();</span>
+ <span class="identifier">upper_incomplete_gamma_fract</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">f2</span><span class="special">(</span><span class="identifier">val</span><span class="special">,</span> <span class="identifier">val</span><span class="special">);</span>
+ <span class="identifier">T</span> <span class="identifier">found_val</span> <span class="special">=</span> <span class="identifier">continued_fraction_a</span><span class="special">(</span><span class="identifier">f2</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">digits</span><span class="special">,</span> <span class="identifier">iters</span><span class="special">);</span>
+ <span class="comment">//
+</span> <span class="comment">// Work out the relative error, as measured in units of epsilon:
+</span> <span class="identifier">T</span> <span class="identifier">err</span> <span class="special">=</span> <span class="identifier">real_cast</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</span><span class="identifier">relative_error</span><span class="special">(</span><span class="identifier">true_val</span><span class="special">,</span> <span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span><span class="special">(</span><span class="identifier">found_val</span><span class="special">))</span> <span class="special">/</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">epsilon</span><span class="special">());</span>
+ <span class="comment">//
+</span> <span class="comment">// now just return the results as a tuple:
+</span> <span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">tr1</span><span class="special">::</span><span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">err</span><span class="special">,</span> <span class="identifier">iters</span><span class="special">);</span>
+ <span class="special">}</span>
+<span class="special">};</span>
+</pre>
+<p>
+ Feeding that functor into test_data allows rapid output of csv data, for
+ whatever type <code class="computeroutput"><span class="identifier">T</span></code> we may
+ be interested in:
+ </p>
+<pre class="programlisting">
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">;</span>
+ <span class="comment">// create an object to hold the data:
+</span> <span class="identifier">test_data</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">data</span><span class="special">;</span>
+ <span class="comment">// insert 500 points at uniform intervals between just after 0 and 100:
+</span> <span class="identifier">data</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span><span class="identifier">profile_gamma_fraction</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;(),</span> <span class="identifier">make_periodic_param</span><span class="special">(</span><span class="number">0.01</span><span class="special">,</span> <span class="number">100.0</span><span class="special">,</span> <span class="number">100</span><span class="special">));</span>
+ <span class="comment">// print out in csv format:
+</span> <span class="identifier">write_csv</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span> <span class="identifier">data</span><span class="special">,</span> <span class="string">", "</span><span class="special">);</span>
+ <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ This time there's no need to plot a graph, the first few rows are:
+ </p>
+<pre class="programlisting">
+<span class="identifier">a</span> <span class="keyword">and</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">Error</span><span class="special">/</span><span class="identifier">epsilon</span><span class="special">,</span> <span class="identifier">Iterations</span> <span class="identifier">required</span>
+
+<span class="number">0.01</span><span class="special">,</span> <span class="number">9723.14</span><span class="special">,</span> <span class="number">4726</span>
+<span class="number">1.0099</span><span class="special">,</span> <span class="number">9.54818</span><span class="special">,</span> <span class="number">87</span>
+<span class="number">2.0098</span><span class="special">,</span> <span class="number">3.84777</span><span class="special">,</span> <span class="number">40</span>
+<span class="number">3.0097</span><span class="special">,</span> <span class="number">0.728358</span><span class="special">,</span> <span class="number">25</span>
+<span class="number">4.0096</span><span class="special">,</span> <span class="number">2.39712</span><span class="special">,</span> <span class="number">21</span>
+<span class="number">5.0095</span><span class="special">,</span> <span class="number">0.233263</span><span class="special">,</span> <span class="number">16</span>
+</pre>
+<p>
+ So it's pretty clear that this fraction shouldn't be used for small values
+ of a and z.
+ </p>
+<a name="math_toolkit.toolkit.internals2.test_data.reference"></a><h5>
+<a name="id732799"></a>
+ reference
+ </h5>
+<a name="test_data_reference"></a><p>
+ </p>
+<p>
+ Most of this tool has been described already in the examples above, we'll
+ just add the following notes on the non-member functions:
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">make_random_param</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">start_range</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">end_range</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">n_points</span><span class="special">);</span>
+</pre>
+<p>
+ Tells class test_data to test <span class="emphasis"><em>n_points</em></span> random values
+ in the range [start_range,end_range].
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">make_periodic_param</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">start_range</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">end_range</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">n_points</span><span class="special">);</span>
+</pre>
+<p>
+ Tells class test_data to test <span class="emphasis"><em>n_points</em></span> evenly spaced
+ values in the range [start_range,end_range].
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">make_power_param</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">basis</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">start_exponent</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">end_exponent</span><span class="special">);</span>
+</pre>
+<p>
+ Tells class test_data to test points of the form <span class="emphasis"><em>basis + R *
+ 2<sup>expon</sup></em></span> for each <span class="emphasis"><em>expon</em></span> in the range [start_exponent,
+ end_exponent], and <span class="emphasis"><em>R</em></span> a random number in [0.5, 1].
+ </p>
+<pre class="programlisting">
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">bool</span> <span class="identifier">get_user_parameter_info</span><span class="special">(</span><span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">info</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">param_name</span><span class="special">);</span>
+</pre>
+<p>
+ Prompts the user for the parameter range and form to use.
+ </p>
+<p>
+ Finally, if we don't want the parameter to be included in the output, we
+ can tell test_data by setting it a "dummy parameter":
+ </p>
+<pre class="programlisting">
+<span class="identifier">parameter_info</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">make_random_param</span><span class="special">(</span><span class="number">2.0</span><span class="special">,</span> <span class="number">5.0</span><span class="special">,</span> <span class="number">10</span><span class="special">);</span>
+<span class="identifier">p</span><span class="special">.</span><span class="identifier">type</span> <span class="special">|=</span> <span class="identifier">dummy_param</span><span class="special">;</span>
+</pre>
+<p>
+ This is useful when the functor used transforms the parameter in some way
+ before passing it to the function under test, usually the functor will
+ then return both the transformed input and the result in a tuple, so there's
+ no need for the original pseudo-parameter to be included in program output.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="error_test.html"><img src="../../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals2.html"><img src="../../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../../using_udt.html"><img src="../../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals_overview.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals_overview.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,54 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Overview</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../toolkit.html" title="Internal Details and Tools (Experimental)">
+<link rel="prev" href="../toolkit.html" title="Internal Details and Tools (Experimental)">
+<link rel="next" href="internals1.html" title="Reused Utilities">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../toolkit.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../toolkit.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="internals1.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.toolkit.internals_overview"></a> Overview
+</h3></div></div></div>
+<p>
+ This section contains internal utilities used by the library's implementation
+ along with tools used in development and testing. These tools have only minimal
+ documentation, and crucially <span class="emphasis"><em>do not have stable interfaces</em></span>.
+ </p>
+<p>
+ There is no doubt that these components can be improved, but they are also
+ largely incidental to the main purpose of this library.
+ </p>
+<p>
+ These tools are designed to "just get the job done", and receive
+ minimal documentation here, in the hopes that they will help stimulate further
+ submissions to this library.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../toolkit.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../toolkit.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="internals1.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/using_udt.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/using_udt.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,51 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Use with User Defined Floating-Point Types</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../index.html" title="Math Toolkit">
+<link rel="up" href="../index.html" title="Math Toolkit">
+<link rel="prev" href="toolkit/internals2/test_data.html" title="Graphing, Profiling, and Generating Test Data for Special Functions">
+<link rel="next" href="using_udt/use_ntl.html" title="Using With NTL - a High-Precision Floating-Point Library">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="toolkit/internals2/test_data.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="using_udt/use_ntl.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="math_toolkit.using_udt"></a><a href="using_udt.html" title="Use with User Defined Floating-Point Types"> Use with User Defined Floating-Point
+ Types</a>
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="using_udt/use_ntl.html"> Using With NTL - a High-Precision
+ Floating-Point Library</a></span></dt>
+<dt><span class="section"><a href="using_udt/concepts.html"> Conceptual Requirements
+ for Real Number Types</a></span></dt>
+<dt><span class="section"><a href="using_udt/dist_concept.html"> Conceptual Requirements
+ for Distribution Types</a></span></dt>
+<dt><span class="section"><a href="using_udt/archetypes.html"> Conceptual Archetypes
+ and Testing</a></span></dt>
+</dl></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="toolkit/internals2/test_data.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="using_udt/use_ntl.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/using_udt/archetypes.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/using_udt/archetypes.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,180 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Conceptual Archetypes and Testing</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../using_udt.html" title="Use with User Defined Floating-Point Types">
+<link rel="prev" href="dist_concept.html" title="Conceptual Requirements for Distribution Types">
+<link rel="next" href="../policy.html" title="Policies">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="dist_concept.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_udt.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../policy.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.using_udt.archetypes"></a><a href="archetypes.html" title="Conceptual Archetypes and Testing"> Conceptual Archetypes
+ and Testing</a>
+</h3></div></div></div>
+<p>
+ There are several concept archetypes available:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">concepts</span><span class="special">/</span><span class="identifier">std_real_concept</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span>
+<span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+<span class="keyword">namespace</span> <span class="identifier">concepts</span><span class="special">{</span>
+
+<span class="keyword">class</span> <span class="identifier">std_real_concept</span><span class="special">;</span>
+
+<span class="special">}}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ <code class="computeroutput"><span class="identifier">std_real_concept</span></code> is an archetype
+ for the built-in Real types.
+ </p>
+<p>
+ The main purpose in providing this type is to verify that standard library
+ functions are found via a using declaration - bringing those functions into
+ the current scope - and not just because they happen to be in global scope.
+ </p>
+<p>
+ In order to ensure that a call to say <code class="computeroutput"><span class="identifier">pow</span></code>
+ can be found either via argument dependent lookup, or failing that then in
+ the std namespace: all calls to standard library functions are unqualified,
+ with the std:: versions found via a using declaration to make them visible
+ in the current scope. Unfortunately it's all to easy to forget the using
+ declaration, and call the double version of the function that happens to
+ be in the global scope by mistake.
+ </p>
+<p>
+ For example if the code calls ::pow rather than std::pow, the code will cleanly
+ compile, but truncation of long doubles to double will cause a significant
+ loss of precision. In contrast a template instantiated with std_real_concept
+ will <span class="bold"><strong>only</strong></span> compile if the all the standard
+ library functions used have been brought into the current scope with a using
+ declaration.
+ </p>
+<p>
+ There is a test program libs/math/test/std_real_concept_check.cpp
+ that instantiates every template in this library with type <code class="computeroutput"><span class="identifier">std_real_concept</span></code> to verify it's usage of
+ standard library functions.
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">concepts</span><span class="special">/</span><span class="identifier">real_concept</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span>
+<span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+<span class="keyword">namespace</span> <span class="identifier">concepts</span><span class="special">{</span>
+
+<span class="keyword">class</span> <span class="identifier">real_concept</span><span class="special">;</span>
+
+<span class="special">}}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ <code class="computeroutput"><span class="identifier">real_concept</span></code> is an archetype
+ for user defined real types,
+ it declares it's standard library functions in it's own namespace: these
+ will only be found if they are called unqualified allowing argument dependent
+ lookup to locate them. In addition this type is useable at runtime: this
+ allows code that would not otherwise be exercised by the built-in floating
+ point types to be tested. There is no std::numeric_limits&lt;&gt; support
+ for this type, since this is not a conceptual requirement for RealType's.
+ </p>
+<p>
+ NTL RR is an example of a type meeting the requirements that this type models,
+ but note that use of a thin wrapper class is required: refer to <a href="use_ntl.html" title="Using With NTL - a High-Precision Floating-Point Library">"Using
+ With NTL - a High-Precision Floating-Point Library"</a>.
+ </p>
+<p>
+ There is no specific test case for type <code class="computeroutput"><span class="identifier">real_concept</span></code>,
+ instead, since this type is usable at runtime, each individual test case
+ as well as testing <code class="computeroutput"><span class="keyword">float</span></code>, <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">long</span>
+ <span class="keyword">double</span></code>, also tests <code class="computeroutput"><span class="identifier">real_concept</span></code>.
+ </p>
+<p>
+
+</p>
+<pre class="programlisting">
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">concepts</span><span class="special">/</span><span class="identifier">distribution</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
+<p>
+ </p>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span>
+<span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
+<span class="keyword">namespace</span> <span class="identifier">concepts</span><span class="special">{</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">distribution_archetype</span><span class="special">;</span>
+
+<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Distribution</span><span class="special">&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">DistributionConcept</span><span class="special">;</span>
+
+<span class="special">}}}</span> <span class="comment">// namespaces
+</span></pre>
+<p>
+ The class template <code class="computeroutput"><span class="identifier">distribution_archetype</span></code>
+ is a model of the <a href="dist_concept.html" title="Conceptual Requirements for Distribution Types">Distribution
+ concept</a>.
+ </p>
+<p>
+ The class template <code class="computeroutput"><span class="identifier">DistributionConcept</span></code>
+ is a <a href="../../../../../../../libs/concept_check/index.html" target="_top">concept checking
+ class</a> for distribution types.
+ </p>
+<p>
+ The test program distribution_concept_check.cpp
+ is responsible for using <code class="computeroutput"><span class="identifier">DistributionConcept</span></code>
+ to verify that all the distributions in this library conform to the Distribution concept.
+ </p>
+<p>
+ The class template <code class="computeroutput"><span class="identifier">DistributionConcept</span></code>
+ verifies the existence (but not proper function) of the non-member accessors
+ required by the <a href="dist_concept.html" title="Conceptual Requirements for Distribution Types">Distribution
+ concept</a>. These are checked by calls like
+ </p>
+<p>
+ v = pdf(dist, x); // (Result v is ignored).
+ </p>
+<p>
+ And in addition, those that accept two arguments do the right thing when
+ the arguments are of different types (the result type is always the same
+ as the distribution's value_type). (This is implemented by some additional
+ forwarding-functions in derived_accessors.hpp, so that there is no need for
+ any code changes. Likewise boilerplate versions of the hazard/chf/coefficient_of_variation
+ functions are implemented in there too.)
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="dist_concept.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_udt.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="../policy.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/using_udt/concepts.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/using_udt/concepts.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,1292 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Conceptual Requirements for Real Number Types</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../using_udt.html" title="Use with User Defined Floating-Point Types">
+<link rel="prev" href="use_ntl.html" title="Using With NTL - a High-Precision Floating-Point Library">
+<link rel="next" href="dist_concept.html" title="Conceptual Requirements for Distribution Types">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="use_ntl.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_udt.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="dist_concept.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.using_udt.concepts"></a><a href="concepts.html" title="Conceptual Requirements for Real Number Types"> Conceptual Requirements
+ for Real Number Types</a>
+</h3></div></div></div>
+<p>
+ The functions, and statistical distributions in this library can be used
+ with any type <span class="emphasis"><em>RealType</em></span> that meets the conceptual requirements
+ given below. All the built in floating point types will meet these requirements.
+ User defined types that meet the requirements can also be used. For example,
+ with a thin wrapper class
+ one of the types provided with NTL (RR)
+ can be used. Submissions of binding to other extended precision types would
+ also be most welcome!
+ </p>
+<p>
+ The guiding principal behind these requirements, is that a <span class="emphasis"><em>RealType</em></span>
+ behaves just like a built in floating point type.
+ </p>
+<a name="math_toolkit.using_udt.concepts.basic_arithmetic_requirements"></a><h5>
+<a name="id733812"></a>
+ <a href="concepts.html#math_toolkit.using_udt.concepts.basic_arithmetic_requirements">Basic
+ Arithmetic Requirements</a>
+ </h5>
+<p>
+ These requirements are common to all of the functions in this library.
+ </p>
+<p>
+ In the following table <span class="emphasis"><em>r</em></span> is an object of type <code class="computeroutput"><span class="identifier">RealType</span></code>, <span class="emphasis"><em>cr</em></span> and
+ <span class="emphasis"><em>cr2</em></span> are objects of type <code class="computeroutput"><span class="keyword">const</span>
+ <span class="identifier">RealType</span></code>, and <span class="emphasis"><em>ca</em></span>
+ is an object of type <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">arithmetic</span><span class="special">-</span><span class="identifier">type</span></code> (arithmetic types include all the
+ built in integers and floating point types).
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Expression
+ </p>
+ </th>
+<th>
+ <p>
+ Result Type
+ </p>
+ </th>
+<th>
+ <p>
+ Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">RealType</span><span class="special">(</span><span class="identifier">cr</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ RealType is copy constructible.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">RealType</span><span class="special">(</span><span class="identifier">ca</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ RealType is copy constructible from the arithmetic types.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">r</span> <span class="special">=</span>
+ <span class="identifier">cr</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType&amp;
+ </p>
+ </td>
+<td>
+ <p>
+ Assignment operator.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">r</span> <span class="special">=</span>
+ <span class="identifier">ca</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType&amp;
+ </p>
+ </td>
+<td>
+ <p>
+ Assignment operator from the arithmetic types.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">r</span> <span class="special">+=</span>
+ <span class="identifier">cr</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType&amp;
+ </p>
+ </td>
+<td>
+ <p>
+ Adds cr to r.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">r</span> <span class="special">+=</span>
+ <span class="identifier">ca</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType&amp;
+ </p>
+ </td>
+<td>
+ <p>
+ Adds ar to r.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">r</span> <span class="special">-=</span>
+ <span class="identifier">cr</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType&amp;
+ </p>
+ </td>
+<td>
+ <p>
+ Subtracts cr from r.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">r</span> <span class="special">-=</span>
+ <span class="identifier">ca</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType&amp;
+ </p>
+ </td>
+<td>
+ <p>
+ Subtracts ca from r.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">r</span> <span class="special">*=</span>
+ <span class="identifier">cr</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType&amp;
+ </p>
+ </td>
+<td>
+ <p>
+ Multiplies r by cr.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">r</span> <span class="special">*=</span>
+ <span class="identifier">ca</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType&amp;
+ </p>
+ </td>
+<td>
+ <p>
+ Multiplies r by ca.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">r</span> <span class="special">/=</span>
+ <span class="identifier">cr</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType&amp;
+ </p>
+ </td>
+<td>
+ <p>
+ Divides r by cr.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">r</span> <span class="special">/=</span>
+ <span class="identifier">ca</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType&amp;
+ </p>
+ </td>
+<td>
+ <p>
+ Divides r by ca.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special">-</span><span class="identifier">r</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Unary Negation.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="special">+</span><span class="identifier">r</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType&amp;
+ </p>
+ </td>
+<td>
+ <p>
+ Identity Operation.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">+</span>
+ <span class="identifier">cr2</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Binary Addition
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">+</span>
+ <span class="identifier">ca</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Binary Addition
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">ca</span> <span class="special">+</span>
+ <span class="identifier">cr</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Binary Addition
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">-</span>
+ <span class="identifier">cr2</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Binary Subtraction
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">-</span>
+ <span class="identifier">ca</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Binary Subtraction
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">ca</span> <span class="special">-</span>
+ <span class="identifier">cr</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Binary Subtraction
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">*</span>
+ <span class="identifier">cr2</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Binary Multiplication
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">*</span>
+ <span class="identifier">ca</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Binary Multiplication
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">ca</span> <span class="special">*</span>
+ <span class="identifier">cr</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Binary Multiplication
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">/</span>
+ <span class="identifier">cr2</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Binary Subtraction
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">/</span>
+ <span class="identifier">ca</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Binary Subtraction
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">ca</span> <span class="special">/</span>
+ <span class="identifier">cr</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Binary Subtraction
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">==</span>
+ <span class="identifier">cr2</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Equality Comparison
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">==</span>
+ <span class="identifier">ca</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Equality Comparison
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">ca</span> <span class="special">==</span>
+ <span class="identifier">cr</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Equality Comparison
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">!=</span>
+ <span class="identifier">cr2</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Inequality Comparison
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">!=</span>
+ <span class="identifier">ca</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Inequality Comparison
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">ca</span> <span class="special">!=</span>
+ <span class="identifier">cr</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Inequality Comparison
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">&lt;=</span>
+ <span class="identifier">cr2</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Less than equal to.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">&lt;=</span>
+ <span class="identifier">ca</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Less than equal to.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">ca</span> <span class="special">&lt;=</span>
+ <span class="identifier">cr</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Less than equal to.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">&gt;=</span>
+ <span class="identifier">cr2</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Greater than equal to.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">&gt;=</span>
+ <span class="identifier">ca</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Greater than equal to.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">ca</span> <span class="special">&gt;=</span>
+ <span class="identifier">cr</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Greater than equal to.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">&lt;</span>
+ <span class="identifier">cr2</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Less than comparison.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">&lt;</span>
+ <span class="identifier">ca</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Less than comparison.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">ca</span> <span class="special">&lt;</span>
+ <span class="identifier">cr</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Less than comparison.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">&gt;</span>
+ <span class="identifier">cr2</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Greater than comparison.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cr</span> <span class="special">&gt;</span>
+ <span class="identifier">ca</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Greater than comparison.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">ca</span> <span class="special">&gt;</span>
+ <span class="identifier">cr</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ bool
+ </p>
+ </td>
+<td>
+ <p>
+ Greater than comparison.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">::</span><span class="identifier">digits</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;()</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ int
+ </p>
+ </td>
+<td>
+ <p>
+ The number of digits in the significand of RealType.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">::</span><span class="identifier">max_value</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;()</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ The largest representable number by type RealType.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">::</span><span class="identifier">min_value</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;()</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ The smallest representable number by type RealType.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">::</span><span class="identifier">log_max_value</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;()</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ The natural logarithm of the largest representable number by type
+ RealType.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">::</span><span class="identifier">log_min_value</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;()</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ The natural logarithm of the smallest representable number by type
+ RealType.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">::</span><span class="identifier">epsilon</span><span class="special">&lt;</span><span class="identifier">RealType</span><span class="special">&gt;()</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ The machine epsilon of RealType.
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<p>
+ Note that:
+ </p>
+<div class="orderedlist"><ol type="1">
+<li>
+ The functions <code class="computeroutput"><span class="identifier">log_max_value</span></code>
+ and <code class="computeroutput"><span class="identifier">log_min_value</span></code> can be
+ synthesised from the others, and so no explicit specialisation is required.
+ </li>
+<li>
+ The function <code class="computeroutput"><span class="identifier">epsilon</span></code> can
+ be synthesised from the others, so no explicit specialisation is required
+ provided the precision of RealType does not vary at runtime (see the header
+ boost/math/tools/ntl.hpp
+ for an example where the precision does vary at runtime).
+ </li>
+<li>
+ The functions <code class="computeroutput"><span class="identifier">digits</span></code>,
+ <code class="computeroutput"><span class="identifier">max_value</span></code> and <code class="computeroutput"><span class="identifier">min_value</span></code>, all get synthesised automatically
+ from <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span></code>. However, if <code class="computeroutput"><span class="identifier">numeric_limits</span></code> is not specialised for
+ type RealType, then you will get a compiler error when code tries to use
+ these functions, <span class="emphasis"><em>unless</em></span> you explicitly specialise
+ them. For example if the precision of RealType varies at runtime, then
+ <code class="computeroutput"><span class="identifier">numeric_limits</span></code> support
+ may not be appropriate, see boost/math/tools/ntl.hpp
+ for examples.
+ </li>
+</ol></div>
+<div class="warning"><table border="0" summary="Warning">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../../doc/html/images/warning.png"></td>
+<th align="left">Warning</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+ If <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;&gt;</span></code>
+ is <span class="bold"><strong>not specialized</strong></span> for type <span class="emphasis"><em>RealType</em></span>
+ then the default float precision of 6 decimal digits will be used by other
+ Boost programs including:
+ </p>
+<p>
+ Boost.Test: giving misleading error messages like
+ </p>
+<p>
+ <span class="emphasis"><em>"difference between {9.79796} and {9.79796} exceeds 5.42101e-19%".</em></span>
+ </p>
+<p>
+ Boost.LexicalCast and Boost.Serialization when converting the number to
+ a string, causing potentially serious loss of accuracy on output.
+ </p>
+<p>
+ Although it might seem obvious that RealType should require <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span></code> to be specialized, this
+ is not sensible for <code class="computeroutput"><span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span></code>
+ and similar classes where the number of digits is a runtime parameter (where
+ as for <code class="computeroutput"><span class="identifier">numeric_limits</span></code> it
+ has to be fixed at compile time).
+ </p>
+</td></tr>
+</table></div>
+<a name="math_toolkit.using_udt.concepts.standard_library_support_requirements"></a><h5>
+<a name="id736880"></a>
+ <a href="concepts.html#math_toolkit.using_udt.concepts.standard_library_support_requirements">Standard
+ Library Support Requirements</a>
+ </h5>
+<p>
+ Many (though not all) of the functions in this library make calls to standard
+ library functions, the following table summarises the requirements. Note
+ that most of the functions in this library will only call a small subset
+ of the functions listed here, so if in doubt whether a user defined type
+ has enough standard library support to be useable the best advise is to try
+ it and see!
+ </p>
+<p>
+ In the following table <span class="emphasis"><em>r</em></span> is an object of type <code class="computeroutput"><span class="identifier">RealType</span></code>, <span class="emphasis"><em>cr1</em></span> and
+ <span class="emphasis"><em>cr2</em></span> are objects of type <code class="computeroutput"><span class="keyword">const</span>
+ <span class="identifier">RealType</span></code>, and <span class="emphasis"><em>i</em></span>
+ is an object of type <code class="computeroutput"><span class="keyword">int</span></code>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Expression
+ </p>
+ </th>
+<th>
+ <p>
+ Result Type
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">fabs</span><span class="special">(</span><span class="identifier">cr1</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">abs</span><span class="special">(</span><span class="identifier">cr1</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">ceil</span><span class="special">(</span><span class="identifier">cr1</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">floor</span><span class="special">(</span><span class="identifier">cr1</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">exp</span><span class="special">(</span><span class="identifier">cr1</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">pow</span><span class="special">(</span><span class="identifier">cr1</span><span class="special">,</span>
+ <span class="identifier">cr2</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">sqrt</span><span class="special">(</span><span class="identifier">cr1</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">log</span><span class="special">(</span><span class="identifier">cr1</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">frexp</span><span class="special">(</span><span class="identifier">cr1</span><span class="special">,</span>
+ <span class="special">&amp;</span><span class="identifier">i</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">ldexp</span><span class="special">(</span><span class="identifier">cr1</span><span class="special">,</span>
+ <span class="identifier">i</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">cos</span><span class="special">(</span><span class="identifier">cr1</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">sin</span><span class="special">(</span><span class="identifier">cr1</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">asin</span><span class="special">(</span><span class="identifier">cr1</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">tan</span><span class="special">(</span><span class="identifier">cr1</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ <code class="computeroutput"><span class="identifier">atan</span><span class="special">(</span><span class="identifier">cr1</span><span class="special">)</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+<p>
+ Note that the table above lists only those standard library functions known
+ to be used (or likely to be used in the near future) by this library. The
+ following functions: <code class="computeroutput"><span class="identifier">acos</span></code>,
+ <code class="computeroutput"><span class="identifier">atan2</span></code>, <code class="computeroutput"><span class="identifier">fmod</span></code>,
+ <code class="computeroutput"><span class="identifier">cosh</span></code>, <code class="computeroutput"><span class="identifier">sinh</span></code>,
+ <code class="computeroutput"><span class="identifier">tanh</span></code>, <code class="computeroutput"><span class="identifier">modf</span></code>
+ and <code class="computeroutput"><span class="identifier">log10</span></code> are not currently
+ used, but may be if further special functions are added.
+ </p>
+<p>
+ In addition, for efficient and accurate results, a <a href="../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a> is highly desirable. You may be able to adapt an existing
+ approximation from boost/math/special_functions/lanczos.hpp
+ or libs/math/tools/ntl_rr_lanczos.hpp:
+ you will need change static_cast's to lexical_cast's, and the constants to
+ <span class="emphasis"><em>strings</em></span> (in order to ensure the coefficients aren't
+ truncated to long double) and then specialise <code class="computeroutput"><span class="identifier">lanczos_traits</span></code>
+ for type T. Otherwise you may have to hack libs/math/tools/lanczos_generator.cpp
+ to find a suitable approximation for your RealType. The code will still compile
+ if you don't do this, but both accuracy and efficiency will be greatly compromised
+ in any function that makes use of the gamma/beta/erf family of functions.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="use_ntl.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_udt.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="dist_concept.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/using_udt/dist_concept.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/using_udt/dist_concept.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,392 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Conceptual Requirements for Distribution Types</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../using_udt.html" title="Use with User Defined Floating-Point Types">
+<link rel="prev" href="concepts.html" title="Conceptual Requirements for Real Number Types">
+<link rel="next" href="archetypes.html" title="Conceptual Archetypes and Testing">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="concepts.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_udt.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="archetypes.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.using_udt.dist_concept"></a><a href="dist_concept.html" title="Conceptual Requirements for Distribution Types"> Conceptual Requirements
+ for Distribution Types</a>
+</h3></div></div></div>
+<p>
+ A <span class="emphasis"><em>DistributionType</em></span> is a type that implements the following
+ conceptual requirements, and encapsulates a statistical distribution.
+ </p>
+<p>
+ Please note that this documentation should not be used as a substitute for
+ the reference documentation,
+ and tutorial of the statistical
+ distributions.
+ </p>
+<p>
+ In the following table, <span class="emphasis"><em>d</em></span> is an object of type <code class="computeroutput"><span class="identifier">DistributionType</span></code>, <span class="emphasis"><em>cd</em></span>
+ is an object of type <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">DistributionType</span></code> and <span class="emphasis"><em>cr</em></span>
+ is an object of a type convertible to <code class="computeroutput"><span class="identifier">RealType</span></code>.
+ </p>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ <p>
+ Expression
+ </p>
+ </th>
+<th>
+ <p>
+ Result Type
+ </p>
+ </th>
+<th>
+ <p>
+ Notes
+ </p>
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ <p>
+ DistributionType::value_type
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ The real-number type <span class="emphasis"><em>RealType</em></span> upon which the
+ distribution operates.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ DistributionType::policy_type
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ The Policy to use when
+ evaluating functions that depend on this distribution.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ d = cd
+ </p>
+ </td>
+<td>
+ <p>
+ Distribution&amp;
+ </p>
+ </td>
+<td>
+ <p>
+ Distribution types are assignable.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ Distribution(cd)
+ </p>
+ </td>
+<td>
+ <p>
+ Distribution
+ </p>
+ </td>
+<td>
+ <p>
+ Distribution types are copy constructible.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ pdf(cd, cr)
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the PDF of the distribution.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf(cd, cr)
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the CDF of the distribution.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ cdf(complement(cd, cr))
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the complement of the CDF of the distribution, the same as:
+ <code class="computeroutput"><span class="number">1</span><span class="special">-</span><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">cd</span><span class="special">,</span> <span class="identifier">cr</span><span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile(cd, cr)
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the quantile of the distribution.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ quantile(complement(cd, cr))
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the quantile of the distribution, starting from the complement
+ of the probability, the same as: <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">cd</span><span class="special">,</span> <span class="number">1</span><span class="special">-</span><span class="identifier">cr</span><span class="special">)</span></code>
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ chf(cd, cr)
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the cumulative hazard function of the distribution.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ hazard(cd, cr)
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the hazard function of the distribution.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis(cd)
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the kurtosis of the distribution.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ kurtosis_excess(cd)
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the kurtosis excess of the distribution.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mean(cd)
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the mean of the distribution.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ mode(cd)
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the mode of the distribution.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ skewness(cd)
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the skewness of the distribution.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ standard_deviation(cd)
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the standard deviation of the distribution.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
+ variance(cd)
+ </p>
+ </td>
+<td>
+ <p>
+ RealType
+ </p>
+ </td>
+<td>
+ <p>
+ Returns the variance of the distribution.
+ </p>
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="concepts.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_udt.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="archetypes.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/using_udt/use_ntl.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/using_udt/use_ntl.html 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -0,0 +1,64 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Using With NTL - a High-Precision Floating-Point Library</title>
+<link rel="stylesheet" href="../../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_2006-12-17_0120">
+<link rel="start" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../using_udt.html" title="Use with User Defined Floating-Point Types">
+<link rel="prev" href="../using_udt.html" title="Use with User Defined Floating-Point Types">
+<link rel="next" href="concepts.html" title="Conceptual Requirements for Real Number Types">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../using_udt.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_udt.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="concepts.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.using_udt.use_ntl"></a><a href="use_ntl.html" title="Using With NTL - a High-Precision Floating-Point Library"> Using With NTL - a High-Precision
+ Floating-Point Library</a>
+</h3></div></div></div>
+<p>
+ The special functions and tools in this library can be used with <a href="http://shoup.net/ntl/doc/RR.txt" target="_top">NTL::RR
+ (an arbitrary precision number type)</a>, via the bindings in boost/math/bindings/rr.hpp.
+ <a href="http://shoup.net/ntl/" target="_top">See also NTL: A Library for doing Number
+ Theory by Victor Shoup</a>
+ </p>
+<p>
+ Unfortunately <code class="computeroutput"><span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span></code> doesn't quite satisfy our conceptual
+ requirements, so there is a very thin wrapper class <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">ntl</span><span class="special">::</span><span class="identifier">RR</span></code> defined in boost/math/bindings/rr.hpp
+ that you should use in place of <code class="computeroutput"><span class="identifier">NTL</span><span class="special">::</span><span class="identifier">RR</span></code>. The
+ class is intended to be a drop-in replacement for the "real" NTL::RR
+ that adds some syntactic sugar to keep this library happy, plus some of the
+ standard library functions not implemented in NTL.
+ </p>
+<p>
+ Finally there is a high precision <a href="../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a> suitable for use with <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">ntl</span><span class="special">::</span><span class="identifier">RR</span></code>, used at 1000-bit precision in libs/math/tools/ntl_rr_lanczos.hpp.
+ The approximation has a theoretical precision of &gt; 90 decimal digits,
+ and an experimental precision of &gt; 100 decimal digits. To use that approximation,
+ just include that header before any of the special function headers (if you
+ don't use it, you'll get a slower, but fully generic implementation for all
+ of the gamma-like functions).
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../using_udt.html"><img src="../../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_udt.html"><img src="../../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="concepts.html"><img src="../../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Modified: trunk/libs/math/doc/sf_and_dist/math.qbk
==============================================================================
--- trunk/libs/math/doc/sf_and_dist/math.qbk (original)
+++ trunk/libs/math/doc/sf_and_dist/math.qbk 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -206,7 +206,7 @@
 [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 __user_error_handling [link math_toolkit.policy.pol_tutorial.user_def_err_pol user error handling]]
 
 [def __usual_accessors __cdf, __pdf, __quantile, __hazard,
    __chf, __mean, __median, __mode, __variance, __sd, __skewness,

Modified: trunk/libs/math/doc/sf_and_dist/policy.qbk
==============================================================================
--- trunk/libs/math/doc/sf_and_dist/policy.qbk (original)
+++ trunk/libs/math/doc/sf_and_dist/policy.qbk 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -113,7 +113,7 @@
 should be replaced with the value of ['val].
 
 There is more information on user-defined error handlers in
-the [link math_toolkit.policy.pol_tutorial.user_defined_error_policies
+the [link math_toolkit.policy.pol_tutorial.user_def_err_pol
 tutorial here].
 
 [h4 Kinds of Error Raised]

Modified: trunk/libs/math/doc/sf_and_dist/policy_tutorial.qbk
==============================================================================
--- trunk/libs/math/doc/sf_and_dist/policy_tutorial.qbk (original)
+++ trunk/libs/math/doc/sf_and_dist/policy_tutorial.qbk 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -320,7 +320,7 @@
 
 [endsect][/section:namespace_policies Setting Policies at Namespace or Translation Unit Scope]
 
-[section:user_defined_error_policies Calling User Defined Error Handlers]
+[section:user_def_err_pol Calling User Defined Error Handlers]
 
 [import ../../example/policy_eg_8.cpp]
 
@@ -330,7 +330,7 @@
 
 [policy_eg_9]
 
-[endsect][/section:user_defined_error_policies Calling User Defined Error Handlers]
+[endsect][/section:user_def_err_pol Calling User Defined Error Handlers]
 
 [section:understand_dis_quant Understanding Quantiles of Discrete Distributions]
 

Modified: trunk/libs/math/doc/sf_and_dist/roadmap.qbk
==============================================================================
--- trunk/libs/math/doc/sf_and_dist/roadmap.qbk (original)
+++ trunk/libs/math/doc/sf_and_dist/roadmap.qbk 2007-10-09 07:30:19 EDT (Tue, 09 Oct 2007)
@@ -57,6 +57,11 @@
 on error rates.
 * Provide sufficient docs for people to be able to find their way around the library.
 
+SVN Revisions:
+
+Sandbox revision merged to trunk: 39833.
+Trunk revision: 39833.
+
 ]
 [/
   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