Boost-Commit mailing page: [Boost-commit] svn:boost r39835 - in trunk/libs/math/doc/sf_and_dist: . distributions html html/math_toolkit html/math_toolkit/backgrounders html/math_toolkit/dist html/math_toolkit/dist/dist_ref html/math_toolkit/dist/dist_ref/dists html/math_toolkit/dist/stat_tut html/math_toolkit/dist/stat_tut/weg html/math_toolkit/dist/stat_tut/weg/binom_eg html/math_toolkit/dist/stat_tut/weg/cs_eg html/math_toolkit/dist/stat_tut/weg/find_eg html/math_toolkit/dist/stat_tut/weg/neg_binom_eg html/math_toolkit/dist/stat_tut/weg/normal_example html/math_toolkit/dist/stat_tut/weg/st_eg html/math_toolkit/main_overview html/math_toolkit/perf html/math_toolkit/policy html/math_toolkit/policy/pol_ref html/math_toolkit/policy/pol_tutorial html/math_toolkit/special html/math_toolkit/special/bessel html/math_toolkit/special/ellint html/math_toolkit/special/factorials html/math_toolkit/special/inv_hyper html/math_toolkit/special/powers html/math_toolkit/special/sf_beta html/math_toolkit/special/sf_erf html/math_toolkit/special/sf_gamma html/math_toolkit/special/sf_poly html/math_toolkit/special/sinc html/math_toolkit/status html/math_toolkit/toolkit html/math_toolkit/toolkit/internals1 html/math_toolkit/toolkit/internals2 html/math_toolkit/using

Date view	Thread view	Subject view	Author view

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

Next message: anthony_at_[hidden]: "[Boost-commit] svn:boost r39836 - trunk/boost/thread/pthread"
Previous message: john_at_[hidden]: "[Boost-commit] svn:boost r39834 - in trunk/boost/math: concepts special_functions tools"

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">
+John Maddock
+</h3></div>
+<div class="author"><h3 class="author">
+Paul A. Bristow
+</h3></div>
+<div class="author"><h3 class="author">
+Hubert Holin
+</h3></div>
+<div class="author"><h3 class="author">
+Xiaogang Zhang
+</h3></div>
+</div></div>
+<div>Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</div>
+<div><div class="legalnotice">
+<a name="id489799"></a>
+ 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)
+ 
+</div></div>
+</div>
+<hr>
+</div>
+<div class="toc">
+Table of Contents
+<dl>
+<dt> Overview</dt>
+<dd><dl>
+<dt> About the Math Toolkit</dt>
+<dt> Navigation</dt>
+<dt><a href="math_toolkit/main_overview/directories.html"> Directory and
+ File Structure</a></dt>
+<dt> Namespaces</dt>
+<dt><a href="math_toolkit/main_overview/result_type.html"> Calculation
+ of the Type of the Result</a></dt>
+<dt> Error Handling</dt>
+<dt><a href="math_toolkit/main_overview/pol_overview.html"> Configuration
+ and Policies</a></dt>
+<dt> Thread Safety</dt>
+<dt> Performance</dt>
+<dt><a href="math_toolkit/main_overview/history1.html"> History and What's
+ New</a></dt>
+<dt><a href="math_toolkit/main_overview/contact.html"> Contact Info and
+ Support</a></dt>
+</dl></dd>
+<dt> Statistical Distributions and Functions</dt>
+<dd><dl>
+<dt><a href="math_toolkit/dist/stat_tut.html"> Statistical Distributions
+ Tutorial</a></dt>
+<dd><dl>
+<dt> Overview</dt>
+<dt> Worked Examples</dt>
+<dd><dl>
+<dt><a href="math_toolkit/dist/stat_tut/weg/dist_construct_eg.html">
+ Distribution Construction Example</a></dt>
+<dt><a href="math_toolkit/dist/stat_tut/weg/st_eg.html"> Student's
+ t Distribution Examples</a></dt>
+<dt><a href="math_toolkit/dist/stat_tut/weg/cs_eg.html"> Chi Squared
+ Distribution Examples</a></dt>
+<dt><a href="math_toolkit/dist/stat_tut/weg/f_eg.html"> F Distribution
+ Examples</a></dt>
+<dt><a href="math_toolkit/dist/stat_tut/weg/binom_eg.html"> Binomial
+ Distribution Examples</a></dt>
+<dt><a href="math_toolkit/dist/stat_tut/weg/neg_binom_eg.html"> Negative
+ Binomial Distribution Examples</a></dt>
+<dt><a href="math_toolkit/dist/stat_tut/weg/normal_example.html"> Normal
+ Distribution Examples</a></dt>
+<dt><a href="math_toolkit/dist/stat_tut/weg/error_eg.html"> Error Handling
+ Example</a></dt>
+<dt><a href="math_toolkit/dist/stat_tut/weg/find_eg.html"> Find Location
+ and Scale Examples</a></dt>
+<dt><a href="math_toolkit/dist/stat_tut/weg/nag_library.html"> Comparison
+ with C, R, FORTRAN-style Free Functions</a></dt>
+</dl></dd>
+<dt><a href="math_toolkit/dist/stat_tut/variates.html"> Random Variates
+ and Distribution Parameters</a></dt>
+<dt><a href="math_toolkit/dist/stat_tut/dist_params.html"> Discrete Probability
+ Distributions</a></dt>
+</dl></dd>
+<dt><a href="math_toolkit/dist/dist_ref.html"> Statistical Distributions
+ Reference</a></dt>
+<dd><dl>
+<dt> Non-Member Properties</dt>
+<dt> Distributions</dt>
+<dd><dl>
+<dt><a href="math_toolkit/dist/dist_ref/dists/bernoulli_dist.html">
+ Bernoulli Distribution</a></dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/beta_dist.html"> Beta
+ Distribution</a></dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/binomial_dist.html">
+ Binomial Distribution</a></dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/cauchy_dist.html"> Cauchy-Lorentz
+ Distribution</a></dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/chi_squared_dist.html">
+ Chi Squared Distribution</a></dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/exp_dist.html"> Exponential
+ Distribution</a></dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/extreme_dist.html"> Extreme
+ Value Distribution</a></dt>
+<dt> F Distribution</dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/gamma_dist.html"> Gamma
+ (and Erlang) Distribution</a></dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/lognormal_dist.html">
+ Log Normal Distribution</a></dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/negative_binomial_dist.html">
+ Negative Binomial Distribution</a></dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/normal_dist.html"> Normal
+ (Gaussian) Distribution</a></dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/pareto.html"> Pareto
+ Distribution</a></dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/poisson_dist.html"> Poisson
+ Distribution</a></dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/rayleigh.html"> Rayleigh
+ Distribution</a></dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/students_t_dist.html">
+ Students t Distribution</a></dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/triangular_dist.html">
+ Triangular Distribution</a></dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/weibull.html"> Weibull
+ Distribution</a></dt>
+<dt><a href="math_toolkit/dist/dist_ref/dists/uniform_dist.html"> Uniform
+ Distribution</a></dt>
+</dl></dd>
+<dt><a href="math_toolkit/dist/dist_ref/dist_algorithms.html"> Distribution
+ Algorithms</a></dt>
+</dl></dd>
+<dt> Extras/Future Directions</dt>
+</dl></dd>
+<dt> Special Functions</dt>
+<dd><dl>
+<dt> Gamma Functions</dt>
+<dd><dl>
+<dt> Gamma</dt>
+<dt> Log Gamma</dt>
+<dt> Digamma</dt>
+<dt><a href="math_toolkit/special/sf_gamma/gamma_ratios.html"> Ratios
+ of Gamma Functions</a></dt>
+<dt><a href="math_toolkit/special/sf_gamma/igamma.html"> Incomplete Gamma
+ Functions</a></dt>
+<dt><a href="math_toolkit/special/sf_gamma/igamma_inv.html"> Incomplete
+ Gamma Function Inverses</a></dt>
+<dt><a href="math_toolkit/special/sf_gamma/gamma_derivatives.html"> Derivative
+ of the Incomplete Gamma Function</a></dt>
+</dl></dd>
+<dt><a href="math_toolkit/special/factorials.html"> Factorials and Binomial
+ Coefficients</a></dt>
+<dd><dl>
+<dt> Factorial</dt>
+<dt><a href="math_toolkit/special/factorials/sf_double_factorial.html">
+ Double Factorial</a></dt>
+<dt><a href="math_toolkit/special/factorials/sf_rising_factorial.html">
+ Rising Factorial</a></dt>
+<dt><a href="math_toolkit/special/factorials/sf_falling_factorial.html">
+ Falling Factorial</a></dt>
+<dt><a href="math_toolkit/special/factorials/sf_binomial.html"> Binomial
+ Coefficients</a></dt>
+</dl></dd>
+<dt> Beta Functions</dt>
+<dd><dl>
+<dt> Beta</dt>
+<dt><a href="math_toolkit/special/sf_beta/ibeta_function.html"> Incomplete
+ Beta Functions</a></dt>
+<dt><a href="math_toolkit/special/sf_beta/ibeta_inv_function.html"> The
+ Incomplete Beta Function Inverses</a></dt>
+<dt><a href="math_toolkit/special/sf_beta/beta_derivative.html"> Derivative
+ of the Incomplete Beta Function</a></dt>
+</dl></dd>
+<dt> Error Functions</dt>
+<dd><dl>
+<dt><a href="math_toolkit/special/sf_erf/error_function.html"> Error
+ Functions</a></dt>
+<dt><a href="math_toolkit/special/sf_erf/error_inv.html"> Error Function
+ Inverses</a></dt>
+</dl></dd>
+<dt> Polynomials</dt>
+<dd><dl>
+<dt><a href="math_toolkit/special/sf_poly/legendre.html"> Legendre (and
+ Associated) Polynomials</a></dt>
+<dt><a href="math_toolkit/special/sf_poly/laguerre.html"> Laguerre (and
+ Associated) Polynomials</a></dt>
+<dt> Hermite Polynomials</dt>
+<dt> Spherical Harmonics</dt>
+</dl></dd>
+<dt> Bessel Functions</dt>
+<dd><dl>
+<dt><a href="math_toolkit/special/bessel/bessel_over.html"> Bessel Function
+ Overview</a></dt>
+<dt><a href="math_toolkit/special/bessel/bessel.html"> Bessel Functions
+ of the First and Second Kinds</a></dt>
+<dt><a href="math_toolkit/special/bessel/mbessel.html"> Modified Bessel
+ Functions of the First and Second Kinds</a></dt>
+<dt><a href="math_toolkit/special/bessel/sph_bessel.html"> Spherical
+ Bessel Functions of the First and Second Kinds</a></dt>
+</dl></dd>
+<dt> Elliptic Integrals</dt>
+<dd><dl>
+<dt><a href="math_toolkit/special/ellint/ellint_intro.html"> Elliptic
+ Integral Overview</a></dt>
+<dt><a href="math_toolkit/special/ellint/ellint_carlson.html"> Elliptic
+ Integrals - Carlson Form</a></dt>
+<dt><a href="math_toolkit/special/ellint/ellint_1.html"> Elliptic Integrals
+ of the First Kind - Legendre Form</a></dt>
+<dt><a href="math_toolkit/special/ellint/ellint_2.html"> Elliptic Integrals
+ of the Second Kind - Legendre Form</a></dt>
+<dt><a href="math_toolkit/special/ellint/ellint_3.html"> Elliptic Integrals
+ of the Third Kind - Legendre Form</a></dt>
+</dl></dd>
+<dt><a href="math_toolkit/special/powers.html"> Logs, Powers, Roots and
+ Exponentials</a></dt>
+<dd><dl>
+<dt> log1p</dt>
+<dt> expm1</dt>
+<dt> cbrt</dt>
+<dt> sqrt1pm1</dt>
+<dt> powm1</dt>
+<dt> hypot</dt>
+</dl></dd>
+<dt><a href="math_toolkit/special/sinc.html"> Sinus Cardinal and Hyperbolic
+ Sinus Cardinal Functions</a></dt>
+<dd><dl>
+<dt><a href="math_toolkit/special/sinc/sinc_overview.html"> Sinus Cardinal
+ and Hyperbolic Sinus Cardinal Functions Overview</a></dt>
+<dt>sinc_pi</dt>
+<dt>sinhc_pi</dt>
+</dl></dd>
+<dt> Inverse Hyperbolic Functions</dt>
+<dd><dl>
+<dt><a href="math_toolkit/special/inv_hyper/inv_hyper_over.html"> Inverse
+ Hyperbolic Functions Overview</a></dt>
+<dt> acosh</dt>
+<dt> asinh</dt>
+<dt> atanh</dt>
+</dl></dd>
+<dt><a href="math_toolkit/special/fpclass.html"> Floating Point Classification:
+ Infinities and NaN's</a></dt>
+</dl></dd>
+<dt> Internal Details and Tools (Experimental)</dt>
+<dd><dl>
+<dt> Overview</dt>
+<dt> Reused Utilities</dt>
+<dd><dl>
+<dt><a href="math_toolkit/toolkit/internals1/series_evaluation.html">
+ Series Evaluation</a></dt>
+<dt><a href="math_toolkit/toolkit/internals1/cf.html"> Continued Fraction
+ Evaluation</a></dt>
+<dt><a href="math_toolkit/toolkit/internals1/rational.html"> Polynomial
+ and Rational Function Evaluation</a></dt>
+<dt><a href="math_toolkit/toolkit/internals1/roots.html"> Root Finding
+ With Derivatives</a></dt>
+<dt><a href="math_toolkit/toolkit/internals1/roots2.html"> Root Finding
+ Without Derivatives</a></dt>
+<dt><a href="math_toolkit/toolkit/internals1/minima.html"> Locating Function
+ Minima</a></dt>
+</dl></dd>
+<dt> Testing and Development</dt>
+<dd><dl>
+<dt> Polynomials</dt>
+<dt><a href="math_toolkit/toolkit/internals2/minimax.html"> Minimax Approximations
+ and the Remez Algorithm</a></dt>
+<dt><a href="math_toolkit/toolkit/internals2/error_test.html"> Relative
+ Error and Testing</a></dt>
+<dt><a href="math_toolkit/toolkit/internals2/test_data.html"> Graphing,
+ Profiling, and Generating Test Data for Special Functions</a></dt>
+</dl></dd>
+</dl></dd>
+<dt><a href="math_toolkit/using_udt.html"> Use with User Defined Floating-Point
+ Types</a></dt>
+<dd><dl>
+<dt><a href="math_toolkit/using_udt/use_ntl.html"> Using With NTL - a High-Precision
+ Floating-Point Library</a></dt>
+<dt><a href="math_toolkit/using_udt/concepts.html"> Conceptual Requirements
+ for Real Number Types</a></dt>
+<dt><a href="math_toolkit/using_udt/dist_concept.html"> Conceptual Requirements
+ for Distribution Types</a></dt>
+<dt><a href="math_toolkit/using_udt/archetypes.html"> Conceptual Archetypes
+ and Testing</a></dt>
+</dl></dd>
+<dt> Policies</dt>
+<dd><dl>
+<dt> Policy Overview</dt>
+<dt> Policy Tutorial</dt>
+<dd><dl>
+<dt><a href="math_toolkit/policy/pol_tutorial/what_is_a_policy.html">
+ So Just What is a Policy Anyway?</a></dt>
+<dt><a href="math_toolkit/policy/pol_tutorial/policy_tut_defaults.html">
+ Policies Have Sensible Defaults</a></dt>
+<dt><a href="math_toolkit/policy/pol_tutorial/policy_usage.html"> So
+ How are Policies Used Anyway?</a></dt>
+<dt><a href="math_toolkit/policy/pol_tutorial/changing_policy_defaults.html">
+ Changing the Policy Defaults</a></dt>
+<dt><a href="math_toolkit/policy/pol_tutorial/ad_hoc_dist_policies.html">
+ Setting Policies for Distributions on an Ad Hoc Basis</a></dt>
+<dt><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></dt>
+<dt><a href="math_toolkit/policy/pol_tutorial/namespace_policies.html">
+ Setting Policies at Namespace or Translation Unit Scope</a></dt>
+<dt><a href="math_toolkit/policy/pol_tutorial/user_def_err_pol.html">
+ Calling User Defined Error Handlers</a></dt>
+<dt><a href="math_toolkit/policy/pol_tutorial/understand_dis_quant.html">
+ Understanding Quantiles of Discrete Distributions</a></dt>
+</dl></dd>
+<dt> Policy Reference</dt>
+<dd><dl>
+<dt><a href="math_toolkit/policy/pol_ref/error_handling_policies.html">
+ Error Handling Policies</a></dt>
+<dt><a href="math_toolkit/policy/pol_ref/internal_promotion.html"> Internal
+ Promotion Policies</a></dt>
+<dt><a href="math_toolkit/policy/pol_ref/assert_undefined.html"> Mathematically
+ Undefined Function Policies</a></dt>
+<dt><a href="math_toolkit/policy/pol_ref/discrete_quant_ref.html"> Discrete
+ Quantile Policies</a></dt>
+<dt><a href="math_toolkit/policy/pol_ref/precision_pol.html"> Precision
+ Policies</a></dt>
+<dt><a href="math_toolkit/policy/pol_ref/iteration_pol.html"> Iteration
+ Limits Policies</a></dt>
+<dt><a href="math_toolkit/policy/pol_ref/policy_defaults.html"> Using
+ macros to Change the Policy Defaults</a></dt>
+<dt><a href="math_toolkit/policy/pol_ref/namespace_pol.html"> Setting
+ Polices at Namespace Scope</a></dt>
+<dt><a href="math_toolkit/policy/pol_ref/pol_ref_ref.html"> Policy Class
+ Reference</a></dt>
+</dl></dd>
+</dl></dd>
+<dt> Performance</dt>
+<dd><dl>
+<dt> Performance Overview</dt>
+<dt> Interpretting these Results</dt>
+<dt><a href="math_toolkit/perf/getting_best.html"> Getting the Best Performance
+ from this Library</a></dt>
+<dt> Comparing Compilers</dt>
+<dt> Performance Tuning Macros</dt>
+<dt><a href="math_toolkit/perf/comparisons.html"> Comparisons to Other
+ Open Source Libraries</a></dt>
+<dt><a href="math_toolkit/perf/perf_test_app.html"> The Performance Test
+ Application</a></dt>
+</dl></dd>
+<dt> Backgrounders</dt>
+<dd><dl>
+<dt><a href="math_toolkit/backgrounders/implementation.html"> Additional
+ Implementation Notes</a></dt>
+<dt><a href="math_toolkit/backgrounders/relative_error.html"> Relative
+ Error</a></dt>
+<dt> The Lanczos Approximation</dt>
+<dt> The Remez Method</dt>
+<dt> References</dt>
+</dl></dd>
+<dt> Library Status</dt>
+<dd><dl>
+<dt> History and What's New</dt>
+<dt> Compilers</dt>
+<dt> Known Issues, and Todo List</dt>
+<dt> Credits and Acknowledgements</dt>
+</dl></dd>
+</dl>
+</div>
+
+ ISBN 0-9504833-2-X 978-0-9504833-2-0, Classification 519.2-dc22
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left">Last revised: October 09, 2007 at 11:19:03 GMT</td>
+<td align="right"></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><a href="backgrounders/implementation.html"> Additional
+ Implementation Notes</a></dt>
+<dt><a href="backgrounders/relative_error.html"> Relative
+ Error</a></dt>
+<dt> The Lanczos Approximation</dt>
+<dt> The Remez Method</dt>
+<dt> References</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+<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>
+
+ "First be right, then be fast."
+ 
+
+ There will always be potential compromises to be made between speed and accuracy.
+ It may be possible to find faster methods, particularly for certain limited
+ ranges of arguments, but for most applications of math functions and distributions,
+ we judge that speed is rarely as important as accuracy.
+ 
+
+ So our priority is accuracy.
+ 
+
+ To permit evaluation of accuracy of the special functions, production of
+ extremely accurate tables of test values has received considerable effort.
+ 
+
+ (It also required much CPU effort - there was some danger of molten plastic
+ dripping from the bottom of JM's laptop, so instead, PAB's Dual-core desktop
+ was kept 50% busy for days calculating some
+ tables of test values!)
+ 
+
+ For a specific RealType, say float or double, it may be possible to find
+ approximations for some functions that are simpler and thus faster, but less
+ accurate (perhaps because there are no refining iterations, for example,
+ when calculating inverse functions).
+ 
+
+ If these prove accurate enough to be "fit for his purpose", then
+ a user may substitute his custom specialization.
+ 
+
+ For example, there are approximations dating back from times when computation
+ was a lot more expensive:
+ 
+
+ H Goldberg and H Levine, Approximate formulas for percentage points and normalisation
+ of t and chi squared, Ann. Math. Stat., 17(4), 216 - 225 (Dec 1946).
+ 
+
+ A H Carter, Approximations to percentage points of the z-distribution, Biometrika
+ 34(2), 352 - 358 (Dec 1947).
+ 
+
+ These could still provide sufficient accuracy for some speed-critical applications.
+ 
+<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>
+
+ 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<RealType>(1.2345L) to provide the appropriate RealType
+ for spot tests.
+ 
+
+ Functions that return constants values, like kurtosis for example, are written
+ as
+ 
+
+ <code class="computeroutput">static_cast<RealType>(-3) /
+ 5;</code>
+ 
+
+ 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).
+ 
+
+ So tests for one third, not exactly representable
+ with radix two floating-point, (should) use, for example:
+ 
+
+ <code class="computeroutput">static_cast<RealType>(1) /
+ 3;</code>
+ 
+
+ 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">a/b</code> with <code class="computeroutput">b</code>
+ a power of two (in order to ensure that the result is an exactly representable
+ binary value).
+ 
+<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>
+
+ The tolerances need to be set to the maximum of:
+ 
+<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>
+
+ Otherwise when long double has more digits than the test data, then no amount
+ of tweaking an epsilon based tolerance will work.
+ 
+
+ 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.
+ 
+<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>
+
+ 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 & M. Paterno
+ it is proposed that signalling a domain error is mandatory when the argument
+ would give an mathematically undefined result.
+ 
+<div class="itemizedlist"><ul type="disc"><li>
+ Guideline 1
+ </li></ul></div>
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ 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.
+ 
+
+ 
+</blockquote></div>
+
+ Put crudely, if the function goes to + infinity and then emerges 'round-the-back'
+ with - infinity, it is NOT defined.
+ 
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ 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.
+ 
+
+ 
+</blockquote></div>
+<div class="itemizedlist"><ul type="disc"><li>
+ Guideline 2
+ </li></ul></div>
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ 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.
+ 
+
+ 
+</blockquote></div>
+
+ This implementation is believed to follow these proposals and to assist compatibility
+ with ISO/IEC 9899:1999 Programming languages - C 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>.
+ 
+
+ 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.
+ 
+
+ 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
+ 
+<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">
+ If you enable throw but do NOT have try & catch block, then the program
+ will terminate with an uncaught exception and probably abort. Therefore
+ to get the benefit of helpful error messages, enabling all
+ exceptions and using try&catch is
+ recommended for all applications. However, for simplicity, this is not
+ done for most examples.
+ </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>
+
+ 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.
+ 
+
+ 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,
+ 
+
+ <code class="computeroutput">#define BOOST_MATH_DOMAIN_ERROR_POLICY
+ ignore_error</code>
+ 
+
+ appears before the first Boost include, then if the un-implemented function
+ is called, mean(cauchy<>()) will return std::numeric_limits<T>::quiet_NaN().
+ 
+<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">
+ If <code class="computeroutput">std::numeric_limits<T>::has_quiet_NaN</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.
+ </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>
+
+ 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.
+ 
+
+ However a useful median approximation for distribution <code class="computeroutput">dist</code>
+ may be available from
+ 
+
+ <code class="computeroutput">quantile(dist, 0.5)</code>.
+ 
+
+ <a href="http://www.amstat.org/publications/jse/v13n2/vonhippel.html" target="_top">Mean,
+ Median, and Skew, Paul T von Hippel</a>
+ 
+
+ <a href="http://documents.wolfram.co.jp/teachersedition/MathematicaBook/24.5.html" target="_top">Descriptive
+ Statistics,</a>
+ 
+
+ <a href="http://documents.wolfram.co.jp/v5/Add-onsLinks/StandardPackages/Statistics/DescriptiveStatistics.html" target="_top">and
+ </a>
+ 
+
+ <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.
+ 
+<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>
+
+ 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.
+ 
+
+ 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">std::numeric_limits<RealType>::infinity()</code> and would return zero rather than any representation
+ of infinity.
+ 
+
+ 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.
+ 
+
+ 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.
+ 
+
+ Overflow, underflow, denorm can be handled using <a href="../policy/pol_ref/error_handling_policies.html" title="Error Handling Policies">error
+ handling policies</a>.
+ 
+
+ 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>.
+ 
+<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>
+
+ We considered adding location and scale to the list of functions, for example:
+ 
+<pre class="programlisting">
+template <class RealType>
+inline RealType scale(const triangular_distribution<RealType>& dist)
+{
+ RealType lower = dist.lower();
+ RealType mode = dist.mode();
+ RealType upper = dist.upper();
+ RealType result; // of checks.
+ if(false == detail::check_triangular(BOOST_CURRENT_FUNCTION, lower, mode, upper, &result))
+ {
+ return result;
+ }
+ return (upper - lower);
+}
+</pre>
+
+ 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.
+ 
+<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 & 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>
+
+ 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>.
+ 
+
+ 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.
+ 
+
+ 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).
+ 
+
+ 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">exp</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.
+ 
+<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>
+
+ 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.
+ 
+
+ 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.
+ 
+
+ 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).
+ 
+
+ For example, pi is defined:
+ 
+<pre class="programlisting">
+BOOST_DEFINE_MATH_CONSTANT(pi,
+ 3.141592653589793238462643383279502884197169399375105820974944,
+ 5923078164062862089986280348253421170679821480865132823066470938446095505,
+ 0)
+</pre>
+
+ And used thus:
+ 
+<pre class="programlisting">
+using namespace boost::math::constants;
+
+double diameter = 1.;
+double radius = diameter * pi<double>();
+
+or boost::math::constants::pi<NTL::RR>()
+</pre>
+
+ Note that it is necessary (if inconvenient) to specify the type explicitly.
+ 
+
+ So you cannot write
+ 
+<pre class="programlisting">
+double p = boost::math::constants::pi<>(); // could not deduce template argument for 'T'
+</pre>
+
+ Neither can you write:
+ 
+<pre class="programlisting">
+double p = boost::math::constants::pi; // Context does not allow for disambiguation of overloaded function
+double p = boost::math::constants::pi(); // Context does not allow for disambiguation of overloaded function
+</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>
+
+ 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.
+ 
+
+ Other than that, the code is intended to be thread safe for
+ built in real-number types : so float, double and long double
+ are all thread safe.
+ 
+
+ For non-built-in types - NTL::RR for example - initialisation of the various
+ constants used in the implementation is potentially not
+ 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.
+ 
+<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>
+
+ We found a large number of sources of test data. We have assumed that these
+ are "known good" if they agree with the results
+ from our test and only consulted other sources for their 'vote'
+ in the case of serious disagreement. The accuracy, 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.
+ 
+
+ 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>
+ 
+
+ Statlet:
+ Is a Javascript application that calculates and plots probability distributions,
+ and provides the most complete range of distributions:
+ 
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ 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.
+ 
+
+ 
+</blockquote></div>
+
+ It calculates pdf, cdf, survivor, log survivor, hazard, tail areas, &
+ critical values for 5 tail values.
+ 
+
+ It is also the only independent source found for the Weibull distribution;
+ unfortunately it appears to suffer from very poor accuracy in areas where
+ the underlying special function is known to be difficult to implement.
+ 
+<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>
+
+ The primary source for the equations is now MathML:
+ see the *.mml files in libs/math/doc/equations/.
+ 
+
+ 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.
+ 
+
+ Convertion to SVG was achieved using SVGMath
+ and a command line such as:
+ 
+<pre class="programlisting">$for file in *.mml; do
+>/cygdrive/c/Python25/python.exe 'C:\download\open\SVGMath-0.3.1\math2svg.py' \
+>>$file > $(basename $file .mml).svg
+>done
+</pre>
+
+ Note that SVGMath requires that the mml files are not
+ 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.
+ 
+
+ If neccessary the XHTML wrapper can be removed with:
+ 
+<pre class="programlisting">cat filename | tr -d "\r\n" | sed -e 's/.*$<math[^>]*>.*</math>$.*/\1/' > newfile</pre>
+
+ Setting up fonts for SVGMath is currently rather tricky, on a windows system
+ JM's font setup looks like this:
+ 
+<pre class="programlisting">
+<config verbose<code class="literal">"true">
+ 
+ <fallback family</code>"Lucida Sans Unicode"/>
+
+ 
+ 
+ <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"/>
+
+ 
+ 
+ <operator-style operator<code class="literal">"&#x2145;" fontstyle</code>"italic"/>
+ <operator-style operator<code class="literal">"&#x2146;" fontstyle</code>"italic"/>
+
+ 
+ <family name<code class="literal">"Times New Roman">
+ "C:\WINDOWS\Fonts\times.ttf"/>
+ "bold" ttf</code>"C:\WINDOWS\Fonts\timesbd.ttf"/>
+ "italic" ttf</code>"C:\WINDOWS\Fonts\timesi.ttf"/>
+ "bold" style</code>"italic" ttf<code class="literal">"C:\WINDOWS\Fonts\timesbi.ttf"\/>
+ <\/family>
+
+ <family name</code>"Arial">
+ "C:\WINDOWS\Fonts\arial.ttf"\/>
+ "bold" ttf<code class="literal">"C:\WINDOWS\Fonts\arialbd.ttf"\/>
+ "italic" ttf<code class="literal">"C:\WINDOWS\Fonts\ariali.ttf"\/>
+ "bold" style<code class="literal">"italic" ttf</code>"C:\WINDOWS\Fonts\arialbi.ttf"/>
+ </family>
+
+ <family name<code class="literal">"Courier New">
+ "C:\WINDOWS\Fonts\cour.ttf"/>
+ "bold" ttf</code>"C:\WINDOWS\Fonts\courbd.ttf"/>
+ "italic" ttf</code>"C:\WINDOWS\Fonts\couri.ttf"/>
+ "bold" style</code>"italic" ttf<code class="literal">"C:\WINDOWS\Fonts\courbi.ttf"\/>
+ <\/family>
+
+ <family name</code>"Euclid Fraktur">
+ "C:\WINDOWS\Fonts\eufrak.ttf"\/>
+ "bold" ttf<code class="literal">"C:\WINDOWS\Fonts\eufrakb.ttf"\/>
+ <\/family>
+
+ <family name</code>"Monotype Corsiva">
+ "C:\WINDOWS\Fonts\mtcorsva.ttf"\/>
+ <\/family>
+
+ <family name</code>"Lucida Sans Unicode">
+ "C:\WINDOWS\Fonts\lsansuni.ttf"\/>
+ <\/family>
+
+ 
+ 
+ <mathvariant name</code>"normal"
+ family<code class="literal">"Times New Roman, Lucida Sans Unicode"\/>
+ <mathvariant name</code>"bold"
+ family<code class="literal">"Times New Roman, Lucida Sans Unicode" weight</code>"bold"/>
+ <mathvariant name<code class="literal">"italic"
+ family</code>"Times New Roman, Lucida Sans Unicode" style<code class="literal">"italic"\/>
+ <mathvariant name</code>"bold-italic"
+ family<code class="literal">"Times New Roman, Lucida Sans Unicode" weight</code>"bold" style<code class="literal">"italic"\/>
+
+ 
+ <mathvariant name</code>"sans-serif"
+ family<code class="literal">"Arial, Lucida Sans Unicode"\/>
+ <mathvariant name</code>"bold-sans-serif"
+ family<code class="literal">"Arial, Lucida Sans Unicode" weight</code>"bold"/>
+ <mathvariant name<code class="literal">"sans-serif-italic"
+ family</code>"Arial, Lucida Sans Unicode" style<code class="literal">"italic"\/>
+ <mathvariant name</code>"sans-serif-bold-italic"
+ family<code class="literal">"Arial, Lucida Sans Unicode" weight</code>"bold" style<code class="literal">"italic"\/>
+
+ 
+ <mathvariant name</code>"fraktur"
+ family<code class="literal">"Euclid Fraktur, Lucida Sans Unicode"\/>
+ <mathvariant name</code>"bold-fraktur"
+ family<code class="literal">"Euclid Fraktur, Lucida Sans Unicode" weight</code>"bold"/>
+
+ 
+ <mathvariant name<code class="literal">"script"
+ family</code>"Monotype Corsiva, Lucida Sans Unicode"/>
+ <mathvariant name<code class="literal">"bold-script"
+ family</code>"Monotype Corsiva, Lucida Sans Unicode" weight<code class="literal">"bold"\/>
+
+ 
+ <mathvariant name</code>"monospace" family<code class="literal">"Courier New, Lucida Sans Unicode"\/>
+
+ 
+ <mathvariant name</code>"double-struck" family="Lucida Sans Unicode"/>
+</config>
+</pre>
+
+ 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".
+ 
+
+ Also note that the SVG files in the repository are almost certainly Windows-specific
+ since they reference various Windows Fonts.
+ 
+
+ PNG files can be created from the SVG's using Batik
+ and a command such as:
+ 
+<pre class="programlisting">java -jar 'C:\download\open\batik-1.7\batik-rasterizer.jar' -dpi 120 *.svg</pre>
+
+ The PDF is generated using:
+ 
+<pre class="programlisting">$bjam -a pdf xsl:param<code class="literal">admon.graphics.extension</code>".svg" \
+>xsl:param=use.role.for.mediaobject=1 xsl:param=preferred.mediaobject.role=print</pre>
+
+ Note that XEP will have to be configured to use and
+ embed whatever fonts are used by the SVG equations. JM's XEP config
+ file looks like:
+ 
+<pre class="programlisting"><?xml version<code class="literal">"1.0" encoding</code>"UTF-8"?>
+<config>
+
+ 
+ 
+ 
+ <options>
+ <option name<code class="literal">"LICENSE" value</code>"license.xml"/>
+ <option name<code class="literal">"TMPDIR" value</code>"none"/>
+ <option name<code class="literal">"BROKENIMAGE" value</code>"images/404.gif"/>
+ <option name<code class="literal">"LOGO" value</code>"images/logo-renderx.svg"/>
+
+ 
+ <generator-options format<code class="literal">"PDF">
+ 
+ 
+ <\/generator-options>
+
+ <generator-options format</code>"PostScript">
+ 
+ 
+ </generator-options>
+
+ <generator-options format<code class="literal">"AFP">
+ <option name</code>"AFPCodepageTxt" value<code class="literal">"Cp500"\/>
+ <option name</code>"AFPCodepage" value<code class="literal">"T1V10500"\/>
+ <option name</code>"AFPLogLevel" value<code class="literal">"0"\/>
+ <option name</code>"USE_PTOCA_LEVEL" value<code class="literal">"3"\/>
+ <option name</code>"USE_BCOCA_LEVEL" value<code class="literal">"1"\/>
+ <option name</code>"USE_GOCA_LEVEL" value<code class="literal">"1"\/>
+ <option name</code>"RESOLUTION" value<code class="literal">"1440"\/>
+ 
+ <option name</code>"USE_SHADING_PATTERNS" value<code class="literal">"yes"\/>
+ <option name</code>"USE_REPLICATE_AND_TRIM" value<code class="literal">"yes"\/>
+ <option name</code>"SHADING_PATTERN_RESOLUTION" value<code class="literal">"0.25"\/>
+ <option name</code>"TRY_USING_TIFF_COMPRESSION" value<code class="literal">"yes"\/>
+ <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"\/>
+ <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"\/>
+ <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"\/>
+ <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"\/>
+ <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"\/>
+ <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"\/>
+ <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"\/>
+ <\/generator-options>
+ <\/options>
+
+ 
+ 
+ 
+
+ <fonts xml:base</code>"fonts/" default-family<code class="literal">"Helvetica">
+
+ 
+ <font-group label</code>"Base 14" embed<code class="literal">"false">
+ <font-family name</code>"Courier">
+ <font-data afm<code class="literal">"Courier.afm"\/><\/font>
+ "oblique"><font-data afm<code class="literal">"Courier-Oblique.afm"\/><\/font>
+ "bold"><font-data afm<code class="literal">"Courier-Bold.afm"\/><\/font>
+ "bold" style<code class="literal">"oblique"><font-data afm</code>"Courier-BoldOblique.afm"/>
+ </font-family>
+
+ <font-family name<code class="literal">"Helvetica">
+ <font-data afm</code>"Helvetica.afm"/>
+ "oblique"><font-data afm</code>"Helvetica-Oblique.afm"/>
+ "bold"><font-data afm</code>"Helvetica-Bold.afm"/>
+ "bold" style</code>"oblique"><font-data afm<code class="literal">"Helvetica-BoldOblique.afm"\/><\/font>
+ <\/font-family>
+
+ <font-family name</code>"Times" ligatures<code class="literal">"ﬁ ﬂ">
+ <font-data afm</code>"Times-Roman.afm"/>
+ "italic"><font-data afm</code>"Times-Italic.afm"/>
+ "bold"><font-data afm</code>"Times-Bold.afm"/>
+ "bold" style</code>"italic"><font-data afm<code class="literal">"Times-BoldItalic.afm"\/><\/font>
+ <\/font-family>
+
+ <font-family name</code>"Symbol">
+ <font-data afm<code class="literal">"Symbol.afm"\/><\/font>
+ <\/font-family>
+
+ <font-family name</code>"ZapfDingbats">
+ <font-data afm<code class="literal">"ZapfDingbats.afm"\/><\/font>
+ <\/font-family>
+ <\/font-group>
+
+ 
+ <font-group label</code>"Assorted Type 1" embed<code class="literal">"true">
+ <font-family name</code>"OmegaSerifIPA">
+ <font-data afm<code class="literal">"IPA.afm" pfa</code>"IPA.pfa" glyph-list<code class="literal">"IPA.glyphs"\/><\/font>
+ <\/font-family>
+ <font-alias name</code>"OmegaIPA" value<code class="literal">"OmegaSerifIPA"\/>
+ <font-alias name</code>"Phonetic" value<code class="literal">"OmegaSerifIPA"\/>
+ <\/font-group>
+
+ 
+
+ <font-group xml:base</code>"file:/C:/Windows/Fonts/" label<code class="literal">"Windows TrueType" embed</code>"true" subset<code class="literal">"true">
+ <font-family name</code>"Arial">
+ <font-data ttf<code class="literal">"arial.ttf"\/><\/font>
+ "oblique"><font-data ttf<code class="literal">"ariali.ttf"\/><\/font>
+ "bold"><font-data ttf<code class="literal">"arialbd.ttf"\/><\/font>
+ "bold" style<code class="literal">"oblique"><font-data ttf</code>"arialbi.ttf"/>
+ </font-family>
+
+ <font-family name<code class="literal">"Times New Roman" ligatures</code>"&#xFB01; &#xFB02;">
+ <font-data ttf<code class="literal">"times.ttf"\/><\/font>
+ "italic"><font-data ttf<code class="literal">"timesi.ttf"\/><\/font>
+ "bold"><font-data ttf<code class="literal">"timesbd.ttf"\/><\/font>
+ "bold" style<code class="literal">"italic"><font-data ttf</code>"timesbi.ttf"/>
+ </font-family>
+
+ <font-family name<code class="literal">"Courier New">
+ <font-data ttf</code>"cour.ttf"/>
+ "oblique"><font-data ttf</code>"couri.ttf"/>
+ "bold"><font-data ttf</code>"courbd.ttf"/>
+ "bold" style</code>"oblique"><font-data ttf<code class="literal">"courbi.ttf"\/><\/font>
+ <\/font-family>
+
+ <font-family name</code>"Tahoma" embed<code class="literal">"true">
+ <font-data ttf</code>"tahoma.ttf"/>
+ "bold"><font-data ttf</code>"tahomabd.ttf"/>
+ </font-family>
+
+ <font-family name<code class="literal">"Verdana" embed</code>"true">
+ <font-data ttf<code class="literal">"verdana.ttf"\/><\/font>
+ "oblique"><font-data ttf<code class="literal">"verdanai.ttf"\/><\/font>
+ "bold"><font-data ttf<code class="literal">"verdanab.ttf"\/><\/font>
+ "bold" style<code class="literal">"oblique"><font-data ttf</code>"verdanaz.ttf"/>
+ </font-family>
+
+ <font-family name<code class="literal">"Palatino" embed</code>"true" ligatures<code class="literal">"&#xFB00; &#xFB01; &#xFB02; &#xFB03; &#xFB04;">
+ <font-data ttf</code>"pala.ttf"/>
+ "italic"><font-data ttf</code>"palai.ttf"/>
+ "bold"><font-data ttf</code>"palab.ttf"/>
+ "bold" style</code>"italic"><font-data ttf<code class="literal">"palabi.ttf"\/><\/font>
+ <\/font-family>
+
+ <font-family name</code>"Lucida Sans Unicode">
+ <font-data ttf<code class="literal">"lsansuni.ttf"\/><\/font>
+ <\/font-family>
+
+ <\/font-group>
+
+ 
+ <font-alias name</code>"monospace" value<code class="literal">"Courier"\/>
+ <font-alias name</code>"sans-serif" value<code class="literal">"Helvetica"\/>
+ <font-alias name</code>"serif" value<code class="literal">"Times"\/>
+ <font-alias name</code>"cursive" value<code class="literal">"Times"\/>
+ <font-alias name</code>"fantasy" value<code class="literal">"Times"\/>
+ <\/fonts>
+
+ 
+ 
+ 
+ <languages default-language</code>"en-US" xml:base<code class="literal">"hyphen\/">
+
+ <language name</code>"English (US)" codes<code class="literal">"none en-US eng-US">
+ <hyphenation pattern</code>"hyphen.tex"/>
+ </language>
+
+ <language name<code class="literal">"English (UK)" codes</code>"en-GB eng-GB en eng">
+ <hyphenation pattern<code class="literal">"ukhyphen.tex"\/>
+ <\/language>
+
+ <language name</code>"Russian" codes<code class="literal">"ru rus">
+ <hyphenation pattern</code>"ruhyphal.tex" encoding<code class="literal">"koi8-r"\/>
+ <\/language>
+
+ <language name</code>"French" codes<code class="literal">"fr fra fre">
+ <hyphenation pattern</code>"frhyph_rx.tex"/>
+ </language>
+
+ <language name<code class="literal">"German" codes</code>"de deu ger">
+ <hyphenation pattern<code class="literal">"dehyph_rx.tex"\/>
+ <\/language>
+
+ <language name</code>"Spanish" codes<code class="literal">"es esl spa">
+ <hyphenation pattern</code>"eshyph_rx.tex"/>
+ </language>
+
+ <language name<code class="literal">"Polish" codes</code>"pl pol">
+ <hyphenation pattern="plhyph_rx.tex"/>
+ </language>
+
+ </languages>
+
+</config>
+</pre>
+
+ 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.
+ 
+
+ Equations are embedded in the quickbook source using the equation
+ template defined in math.qbk. This outputs Docbook XML that looks like:
+ 
+<pre class="programlisting"><inlinemediaobject>
+<imageobject role<code class="literal">"html">
+<imagedata fileref</code>"../equations/myfile.png"></imagedata>
+</imageobject>
+<imageobject role<code class="literal">"print">
+<imagedata fileref</code>"../equations/myfile.svg"></imagedata>
+</imageobject>
+</inlinemediaobject>
+</pre>
+
+ MathML is not currently present in the Docbook output, or in the generated
+ HTML: this needs further investigation.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ Why base gamma and gamma-like functions on the Lanczos approximation?
+ 
+
+ 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:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ The approximation has an easy to compute truncation error that holds for
+ all z > 0. In practice that means we can use the
+ same approximation for all z > 0, and be certain
+ that no matter how large or small z is, the truncation
+ error will at worst 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>
+
+ 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.
+ 
+
+ As the simplest example, consider the ratio of two gamma functions: one could
+ compute the result via lgamma:
+ 
+<pre class="programlisting">
+exp(lgamma(a) - lgamma(b));
+</pre>
+
+ However, even if lgamma is uniformly accurate to 0.5ulp, the worst case relative
+ error in the above can easily be shown to be:
+ 
+<pre class="programlisting">
+Erel > a * log(a)/2 + b * log(b)/2
+</pre>
+
+ For small a and b that's not a
+ problem, but to put the relationship another way: each time a and
+ b increase in magnitude by a factor of 10, at least one decimal digit of
+ precision will be lost.
+ 
+
+ In contrast, by analytically combining like power terms in a ratio of Lanczos
+ approximation's, these errors can be virtually eliminated for small a
+ and b, and kept under control for very large (or very
+ small for that matter) a and b.
+ 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.
+ 
+<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>
+
+ The Lanczos Approximation to the Gamma Function is given by:
+ 
+
+ <img src="../../../equations/lanczos0.png">
+ 
+
+ Where Sg(z) is an infinite sum, that is convergent for all z > 0, and
+ g is an arbitrary parameter that controls the "shape"
+ of the terms in the sum which is given by:
+ 
+
+ <img src="../../../equations/lanczos0a.png">
+ 
+
+ With individual coefficients defined in closed form by:
+ 
+
+ <img src="../../../equations/lanczos0b.png">
+ 
+
+ 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).
+ 
+
+ The Lanczos approximation is therefore often written in partial fraction
+ form with the leading constants absorbed by the coefficients in the sum:
+ 
+
+ <img src="../../../equations/lanczos1.png">
+ 
+
+ where:
+ 
+
+ <img src="../../../equations/lanczos2.png">
+ 
+
+ Again parameter g is an arbitrarily chosen constant,
+ and N is an arbitrarily chosen number of terms to evaluate
+ in the "Lanczos sum" part.
+ 
+<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">
+ 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.
+ </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>
+
+ The coefficients C0..CN-1 need to be computed from N
+ and g 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 = B D C F
+ 
+
+ where B is an NxN matrix:
+ 
+
+ <img src="../../../equations/lanczos4.png">
+ 
+
+ D is an NxN matrix:
+ 
+
+ <img src="../../../equations/lanczos3.png">
+ 
+
+ C is an NxN matrix:
+ 
+
+ <img src="../../../equations/lanczos5.png">
+ 
+
+ and F is an N element column vector:
+ 
+
+ <img src="../../../equations/lanczos6.png">
+ 
+
+ Note than the matrices B, D and C contain all integer terms and depend only
+ on N, this product should be computed first, and then
+ multiplied by F as the last step.
+ 
+<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>
+
+ The trick is to choose N and g
+ to give the desired level of accuracy: choosing a small value for g
+ leads to a strictly convergent series, but one which converges only slowly.
+ Choosing a larger value of g causes the terms in the
+ series to be large and/or divergent for about the first g-1
+ terms, and to then suddenly converge with a "crunch".
+ 
+
+ Pugh has determined the optimal value of g
+ for N in the range 1 <= N <= 60:
+ 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 and 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.
+ 
+<div class="table">
+<a name="id788557"></a>Table 43. Optimal choices for N and g when computing with
+ guard digits (source: Pugh)
+<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>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ N
+ 
+ </th>
+<th>
+ 
+ g
+ 
+ </th>
+<th>
+ 
+ Max Error
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 24
+ 
+ </td>
+<td>
+ 
+ 6
+ 
+ </td>
+<td>
+ 
+ 5.581
+ 
+ </td>
+<td>
+ 
+ 9.51e-12
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ 13
+ 
+ </td>
+<td>
+ 
+ 13.144565
+ 
+ </td>
+<td>
+ 
+ 9.2213e-23
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ 
+ The alternative described by Godfrey is to
+ perform an exhaustive search of the N and g
+ parameter space to determine the optimal combination for a given p
+ 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 < z < 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.
+ 
+
+ 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
+ (aN) in the Lanczos series Sg(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.
+ 
+
+ 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 g, but avoiding cancellation
+ errors in the evaluation requires a small g.
+ 
+
+ 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 they
+ are all positive. 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 N
+ and slightly smaller g 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 N than would otherwise be required,
+ so fewer floating point operations may be required overall.
+ 
+
+ The following table shows the optimal values for N and
+ g 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 & NTL quad_float), and further optimisation of the
+ values of g may be possible. Errors given in the table
+ are estimates of the error due to truncation of the Lanczos infinite series
+ to N 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 N
+ and g occurred when the estimated truncation error almost
+ exactly matches the machine epsilon for the type in question.
+ 
+<div class="table">
+<a name="id788884"></a>Table 44. Optimum value for N and g when computing at fixed
+ precision
+<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>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform/Compiler Used
+ 
+ </th>
+<th>
+ 
+ N
+ 
+ </th>
+<th>
+ 
+ g
+ 
+ </th>
+<th>
+ 
+ Max Truncation Error
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 24
+ 
+ </td>
+<td>
+ 
+ Win32, VC++ 7.1
+ 
+ </td>
+<td>
+ 
+ 6
+ 
+ </td>
+<td>
+ 
+ 1.428456135094165802001953125
+ 
+ </td>
+<td>
+ 
+ 9.41e-007
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, VC++ 7.1
+ 
+ </td>
+<td>
+ 
+ 13
+ 
+ </td>
+<td>
+ 
+ 6.024680040776729583740234375
+ 
+ </td>
+<td>
+ 
+ 3.23e-016
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Suse Linux 9 IA64, gcc-3.3.3
+ 
+ </td>
+<td>
+ 
+ 17
+ 
+ </td>
+<td>
+ 
+ 12.2252227365970611572265625
+ 
+ </td>
+<td>
+ 
+ 2.34e-024
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 116
+ 
+ </td>
+<td>
+ 
+ HP Tru64 Unix 5.1B / Alpha, Compaq C++ V7.1-006
+ 
+ </td>
+<td>
+ 
+ 24
+ 
+ </td>
+<td>
+ 
+ 20.3209821879863739013671875
+ 
+ </td>
+<td>
+ 
+ 4.75e-035
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ 
+ 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):
+ 
+
+ <img src="../../../equations/lanczos7.png">
+ 
+
+ This form is more convenient for calculating lgamma, but for the gamma function
+ the division by e 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.
+ 
+<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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ (Specific detailed sources for individual functions and distributions are
+ given at the end of each individual section).
+ 
+
+ <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.
+ 
+
+ 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..
+ 
+
+ 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.
+ 
+
+ <a href="http://www.itl.nist.gov/div898/handbook/index.htm" target="_top">NIST/SEMATECH
+ e-Handbook of Statistical Methods</a>
+ 
+
+ <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.
+ 
+
+ <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.
+ 
+
+ Statistical Distributions (Wiley Series in Probability & Statistics)
+ (Paperback) by N.A.J. Hastings, Brian Peacock, Merran Evans, ISBN: 0471371246,
+ Wiley 2000.
+ 
+
+ <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.
+ 
+
+ <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>
+ 
+<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>
+
+ http://www.adsciengineering.combpdcalc
+ Binomial Probability Distribution Calculator.
+ 
+<a name="math_toolkit.backgrounders.refs.other_libraries"></a><h5>
+<a name="id790724"></a>
+ Other Libraries
+ </h5>
+
+ Cephes library by Shephen
+ Moshier and his book:
+ 
+
+ Methods and programs for mathematical functions, Stephen L B Moshier, Ellis
+ Horwood (1989) ISBN 0745802893 0470216093 provided inspiration.
+ 
+
+ 100-decimal digit calculator
+ provided some spot values.
+ 
+
+ <a href="http://www.csit.fsu.edu/~burkardt/cpp_src/dcdflib/dcdflib.html" target="_top">C++
+ version</a>.
+ 
+
+ <a href="../../lib.stat.cmu.edu/general/cdflib" target="_top">CDFLIB Library of Fortran Routines
+ for Cumulative Distribution functions.</a>
+ 
+
+ <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.
+ 
+
+ http://www.softintegration.com/docs/packagechnagstat
+ 
+
+ NAG libraries.
+ 
+
+ MathCAD
+ 
+
+ <a href="http://www.vni.com/products/imsl/jmsl/v30/api/com/imsl/stat/Cdf.html" target="_top">JMSL
+ Numerical Library</a> (Java).
+ 
+
+ John F Hart, Computer Approximations, (1978) ISBN 0 088275 642-7.
+ 
+
+ William J Cody, Software Manual for the Elementary Functions, Prentice-Hall
+ (1980) ISBN 0138220646.
+ 
+
+ Nico Temme, Special Functions, An Introduction to the Classical Functions
+ of Mathematical Physics, Wiley, ISBN: 0471-11313-1 (1996) who also gave valueable
+ advice.
+ 
+
+ <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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ Given an actual value a and a found value v
+ the relative error can be calculated from:
+ 
+
+ <img src="../../../equations/error2.png">
+ 
+
+ However the test programs in the library use the symmetrical form:
+ 
+
+ <img src="../../../equations/error1.png">
+ 
+
+ which measures relative difference 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.
+ 
+
+ 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">std::numeric_limits<>::min()</code>: in other words all denormalised numbers
+ are regarded as a zero.
+ 
+
+ All the test programs calculate quantized relative error,
+ whereas the graphs in this manual are produced with the actual
+ error. 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 units
+ in the last place either rounded up from the actual error, or
+ rounded down (possibly to zero). In contrast the true error
+ 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 units in the last place.
+ 
+
+ Note that throughout this manual and the test programs the relative error
+ is usually quoted in units of epsilon. However, remember that units
+ in the last place more accurately reflect the number of contaminated
+ digits, and that relative error can "wobble"
+ by a factor of 2 compared to units in the last place.
+ 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!
+ 
+<a name="zero_error"></a>
+ 
+<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>
+
+ 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
+ transcendental number 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 the table makers dilemma: 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....
+ 
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ 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.
+ 
+
+ 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:
+ 
+
+ Eabs(x) = f(x) - R(x)
+ 
+
+ which is expressed in terms of absolute error, but we can equally use relative
+ error:
+ 
+
+ Erel(x) = (f(x) - R(x)) / |f(x)|
+ 
+
+ 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.
+ 
+
+ 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:
+ 
+<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>
+
+ That means that if we know the location of the extrema of the error function
+ then we can write N+2 simultaneous equations:
+ 
+
+ R(xi) + (-1)iE = f(xi)
+ 
+
+ where E is the maximal error term, and xi 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.
+ 
+
+ Unfortunately we don't know where the extrema of the error function
+ are located!
+ 
+<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>
+
+ 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.
+ 
+
+ In the following discussion we'll use a concrete example to illustrate the
+ Remez method: an approximation to the function ex over the range [-1, 1].
+ 
+
+ 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).
+ 
+
+ In order to obtain the N+1 coefficients of the interpolated polynomial we
+ need N+1 points (x0...xN): with our interpolated form passing through each
+ of those points that yields N+1 simultaneous equations:
+ 
+
+ f(xi) = P(xi) = c0 + c1xi ... + cNxiN
+ 
+
+ Which can be solved for the coefficients c0...cN in P(x).
+ 
+
+ 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 relative error we get the following
+ error function:
+ 
+
+ <img src="../../../graphs/remez-2.png" alt="remez-2">
+ 
+
+ Which has a peak relative error of 1.2x10-3.
+ 
+
+ 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 Chebyshev
+ control points.
+ 
+<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">
+
+ In the simple case of a polynomial approximation, by interpolating through
+ the roots of a Chebyshev polynomial we have in fact created a Chebyshev
+ approximation to the function: in terms of absolute
+ error this is the best a priori choice for the interpolated
+ form we can achieve, and typically is very close to the minimax solution.
+ 
+
+ However, if we want to optimise for relative error,
+ or if the approximation is a rational function, then the initial Chebyshev
+ solution can be quite far from the ideal minimax solution.
+ 
+
+ 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>.
+ 
+</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>
+
+ The first step in the Remez method, given our current set of N+2 Chebyshev
+ control points xi, is to solve the N+2 simultaneous equations:
+ 
+
+ P(xi) + (-1)iE = f(xi)
+ 
+
+ To obtain the error term E, and the coefficients of the polynomial P(x).
+ 
+
+ This gives us a new approximation to f(x) that has the same error E
+ at each of the control points, and whose error function alternates
+ in sign 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:
+ 
+
+ <img src="../../../graphs/remez-3.png" alt="remez-3">
+ 
+
+ 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-4.
+ 
+<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>
+
+ 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.
+ 
+
+ We now have a choice: multi-point exchange, or single point exchange.
+ 
+
+ In single point exchange, we move the control point nearest to the largest
+ extrema to the absissa value of the extrema.
+ 
+
+ In multi-point exchange we swap all the current control points, for the locations
+ of the extrema.
+ 
+
+ In our example we perform multi-point exchange.
+ 
+<a name="math_toolkit.backgrounders.remez.iteration"></a><h5>
+<a name="id789799"></a>
+ Iteration
+ </h5>
+
+ 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.
+ 
+
+ For our current example, two more iterations converges on a minimax solution
+ with a peak relative error of 5x10-4 and an error function that looks like:
+ 
+
+ <img src="../../../graphs/remez-4.png" alt="remez-4">
+ 
+<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>
+
+ If we wish to extend the Remez method to a rational approximation of the
+ form
+ 
+
+ f(x) = R(x) = P(x) / Q(x)
+ 
+
+ 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.
+ 
+
+ The simultaneous equations to be solved are now:
+ 
+
+ P(xi) / Q(xi) + (-1)iE = f(xi)
+ 
+
+ Evaluated at the N+M+2 control points xi.
+ 
+
+ 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!
+ 
+
+ 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.
+ 
+
+ 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 ex, we obtained 5x10-4 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-5. That's a 5 fold increase in accuracy, for the same
+ number of terms overall.
+ 
+<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>
+
+ 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.
+ 
+
+ So far we have used a direct approximation:
+ 
+
+ f(x) = R(x)
+ 
+
+ 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.
+ 
+
+ 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:
+ 
+
+ f(x) = g(x) + R(x)
+ 
+
+ 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:
+ 
+
+ f(x) = g(x)(c + R(x))
+ 
+
+ Will yield a much better solution: here c is a constant
+ that is the approximate value of f(x)/g(x) and R(x) is typically tiny compared
+ to c. In this situation if R(x) is optimised for absolute
+ error, then as long as its error is small compared to the constant c,
+ that error will effectively get wiped out when R(x) is added to c.
+ 
+
+ 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-x2/x as x becomes large. Therefore using:
+ 
+
+ erfc(z) = (C + R(x)) e-x2/x
+ 
+
+ as the approximating form seems like an obvious thing to try, and does indeed
+ yield a useful approximation.
+ 
+
+ 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.
+ 
+
+ 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
+ ex over [-1,1], the initial interpolated form was some way from the minimax
+ solution:
+ 
+
+ <img src="../../../graphs/remez-2.png" alt="remez-2">
+ 
+
+ 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-3to 6x10-4:
+ 
+
+ <img src="../../../graphs/remez-5.png" alt="remez-5">
+ 
+
+ It's clearly still not ideal, but it is only a few percent away from our
+ desired minimax solution (5x10-4).
+ 
+<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>
+
+ 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.
+ 
+<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 b.
+ </li>
+</ul></div>
+<a name="math_toolkit.backgrounders.remez.references"></a><h5>
+<a name="id790344"></a>
+ References
+ </h5>
+
+ The original references for the Remez Method and it's extension to rational
+ functions are unfortunately in Russian:
+ 
+
+ Remez, E.Ya., Fundamentals of numerical methods for Chebyshev approximations,
+ "Naukova Dumka", Kiev, 1969.
+ 
+
+ Remez, E.Ya., Gavrilyuk, V.T., Computer development of certain
+ approaches to the approximate construction of solutions of Chebyshev problems
+ nonlinearly depending on parameters, Ukr. Mat. Zh. 12 (1960),
+ 324-338.
+ 
+
+ Gavrilyuk, V.T., Generalization of the first polynomial algorithm
+ of E.Ya.Remez for the problem of constructing rational-fractional Chebyshev
+ approximations, Ukr. Mat. Zh. 16 (1961), 575-585.
+ 
+
+ Some English language sources include:
+ 
+
+ Fraser, W., Hart, J.F., On the computation of rational approximations
+ to continuous functions, Comm. of the ACM 5 (1962), 401-403, 414.
+ 
+
+ Ralston, A., Rational Chebyshev approximation by Remes' algorithms,
+ Numer.Math. 7 (1965), no. 4, 322-330.
+ 
+
+ A. Ralston, Rational Chebyshev approximation, Mathematical Methods
+ for Digital Computers v. 2 (Ralston A., Wilf H., eds.), Wiley,
+ New York, 1967, pp. 264-284.
+ 
+
+ Hart, J.F. e.a., Computer approximations, Wiley, New
+ York a.o., 1968.
+ 
+
+ Cody, W.J., Fraser, W., Hart, J.F., Rational Chebyshev approximation
+ using linear equations, Numer.Math. 12 (1968), 242-251.
+ 
+
+ Cody, W.J., A survey of practical rational and polynomial approximation
+ of functions, SIAM Review 12 (1970), no. 3, 400-423.
+ 
+
+ Barrar, R.B., Loeb, H.J., On the Remez algorithm for non-linear
+ families, Numer.Math. 15 (1970), 382-391.
+ 
+
+ Dunham, Ch.B., Convergence of the Fraser-Hart algorithm for rational
+ Chebyshev approximation, Math. Comp. 29 (1975), no. 132, 1078-1082.
+ 
+
+ G. L. Litvinov, Approximate construction of rational approximations
+ and the effect of error autocorrection, Russian Journal of Mathematical
+ Physics, vol.1, No. 3, 1994.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="dist/stat_tut.html"> Statistical Distributions
+ Tutorial</a></dt>
+<dd><dl>
+<dt> Overview</dt>
+<dt> Worked Examples</dt>
+<dd><dl>
+<dt><a href="dist/stat_tut/weg/dist_construct_eg.html">
+ Distribution Construction Example</a></dt>
+<dt><a href="dist/stat_tut/weg/st_eg.html"> Student's
+ t Distribution Examples</a></dt>
+<dd><dl>
+<dt><a href="dist/stat_tut/weg/st_eg/tut_mean_intervals.html">
+ Calculating confidence intervals on the mean with the Students-t distribution</a></dt>
+<dt><a href="dist/stat_tut/weg/st_eg/tut_mean_test.html">
+ Testing a sample mean for difference from a "true" mean</a></dt>
+<dt><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></dt>
+<dt><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></dt>
+<dt><a href="dist/stat_tut/weg/st_eg/paired_st.html">
+ Comparing two paired samples with the Student's t distribution</a></dt>
+</dl></dd>
+<dt><a href="dist/stat_tut/weg/cs_eg.html"> Chi Squared
+ Distribution Examples</a></dt>
+<dd><dl>
+<dt><a href="dist/stat_tut/weg/cs_eg/chi_sq_intervals.html">
+ Confidence Intervals on the Standard Deviation</a></dt>
+<dt><a href="dist/stat_tut/weg/cs_eg/chi_sq_test.html">
+ Chi-Square Test for the Standard Deviation</a></dt>
+<dt><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></dt>
+</dl></dd>
+<dt><a href="dist/stat_tut/weg/f_eg.html"> F Distribution
+ Examples</a></dt>
+<dt><a href="dist/stat_tut/weg/binom_eg.html"> Binomial
+ Distribution Examples</a></dt>
+<dd><dl>
+<dt><a href="dist/stat_tut/weg/binom_eg/binomial_coinflip_example.html">
+ Binomial Coin-Flipping Example</a></dt>
+<dt><a href="dist/stat_tut/weg/binom_eg/binomial_quiz_example.html">
+ Binomial Quiz Example</a></dt>
+<dt><a href="dist/stat_tut/weg/binom_eg/binom_conf.html">
+ Calculating Confidence Limits on the Frequency of Occurrence for a Binomial
+ Distribution</a></dt>
+<dt><a href="dist/stat_tut/weg/binom_eg/binom_size_eg.html">
+ Estimating Sample Sizes for a Binomial Distribution.</a></dt>
+</dl></dd>
+<dt><a href="dist/stat_tut/weg/neg_binom_eg.html"> Negative
+ Binomial Distribution Examples</a></dt>
+<dd><dl>
+<dt><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></dt>
+<dt><a href="dist/stat_tut/weg/neg_binom_eg/neg_binom_size_eg.html">
+ Estimating Sample Sizes for the Negative Binomial.</a></dt>
+<dt><a href="dist/stat_tut/weg/neg_binom_eg/negative_binomial_example1.html">
+ Negative Binomial Sales Quota Example.</a></dt>
+<dt><a href="dist/stat_tut/weg/neg_binom_eg/negative_binomial_example2.html">
+ Negative Binomial Table Printing Example.</a></dt>
+</dl></dd>
+<dt><a href="dist/stat_tut/weg/normal_example.html"> Normal
+ Distribution Examples</a></dt>
+<dd><dl><dt><a href="dist/stat_tut/weg/normal_example/normal_misc.html">
+ Some Miscellaneous Examples of the Normal (Gaussian) Distribution</a></dt></dl></dd>
+<dt><a href="dist/stat_tut/weg/error_eg.html"> Error Handling
+ Example</a></dt>
+<dt><a href="dist/stat_tut/weg/find_eg.html"> Find Location
+ and Scale Examples</a></dt>
+<dd><dl>
+<dt><a href="dist/stat_tut/weg/find_eg/find_location_eg.html">
+ Find Location (Mean) Example</a></dt>
+<dt><a href="dist/stat_tut/weg/find_eg/find_scale_eg.html">
+ Find Scale (Standard Deviation) Example</a></dt>
+<dt><a href="dist/stat_tut/weg/find_eg/find_mean_and_sd_eg.html">
+ Find mean and standard deviation example</a></dt>
+</dl></dd>
+<dt><a href="dist/stat_tut/weg/nag_library.html"> Comparison
+ with C, R, FORTRAN-style Free Functions</a></dt>
+</dl></dd>
+<dt><a href="dist/stat_tut/variates.html"> Random Variates
+ and Distribution Parameters</a></dt>
+<dt><a href="dist/stat_tut/dist_params.html"> Discrete Probability
+ Distributions</a></dt>
+</dl></dd>
+<dt><a href="dist/dist_ref.html"> Statistical Distributions
+ Reference</a></dt>
+<dd><dl>
+<dt> Non-Member Properties</dt>
+<dt> Distributions</dt>
+<dd><dl>
+<dt><a href="dist/dist_ref/dists/bernoulli_dist.html">
+ Bernoulli Distribution</a></dt>
+<dt><a href="dist/dist_ref/dists/beta_dist.html"> Beta
+ Distribution</a></dt>
+<dt><a href="dist/dist_ref/dists/binomial_dist.html">
+ Binomial Distribution</a></dt>
+<dt><a href="dist/dist_ref/dists/cauchy_dist.html"> Cauchy-Lorentz
+ Distribution</a></dt>
+<dt><a href="dist/dist_ref/dists/chi_squared_dist.html">
+ Chi Squared Distribution</a></dt>
+<dt><a href="dist/dist_ref/dists/exp_dist.html"> Exponential
+ Distribution</a></dt>
+<dt><a href="dist/dist_ref/dists/extreme_dist.html"> Extreme
+ Value Distribution</a></dt>
+<dt> F Distribution</dt>
+<dt><a href="dist/dist_ref/dists/gamma_dist.html"> Gamma
+ (and Erlang) Distribution</a></dt>
+<dt><a href="dist/dist_ref/dists/lognormal_dist.html">
+ Log Normal Distribution</a></dt>
+<dt><a href="dist/dist_ref/dists/negative_binomial_dist.html">
+ Negative Binomial Distribution</a></dt>
+<dt><a href="dist/dist_ref/dists/normal_dist.html"> Normal
+ (Gaussian) Distribution</a></dt>
+<dt><a href="dist/dist_ref/dists/pareto.html"> Pareto
+ Distribution</a></dt>
+<dt><a href="dist/dist_ref/dists/poisson_dist.html"> Poisson
+ Distribution</a></dt>
+<dt><a href="dist/dist_ref/dists/rayleigh.html"> Rayleigh
+ Distribution</a></dt>
+<dt><a href="dist/dist_ref/dists/students_t_dist.html">
+ Students t Distribution</a></dt>
+<dt><a href="dist/dist_ref/dists/triangular_dist.html">
+ Triangular Distribution</a></dt>
+<dt><a href="dist/dist_ref/dists/weibull.html"> Weibull
+ Distribution</a></dt>
+<dt><a href="dist/dist_ref/dists/uniform_dist.html"> Uniform
+ Distribution</a></dt>
+</dl></dd>
+<dt><a href="dist/dist_ref/dist_algorithms.html"> Distribution
+ Algorithms</a></dt>
+</dl></dd>
+<dt> Extras/Future Directions</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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> Non-Member Properties</dt>
+<dt> Distributions</dt>
+<dd><dl>
+<dt><a href="dist_ref/dists/bernoulli_dist.html">
+ Bernoulli Distribution</a></dt>
+<dt><a href="dist_ref/dists/beta_dist.html"> Beta
+ Distribution</a></dt>
+<dt><a href="dist_ref/dists/binomial_dist.html">
+ Binomial Distribution</a></dt>
+<dt><a href="dist_ref/dists/cauchy_dist.html"> Cauchy-Lorentz
+ Distribution</a></dt>
+<dt><a href="dist_ref/dists/chi_squared_dist.html">
+ Chi Squared Distribution</a></dt>
+<dt><a href="dist_ref/dists/exp_dist.html"> Exponential
+ Distribution</a></dt>
+<dt><a href="dist_ref/dists/extreme_dist.html"> Extreme
+ Value Distribution</a></dt>
+<dt> F Distribution</dt>
+<dt><a href="dist_ref/dists/gamma_dist.html"> Gamma
+ (and Erlang) Distribution</a></dt>
+<dt><a href="dist_ref/dists/lognormal_dist.html">
+ Log Normal Distribution</a></dt>
+<dt><a href="dist_ref/dists/negative_binomial_dist.html">
+ Negative Binomial Distribution</a></dt>
+<dt><a href="dist_ref/dists/normal_dist.html"> Normal
+ (Gaussian) Distribution</a></dt>
+<dt><a href="dist_ref/dists/pareto.html"> Pareto
+ Distribution</a></dt>
+<dt><a href="dist_ref/dists/poisson_dist.html"> Poisson
+ Distribution</a></dt>
+<dt><a href="dist_ref/dists/rayleigh.html"> Rayleigh
+ Distribution</a></dt>
+<dt><a href="dist_ref/dists/students_t_dist.html">
+ Students t Distribution</a></dt>
+<dt><a href="dist_ref/dists/triangular_dist.html">
+ Triangular Distribution</a></dt>
+<dt><a href="dist_ref/dists/weibull.html"> Weibull
+ Distribution</a></dt>
+<dt><a href="dist_ref/dists/uniform_dist.html"> Uniform
+ Distribution</a></dt>
+</dl></dd>
+<dt><a href="dist_ref/dist_algorithms.html"> Distribution
+ Algorithms</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ 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.
+ 
+
+ Complement versions are also provided, both with explicit and implicit
+ (default) policy.
+ 
+<pre class="programlisting">
+using boost::math::policies::policy; // May be needed by users defining their own policies.
+using boost::math::complement; // Will be needed by users who want to use complements.
+</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/find_location.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class Dist, class Policy> // explicit error handling policy
+ typename Dist::value_type find_location( // For example, normal mean.
+ typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
+ // For example, a nominal minimum acceptable z, so that p * 100 % are > z
+ typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
+ typename Dist::value_type scale, // scale parameter, for example, normal standard deviation.
+ const Policy& pol);
+
+template <class Dist> // with default policy.
+ typename Dist::value_type find_location( // For example, normal mean.
+ typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
+ // For example, a nominal minimum acceptable z, so that p * 100 % are > z
+ typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
+ typename Dist::value_type scale); // scale parameter, for example, normal standard deviation.
+
+ }} // namespaces
+</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/find_scale.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class Dist, class Policy>
+ typename Dist::value_type find_scale( // For example, normal mean.
+ typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
+ // For example, a nominal minimum acceptable weight z, so that p * 100 % are > z
+ typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
+ typename Dist::value_type location, // location parameter, for example, normal distribution mean.
+ const Policy& pol);
+
+ template <class Dist> // with default policy.
+ typename Dist::value_type find_scale( // For example, normal mean.
+ typename Dist::value_type z, // location of random variable z to give probability, P(X > z) == p.
+ // For example, a nominal minimum acceptable z, so that p * 100 % are > z
+ typename Dist::value_type p, // probability value desired at x, say 0.95 for 95% > z.
+ typename Dist::value_type location) // location parameter, for example, normal distribution mean.
+}} // namespaces
+</pre>
+
+ All argument must be finite, otherwise domain_error
+ is called.
+ 
+
+ Probability arguments must be [0, 1], otherwise domain_error
+ is called.
+ 
+
+ 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.
+ 
+
+ <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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="dists/bernoulli_dist.html">
+ Bernoulli Distribution</a></dt>
+<dt><a href="dists/beta_dist.html"> Beta
+ Distribution</a></dt>
+<dt><a href="dists/binomial_dist.html">
+ Binomial Distribution</a></dt>
+<dt><a href="dists/cauchy_dist.html"> Cauchy-Lorentz
+ Distribution</a></dt>
+<dt><a href="dists/chi_squared_dist.html">
+ Chi Squared Distribution</a></dt>
+<dt><a href="dists/exp_dist.html"> Exponential
+ Distribution</a></dt>
+<dt><a href="dists/extreme_dist.html"> Extreme
+ Value Distribution</a></dt>
+<dt> F Distribution</dt>
+<dt><a href="dists/gamma_dist.html"> Gamma
+ (and Erlang) Distribution</a></dt>
+<dt><a href="dists/lognormal_dist.html">
+ Log Normal Distribution</a></dt>
+<dt><a href="dists/negative_binomial_dist.html">
+ Negative Binomial Distribution</a></dt>
+<dt><a href="dists/normal_dist.html"> Normal
+ (Gaussian) Distribution</a></dt>
+<dt><a href="dists/pareto.html"> Pareto
+ Distribution</a></dt>
+<dt><a href="dists/poisson_dist.html"> Poisson
+ Distribution</a></dt>
+<dt><a href="dists/rayleigh.html"> Rayleigh
+ Distribution</a></dt>
+<dt><a href="dists/students_t_dist.html">
+ Students t Distribution</a></dt>
+<dt><a href="dists/triangular_dist.html">
+ Triangular Distribution</a></dt>
+<dt><a href="dists/weibull.html"> Weibull
+ Distribution</a></dt>
+<dt><a href="dists/uniform_dist.html"> Uniform
+ Distribution</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/bernoulli.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+ template <class RealType = double,
+ class Policy = policies::policy<> >
+ class bernoulli_distribution;
+
+ typedef bernoulli_distribution<> bernoulli;
+
+ template <class RealType, class Policy>
+ class bernoulli_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ bernoulli_distribution(RealType p); // Constructor.
+ // Accessor function.
+ RealType success_fraction() const
+ // Probability of success (as a fraction).
+ };
+}} // namespaces
+</pre>
+
+ 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.
+ 
+
+ The Bernoulli distribution is the simplest building block on which other
+ discrete distributions of sequences of independent Bernoulli trials can
+ be based.
+ 
+
+ The Bernoulli is the binomial distribution (k = 1, p) with only one trial.
+ 
+
+ <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.
+ 
+
+ 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:
+ 
+
+ <img src="../../../../../graphs/bernoulli_pdf.png" alt="bernoulli_pdf">
+ 
+
+ and the <a href="http://en.wikipedia.org/wiki/Cumulative_Distribution_Function" target="_top">Cumulative
+ distribution function</a>
+ 
+
+ <img src="../../../../../graphs/bernoulli_cdf.png" alt="bernoulli_cdf">
+ 
+<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">
+bernoulli_distribution(RealType p);
+</pre>
+
+ Constructs a <a href="http://en.wikipedia.org/wiki/bernoulli_distribution" target="_top">bernoulli
+ distribution</a> with success_fraction p.
+ 
+<pre class="programlisting">
+RealType success_fraction() const
+</pre>
+
+ Returns the success_fraction parameter of this distribution.
+ 
+<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>
+
+ 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.
+ 
+
+ The domain of the random variable is 0 and 1, and the useful supported
+ range is only 0 or 1.
+ 
+
+ Outside this range, functions are undefined, or may throw domain_error
+ exception and make an error message available.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.bernoulli_dist.accuracy"></a><h5>
+<a name="id576854"></a>
+ Accuracy
+ </h5>
+
+ The Bernoulli distribution is implemented with simple arithmetic operators
+ and so should have errors within an epsilon or two.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.bernoulli_dist.implementation"></a><h5>
+<a name="id576885"></a>
+ Implementation
+ </h5>
+
+ In the following table p is the probability of success
+ and q = 1-p. k is the random
+ variate, either 0 or 1.
+ 
+<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">
+
+ The Bernoulli distribution is implemented here as a strict
+ discrete 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:
+ 
+
+ <code class="computeroutput">binomial_distribution(1,
+ 0.25)</code>
+ 
+</td></tr>
+</table></div>
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Supported range
+ 
+ </td>
+<td>
+ 
+ {0, 1}
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: pdf = 1 - p for k = 0, else p
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: cdf = 1 - p for k = 0, else 1
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ q = 1 - p
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ if x <= (1-p) 0 else 1
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ if x <= (1-p) 1 else 0
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ p
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ variance
+ 
+ </td>
+<td>
+ 
+ p * (1 - p)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ if (p < 0.5) 0 else 1
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ (1 - 2 * p) / sqrt(p * q)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ 6 * p * p - 6 * p +1/ p * q
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ kurtosis -3
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/beta.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+ template <class RealType = double,
+ class Policy = policies::policy<> >
+class beta_distribution;
+
+// typedef beta_distribution<double> beta;
+// Note that this is deliberately NOT provided,
+// to avoid a clash with the function name beta.
+
+template <class RealType, class Policy>
+class beta_distribution
+{
+public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Constructor from two shape parameters, alpha & beta:
+ beta_distribution(RealType a, RealType b);
+
+ // Parameter accessors:
+ RealType alpha() const;
+ RealType beta() const;
+
+ // Parameter estimators of alpha or beta from mean and variance.
+ static RealType find_alpha(
+ RealType mean, // Expected value of mean.
+ RealType variance); // Expected value of variance.
+
+ static RealType find_beta(
+ RealType mean, // Expected value of mean.
+ RealType variance); // Expected value of variance.
+
+ // Parameter estimators from from
+ // either alpha or beta, and x and probability.
+
+ static RealType find_alpha(
+ RealType beta, // from beta.
+ RealType x, // x.
+ RealType probability); // cdf
+
+ static RealType find_beta(
+ RealType alpha, // alpha.
+ RealType x, // probability x.
+ RealType probability); // probability cdf.
+};
+
+}} // namespaces
+</pre>
+
+ The class type <code class="computeroutput">beta_distribution</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>.
+ 
+
+ 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>.
+ 
+
+ 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>.
+ 
+
+ 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.
+ 
+
+ 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:
+ 
+
+ f(x;α,β) = xα - 1 (1 - x)β -1 / B(α, β)
+ 
+
+ where B(α, β) 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.
+ 
+
+ The following graph illustrates examples of the pdf for various values
+ of the shape parameters. Note the α = β = 2 (blue line) is dome-shaped, and
+ might be approximated by a symmetrical triangular distribution.
+ 
+
+ <img src="../../../../../graphs/beta_dist.png" alt="beta_dist">
+ 
+
+ If α = β = 1, then it is a 
+<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 α and β are < 1, then the pdf is U-shaped. If α != β, then the shape
+ is asymmetric and could be approximated by a triangle whose apex is away
+ from the centre (where x = half).
+ 
+<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">
+beta_distribution(RealType alpha, RealType beta);
+</pre>
+
+ Constructs a beta distribution with shape parameters alpha
+ and beta.
+ 
+
+ Requires alpha,beta > 0,otherwise domain_error
+ is called. Note that technically the beta distribution is defined for
+ alpha,beta >= 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.
+ 
+
+ For example:
+ 
+<pre class="programlisting">
+beta_distribution<> mybeta(2, 5);
+</pre>
+
+ Constructs a the beta distribution with alpha=2 and beta=5 (shown in
+ yellow in the graph above).
+ 
+<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">
+RealType alpha() const;
+</pre>
+
+ Returns the parameter alpha from which this distribution
+ was constructed.
+ 
+<pre class="programlisting">
+RealType beta() const;
+</pre>
+
+ Returns the parameter beta from which this distribution
+ was constructed.
+ 
+
+ So for example:
+ 
+<pre class="programlisting">
+beta_distribution<> mybeta(2, 5);
+assert(mybeta.alpha() == 2.); // mybeta.alpha() returns 2
+assert(mybeta.beta() == 5.); // mybeta.beta() returns 5
+</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>
+
+ Two pairs of parameter estimators are provided.
+ 
+
+ One estimates either α or β 
+from presumed-known mean and variance.
+ 
+
+ The other pair estimates either α or β from the cdf and x.
+ 
+
+ It is also possible to estimate α and β from 'known' mode & 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.
+ 
+<pre class="programlisting">
+static RealType find_alpha(
+ RealType mean, // Expected value of mean.
+ RealType variance); // Expected value of variance.
+</pre>
+
+ Returns the unique value of α that corresponds to a beta distribution with
+ mean mean and variance variance.
+ 
+<pre class="programlisting">
+static RealType find_beta(
+ RealType mean, // Expected value of mean.
+ RealType variance); // Expected value of variance.
+</pre>
+
+ Returns the unique value of β that corresponds to a beta distribution with
+ mean mean and variance variance.
+ 
+<pre class="programlisting">
+static RealType find_alpha(
+ RealType beta, // from beta.
+ RealType x, // x.
+ RealType probability); // probability cdf
+</pre>
+
+ Returns the value of α that gives: <code class="computeroutput">cdf(beta_distribution<RealType>(alpha, beta), x) == probability</code>.
+ 
+<pre class="programlisting">
+static RealType find_beta(
+ RealType alpha, // alpha.
+ RealType x, // probability x.
+ RealType probability); // probability cdf.
+</pre>
+
+ Returns the value of β that gives: <code class="computeroutput">cdf(beta_distribution<RealType>(alpha, beta), x) == probability</code>.
+ 
+<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>
+
+ 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.
+ 
+
+ 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>.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.beta_dist.applications"></a><h5>
+<a name="id579696"></a>
+ Applications
+ </h5>
+
+ 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.
+ 
+
+ It is also widely used in <a href="http://en.wikipedia.org/wiki/Bayesian_inference" target="_top">Bayesian
+ statistical inference</a>.
+ 
+<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>
+
+ The beta distribution with both α and β = 1 follows a <a href="http://en.wikipedia.org/wiki/Uniform_distribution_%28continuous%29" target="_top">uniform
+ distribution</a>.
+ 
+
+ The triangular
+ is used when less precise information is available.
+ 
+
+ The <a href="http://en.wikipedia.org/wiki/Binomial_distribution" target="_top">binomial
+ distribution</a> is closely related when α and β are integers.
+ 
+
+ With integer values of α and β 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.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.beta_dist.accuracy"></a><h5>
+<a name="id579831"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.beta_dist.implementation"></a><h5>
+<a name="id579909"></a>
+ Implementation
+ </h5>
+
+ In the following table a and b
+ are the parameters α and β, x is the random variable,
+ p is the probability and q = 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ f(x;α,β) = xα - 1 (1 - x)β -1 / B(α, β)
+ 
+ 
+ Implemented using ibeta_derivative(a,
+ b, x).
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the incomplete beta function ibeta(a,
+ b, x)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ ibetac(a,
+ b, x)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ Using the inverse incomplete beta function ibeta_inv(a,
+ b, p)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ ibetac_inv(a,
+ b, q)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">a/(a+b)</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ variance
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">a *
+ b /
+ (a+b)^2 * (a +
+ b +
+ 1)</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">(a-1) /
+ (a
+ + b
+ - 2)</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">2 (b-a)
+ sqrt(a+b+1)/(a+b+2) * sqrt(a
+ * b)</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ <img src="../../../../../equations/beta_dist_kurtosis.png">
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">kurtosis +
+ 3</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ parameter estimation
+ 
+ </td>
+<td>
+ 
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ alpha
+ 
+ 
+ from mean and variance
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">mean *
+ (( (mean *
+ (1
+ - mean)) /
+ variance)-
+ 1)</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ beta
+ 
+ 
+ from mean and variance
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">(1
+ - mean) *
+ (((mean
+ * (1 - mean))
+ /variance)-1)</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ The member functions <code class="computeroutput">find_alpha</code>
+ and <code class="computeroutput">find_beta</code>
+ 
+ 
+ from cdf and probability x
+ 
+ 
+ and either <code class="computeroutput">alpha</code>
+ or <code class="computeroutput">beta</code>
+ 
+ </td>
+<td>
+ 
+ Implemented in terms of the inverse incomplete beta functions
+ 
+ 
+ ibeta_inva,
+ and ibeta_invb
+ respectively.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">find_alpha</code>
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">ibeta_inva(beta,
+ x,
+ probability)</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">find_beta</code>
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">ibeta_invb(alpha,
+ x,
+ probability)</code>
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.dist.dist_ref.dists.beta_dist.references"></a><h5>
+<a name="id581207"></a>
+ References
+ </h5>
+
+ <a href="http://en.wikipedia.org/wiki/Beta_distribution" target="_top">Wikipedia
+ Beta distribution</a>
+ 
+
+ <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366h.htm" target="_top">NIST
+ Exploratory Data Analysis</a>
+ 
+
+ <a href="http://mathworld.wolfram.com/BetaDistribution.html" target="_top">Wolfram
+ MathWorld</a>
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/binomial.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class RealType = double,
+ class Policy = policies::policy<> >
+class binomial_distribution;
+
+typedef binomial_distribution<> binomial;
+
+template <class RealType, class Policy>
+class binomial_distribution
+{
+public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ static const unspecified-type cloppper_pearson_exact_interval;
+ static const unspecified-type jeffreys_prior_interval;
+
+ // construct:
+ binomial_distribution(RealType n, RealType p);
+
+ // parameter access::
+ RealType success_fraction() const;
+ RealType trials() const;
+
+ // Bounds on success fraction:
+ static RealType find_lower_bound_on_p(
+ RealType trials,
+ RealType successes,
+ RealType probability,
+ unspecified-type method = clopper_pearson_exact_interval);
+ static RealType find_upper_bound_on_p(
+ RealType trials,
+ RealType successes,
+ RealType probability,
+ unspecified-type method = clopper_pearson_exact_interval);
+
+ // estimate min/max number of trials:
+ static RealType find_minimum_number_of_trials(
+ RealType k, // number of events
+ RealType p, // success fraction
+ RealType alpha); // risk level
+
+ static RealType find_maximum_number_of_trials(
+ RealType k, // number of events
+ RealType p, // success fraction
+ RealType alpha); // risk level
+};
+
+}} // namespaces
+</pre>
+
+ The class type <code class="computeroutput">binomial_distribution</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.
+ 
+<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">
+ 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.
+ </td></tr>
+</table></div>
+
+ The PDF for the binomial distribution is given by:
+ 
+
+ <img src="../../../../../equations/binomial_ref2.png">
+ 
+
+ The following two graphs illustrate how the PDF changes depending upon
+ the distributions parameters, first we'll keep the success fraction
+ p fixed at 0.5, and vary the sample size:
+ 
+
+ <img src="../../../../../graphs/binomial_pdf_1.png" alt="binomial_pdf_1">
+ 
+
+ Alternatively, we can keep the sample size fixed at N=20 and vary the
+ success fraction p:
+ 
+
+ <img src="../../../../../graphs/binomial_pdf_2.png" alt="binomial_pdf_2">
+ 
+
+ 
+<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">
+
+ The Binomial distribution is a discrete distribution: internally
+ functions like the <code class="computeroutput">cdf</code>
+ and <code class="computeroutput">pdf</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.
+ 
+
+ The quantile function will by default return an integer result that
+ has been rounded outwards. That is to say lower
+ quantiles (where the probability is less than 0.5) are rounded downward,
+ and upper quantiles (where the probability is greater than 0.5) are
+ rounded upwards. This behaviour ensures that if an X% quantile is
+ requested, then at least the requested coverage
+ will be present in the central region, and no more than
+ the requested coverage will be present in the tails.
+ 
+
+ This behaviour can be changed so that the quantile functions are
+ rounded differently, or even return a real-valued result using 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.
+ 
+</td></tr>
+</table></div>
+
+ 
+<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">
+binomial_distribution(RealType n, RealType p);
+</pre>
+
+ Constructor: n is the total number of trials, p
+ is the probability of success of a single trial.
+ 
+
+ Requires <code class="computeroutput">0 <=
+ p <=
+ 1</code>, and <code class="computeroutput">n
+ >= 0</code>,
+ otherwise calls domain_error.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.binomial_dist.accessors"></a><h6>
+<a name="id582697"></a>
+ Accessors
+ </h6>
+<pre class="programlisting">
+RealType success_fraction() const;
+</pre>
+
+ Returns the parameter p from which this distribution
+ was constructed.
+ 
+<pre class="programlisting">
+RealType trials() const;
+</pre>
+
+ Returns the parameter n from which this distribution
+ was constructed.
+ 
+<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">
+static RealType find_lower_bound_on_p(
+ RealType trials,
+ RealType successes,
+ RealType alpha,
+ unspecified-type method = clopper_pearson_exact_interval);
+</pre>
+
+ Returns a lower bound on the success fraction:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>trials</dt>
+<dd>
+ The total number of trials conducted.
+ </dd>
+<dt>successes</dt>
+<dd>
+ The number of successes that occurred.
+ </dd>
+<dt>alpha</dt>
+<dd>
+ The largest acceptable probability that the true value of the success
+ fraction is less than the value
+ returned.
+ </dd>
+<dt>method</dt>
+<dd>
+ An optional parameter that specifies the method to be used to compute
+ the interval (See below).
+ </dd>
+</dl>
+</div>
+
+ For example, if you observe k successes from n
+ trials the best estimate for the success fraction is simply k/n,
+ but if you want to be 95% sure that the true value is greater
+ than some value, pmin, then:
+ 
+<pre class="programlisting">
+pmin = binomial_distribution<RealType>::find_lower_bound_on_p(
+ n, k, 0.05);
+</pre>
+
+ <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>
+ 
+
+ There are currently two possible values available for the method
+ optional parameter: clopper_pearson_exact_interval
+ or jeffreys_prior_interval. These constants are
+ both members of class template <code class="computeroutput">binomial_distribution</code>,
+ so usage is for example:
+ 
+<pre class="programlisting">
+p = binomial_distribution<RealType>::find_lower_bound_on_p(
+ n, k, 0.05, binomial_distribution<RealType>::jeffreys_prior_interval);
+</pre>
+
+ 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">100(1-alpha)%</code> coverage, but which is known to be
+ overly conservative, sometimes producing intervals with much greater
+ than the requested coverage.
+ 
+
+ The alternative calculation method produces a non-informative Jeffreys
+ Prior interval. It produces <code class="computeroutput">100(1-alpha)%</code>
+ coverage only in the average case, 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.
+ 
+
+ 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.
+ 
+
+ The two methods provided here were chosen principally because they can
+ be used for both one and two sided intervals. See also:
+ 
+
+ Lawrence D. Brown, T. Tony Cai and Anirban DasGupta (2001), Interval
+ Estimation for a Binomial Proportion, Statistical Science, Vol. 16, No.
+ 2, 101-133.
+ 
+
+ T. Tony Cai (2005), One-sided confidence intervals in discrete distributions,
+ Journal of Statistical Planning and Inference 131, 63-88.
+ 
+
+ Agresti, A. and Coull, B. A. (1998). Approximate is better than "exact"
+ for interval estimation of binomial proportions. Amer. Statist. 52 119-126.
+ 
+
+ 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.
+ 
+<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">
+static RealType find_upper_bound_on_p(
+ RealType trials,
+ RealType successes,
+ RealType alpha,
+ unspecified-type method = clopper_pearson_exact_interval);
+</pre>
+
+ Returns an upper bound on the success fraction:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>trials</dt>
+<dd>
+ The total number of trials conducted.
+ </dd>
+<dt>successes</dt>
+<dd>
+ The number of successes that occurred.
+ </dd>
+<dt>alpha</dt>
+<dd>
+ The largest acceptable probability that the true value of the success
+ fraction is greater than the value
+ returned.
+ </dd>
+<dt>method</dt>
+<dd>
+ An optional parameter that specifies the method to be used to compute
+ the interval. Refer to the documentation for <code class="computeroutput">find_upper_bound_on_p</code>
+ above for the meaning of the method options.
+ </dd>
+</dl>
+</div>
+
+ For example, if you observe k successes from n
+ trials the best estimate for the success fraction is simply k/n,
+ but if you want to be 95% sure that the true value is less
+ than some value, pmax, then:
+ 
+<pre class="programlisting">
+pmax = binomial_distribution<RealType>::find_upper_bound_on_p(
+ n, k, 0.05);
+</pre>
+
+ <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>
+ 
+<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">
+
+ In order to obtain a two sided bound on the success fraction, you call
+ both <code class="computeroutput">find_lower_bound_on_p</code>
+ and <code class="computeroutput">find_upper_bound_on_p</code>
+ each with the same arguments.
+ 
+
+ If the desired risk level that the true success fraction lies outside
+ the bounds is α, then you pass α/2 to these functions.
+ 
+
+ So for example a two sided 95% confidence interval would be obtained
+ by passing α = 0.025 to each of the functions.
+ 
+
+ <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>
+ 
+</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">
+static RealType find_minimum_number_of_trials(
+ RealType k, // number of events
+ RealType p, // success fraction
+ RealType alpha); // probability threshold
+</pre>
+
+ This function estimates the minimum number of trials required to ensure
+ that more than k events is observed with a level of risk alpha
+ that k or fewer events occur.
+ 
+<div class="variablelist">
+
+<dl>
+<dt>k</dt>
+<dd>
+ The number of success observed.
+ </dd>
+<dt>p</dt>
+<dd>
+ The probability of success for each trial.
+ </dd>
+<dt>alpha</dt>
+<dd>
+ The maximum acceptable probability that k events or fewer will be
+ observed.
+ </dd>
+</dl>
+</div>
+
+ For example:
+ 
+<pre class="programlisting">
+binomial_distribution<RealType>::find_number_of_trials(10, 0.5, 0.05);
+</pre>
+
+ Returns the smallest number of trials we must conduct to be 95% sure
+ of seeing 10 events that occur with frequency one half.
+ 
+<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">
+static RealType find_maximum_number_of_trials(
+ RealType k, // number of events
+ RealType p, // success fraction
+ RealType alpha); // probability threshold
+</pre>
+
+ This function estimates the maximum number of trials we can conduct to
+ ensure that k successes or fewer are observed, with a risk alpha
+ that more than k occur.
+ 
+<div class="variablelist">
+
+<dl>
+<dt>k</dt>
+<dd>
+ The number of success observed.
+ </dd>
+<dt>p</dt>
+<dd>
+ The probability of success for each trial.
+ </dd>
+<dt>alpha</dt>
+<dd>
+ The maximum acceptable probability that more than k events will be
+ observed.
+ </dd>
+</dl>
+</div>
+
+ For example:
+ 
+<pre class="programlisting">
+binomial_distribution<RealType>::find_maximum_number_of_trials(0, 1e-6, 0.05);
+</pre>
+
+ 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.
+ 
+
+ <a href="../../stat_tut/weg/binom_eg/binom_size_eg.html" title="Estimating Sample Sizes for a Binomial Distribution.">See
+ Worked Example.</a>
+ 
+<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>
+
+ 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.
+ 
+
+ The domain for the random variable k is <code class="computeroutput">0 <= k <= N</code>, otherwise a domain_error
+ is returned.
+ 
+
+ It's worth taking a moment to define what these accessors actually mean
+ in the context of this distribution:
+ 
+<div class="table">
+<a name="id584676"></a>Table 7. Meaning of the non-member accessors
+<div class="table-contents"><table class="table" summary="Meaning of the non-member accessors">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Meaning
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Probability Density Function
+ 
+ </td>
+<td>
+ 
+ The probability of obtaining exactly k successes
+ from n trials with success fraction p. For example:
+ 
+ 
+ <code class="computeroutput">pdf(binomial(n,
+ p),
+ k)</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Cumulative Distribution Function
+ 
+ </td>
+<td>
+ 
+ The probability of obtaining k successes
+ or fewer from n trials with success fraction p. For
+ example:
+ 
+ 
+ <code class="computeroutput">cdf(binomial(n,
+ p),
+ k)</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../nmp.html#math.dist.ccdf">Complement of the Cumulative Distribution
+ Function</a>
+ 
+ </td>
+<td>
+ 
+ The probability of obtaining more than k
+ successes from n trials with success fraction p. For
+ example:
+ 
+ 
+ <code class="computeroutput">cdf(complement(binomial(n,
+ p),
+ k))</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Quantile
+ 
+ </td>
+<td>
+ 
+ The greatest 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:
+ 
+ 
+ <code class="computeroutput">quantile(binomial(n,
+ p),
+ P)</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../nmp.html#math.dist.quantile_c">Quantile from the complement
+ of the probability</a>
+ 
+ </td>
+<td>
+ 
+ The smallest 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:
+ 
+ 
+ <code class="computeroutput">quantile(complement(binomial(n,
+ p),
+ P))</code>`
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <a name="math_toolkit.dist.dist_ref.dists.binomial_dist.examples"></a><h5>
+<a name="id585235"></a>
+ Examples
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.binomial_dist.accuracy"></a><h5>
+<a name="id585275"></a>
+ Accuracy
+ </h5>
+
+ This distribution is implemented using the incomplete beta functions
+ ibeta
+ and ibetac,
+ please refer to these functions for information on accuracy.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.binomial_dist.implementation"></a><h5>
+<a name="id585325"></a>
+ Implementation
+ </h5>
+
+ In the following table p is the probability that
+ one trial will be successful (the success fraction), n
+ is the number of trials, k is the number of successes,
+ p is the probability and q = 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ Implementation is in terms of ibeta_derivative:
+ if nCk is the binomial coefficient of a and b, then we have:
+ 
+ 
+ <img src="../../../../../equations/binomial_ref1.png">
+ 
+ 
+ Which can be evaluated as <code class="computeroutput">ibeta_derivative(k+1, n-k+1, p) /
+ (n+1)</code>
+ 
+ 
+ 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.
+ 
+ 
+ There are also various special cases: refer to the code for details.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relation:
+ 
+ 
+
+
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">
+p = I[sub 1-p](n - k, k + 1)
+ = 1 - I[sub p](k + 1, n - k)
+ = ibetac(k + 1, n - k, p)</pre>
+
+ 
+ 
+ There are also various special cases: refer to the code for details.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: q = ibeta(k
+ + 1, n - k, p)
+ 
+ 
+ There are also various special cases: refer to the code for details.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ Since the cdf is non-linear in variate k
+ 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>).
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ Found numerically as above.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">p *
+ n</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ variance
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">p *
+ n *
+ (1-p)</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">floor(p *
+ (n
+ + 1))</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">(1
+ - 2
+ * p) /
+ sqrt(n *
+ p *
+ (1
+ - p))</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">3 -
+ (6
+ / n) +
+ (1
+ / (n *
+ p *
+ (1
+ - p)))</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">(1
+ - 6
+ * p
+ * q) /
+ (n
+ * p
+ * q)</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ parameter estimation
+ 
+ </td>
+<td>
+ 
+ The member functions <code class="computeroutput">find_upper_bound_on_p</code>
+ <code class="computeroutput">find_lower_bound_on_p</code>
+ and <code class="computeroutput">find_number_of_trials</code>
+ are implemented in terms of the inverse incomplete beta functions
+ ibetac_inv,
+ ibeta_inv,
+ and ibetac_invb
+ respectively
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/cauchy.hpp></pre>
+
+ 
+<pre class="programlisting">
+template <class RealType = double,
+ class Policy = policies::policy<> >
+class cauchy_distribution;
+
+typedef cauchy_distribution<> cauchy;
+
+template <class RealType, class Policy>
+class cauchy_distribution
+{
+public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ cauchy_distribution(RealType location = 0, RealType scale = 1);
+
+ RealType location()const;
+ RealType scale()const;
+};
+</pre>
+
+ 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:
+ 
+
+ <img src="../../../../../equations/cauchy_ref1.png">
+ 
+
+ The location parameter x0 is the location of the peak of the distribution
+ (the mode of the distribution), while the scale parameter γ 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.
+ 
+
+ 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.
+ 
+
+ The following graph shows how the distributions moves as the location
+ parameter changes:
+ 
+
+ <img src="../../../../../graphs/cauchy1.png" alt="cauchy1">
+ 
+
+ While the following graph shows how the shape (scale) parameter alters
+ the distribution:
+ 
+
+ <img src="../../../../../graphs/cauchy2.png" alt="cauchy2">
+ 
+<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">
+cauchy_distribution(RealType location = 0, RealType scale = 1);
+</pre>
+
+ Constructs a Cauchy distribution, with location parameter location
+ and scale parameter scale. When these parameters
+ take their default values (location = 0, scale = 1) then the result is
+ a Standard Cauchy Distribution.
+ 
+
+ Requires scale > 0, otherwise calls domain_error.
+ 
+<pre class="programlisting">
+RealType location()const;
+</pre>
+
+ Returns the location parameter of the distribution.
+ 
+<pre class="programlisting">
+RealType scale()const;
+</pre>
+
+ Returns the scale parameter of the distribution.
+ 
+<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>
+
+ 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.
+ 
+
+ 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>
+ 
+
+ to control whether these should fail to compile with a BOOST_STATIC_ASSERTION_FAILURE,
+ which is the default.
+ 
+
+ Alternately, the functions mean,
+ standard deviation, variance,
+ skewness, kurtosis
+ and kurtosis_excess
+ will all return a domain_error if
+ called.
+ 
+
+ The domain of the random variable is [-[max_value], +[min_value]].
+ 
+<a name="math_toolkit.dist.dist_ref.dists.cauchy_dist.accuracy"></a><h5>
+<a name="id587817"></a>
+ Accuracy
+ </h5>
+
+ The Cauchy distribution is implemented in terms of the standard library
+ <code class="computeroutput">tan</code> and <code class="computeroutput">atan</code> functions, and as such should
+ have very low error rates.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.cauchy_dist.implementation"></a><h5>
+<a name="id587872"></a>
+ Implementation
+ </h5>
+
+ In the following table x0 is the location parameter of the distribution,
+ γ is its scale parameter, x is the random variate,
+ p is the probability and q = 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: pdf = 1 / (π * γ * (1 + ((x - x0 ) / γ)2)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf and its complement
+ 
+ </td>
+<td>
+ 
+ The cdf is normally given by:
+ 
+ 
+ p = 0.5 + atan(x)/π
+ 
+ 
+ But that suffers from cancellation error as x -> -∞. So recall
+ that for <code class="computeroutput">x <
+ 0</code>:
+ 
+ 
+ atan(x) = -π/2 - atan(1/x)
+ 
+ 
+ Substituting into the above we get:
+ 
+ 
+ p = -atan(1/x) ; x < 0
+ 
+ 
+ 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 - x0 ) / γ for x in the above.
+ 
+ 
+ This procedure yields the smaller of p and
+ q, so the result may need subtracting from
+ 1 depending on whether we want the complement or not, and whether
+ x is less than x0 or not.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ The same procedure is used irrespective of whether we're starting
+ from the probability or it's complement. First the argument
+ p is reduced to the range [-0.5, 0.5], then
+ the relation
+ 
+ 
+ x = x0 ± γ / tan(π * p)
+ 
+ 
+ is used to obtain the result. Whether we're adding or subtracting
+ from x0 is determined by whether we're starting from the complement
+ or not.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ The location parameter.
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/chi_squared.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class RealType = double,
+ class Policy = policies::policy<> >
+class chi_squared_distribution;
+
+typedef chi_squared_distribution<> chi_squared;
+
+template <class RealType, class Policy>
+class chi_squared_distribution
+{
+public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ // Constructor:
+ chi_squared_distribution(RealType i);
+
+ // Accessor to parameter:
+ RealType degrees_of_freedom()const;
+
+ // Parameter estimation:
+ static RealType find_degrees_of_freedom(
+ RealType difference_from_mean,
+ RealType alpha,
+ RealType beta,
+ RealType sd,
+ RealType hint = 100);
+};
+
+}} // namespaces
+</pre>
+
+ The Chi-Squared distribution is one of the most widely used distributions
+ in statistical tests. If χi are ν
+independent, normally distributed random
+ variables with means μi and variances σi2, then the random variable:
+ 
+
+ <img src="../../../../../equations/chi_squ_ref1.png">
+ 
+
+ is distributed according to the Chi-Squared distribution.
+ 
+
+ The Chi-Squared distribution is a special case of the gamma distribution
+ and has a single parameter ν that specifies the number of degrees of freedom.
+ The following graph illustrates how the distribution changes for different
+ values of ν:
+ 
+
+ <img src="../../../../../graphs/chi_square.png" alt="chi_square">
+ 
+<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">
+chi_squared_distribution(RealType v);
+</pre>
+
+ Constructs a Chi-Squared distribution with v degrees
+ of freedom.
+ 
+
+ Requires v > 0, otherwise calls domain_error.
+ 
+<pre class="programlisting">
+RealType degrees_of_freedom()const;
+</pre>
+
+ Returns the parameter v from which this object was
+ constructed.
+ 
+<pre class="programlisting">
+static RealType find_degrees_of_freedom(
+ RealType difference_from_variance,
+ RealType alpha,
+ RealType beta,
+ RealType variance,
+ RealType hint = 100);
+</pre>
+
+ Estimates the sample size required to detect a difference from a nominal
+ variance in a Chi-Squared test for equal standard deviations.
+ 
+<div class="variablelist">
+
+<dl>
+<dt>difference_from_variance</dt>
+<dd>
+ The difference from the assumed nominal variance that is to be detected:
+ Note that the sign of this value is critical, see below.
+ </dd>
+<dt>alpha</dt>
+<dd>
+ The maximum acceptable risk of rejecting the null hypothesis when
+ it is in fact true.
+ </dd>
+<dt>beta</dt>
+<dd>
+ The maximum acceptable risk of falsely failing to reject the null
+ hypothesis.
+ </dd>
+<dt>variance</dt>
+<dd>
+ The nominal variance being tested against.
+ </dd>
+<dt>hint</dt>
+<dd>
+ An optional hint on where to start looking for a result: the current
+ sample size would be a good choice.
+ </dd>
+</dl>
+</div>
+
+ Note that this calculation works with variances
+ and not standard deviations.
+ 
+
+ The sign of the parameter difference_from_variance
+ 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 difference_from_variance)
+ or testing for a variance less than a nominal value (negative difference_from_variance).
+ If the latter, then obviously it is a requirement that <code class="computeroutput">variance +
+ difference_from_variance >
+ 0</code>, since no sample can have a negative
+ variance!
+ 
+
+ This procedure uses the method in Diamond, W. J. (1989). Practical Experiment
+ Designs, Van-Nostrand Reinhold, New York.
+ 
+
+ 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>.
+ 
+<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>
+
+ 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.
+ 
+
+ The domain of the random variable is [0, +∞].
+ 
+<a name="math_toolkit.dist.dist_ref.dists.chi_squared_dist.examples"></a><h5>
+<a name="id589544"></a>
+ Examples
+ </h5>
+
+ Various worked examples
+ are available illustrating the use of the Chi Squared Distribution.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.chi_squared_dist.accuracy"></a><h5>
+<a name="id589585"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.chi_squared_dist.implementation"></a><h5>
+<a name="id589627"></a>
+ Implementation
+ </h5>
+
+ In the following table v is the number of degrees
+ of freedom of the distribution, x is the random
+ variate, p is the probability, and q =
+ 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: pdf = gamma_p_derivative(v
+ / 2, x / 2) / 2
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: p = gamma_p(v
+ / 2, x / 2)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: q = gamma_q(v
+ / 2, x / 2)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = 2 * gamma_p_inv(v
+ / 2, p)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = 2 * gamma_q_inv(v
+ / 2, p)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ v
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ variance
+ 
+ </td>
+<td>
+ 
+ 2v
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ v - 2 (if v >= 2)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ 2 * sqrt(2 / v) == sqrt(8 / v)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ 3 + 12 / v
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ 12 / v
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/exponential.hpp></pre>
+
+ 
+<pre class="programlisting">
+template <class RealType = double,
+ class Policy = policies::policy<> >
+class exponential_distribution;
+
+typedef exponential_distribution<> exponential;
+
+template <class RealType, class Policy>
+class exponential_distribution
+{
+public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ exponential_distribution(RealType lambda = 1);
+
+ RealType lambda()const;
+};
+</pre>
+
+ 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:
+ 
+
+ <img src="../../../../../equations/exponential_dist_ref1.png">
+ 
+
+ It is often used to model the time between independent events that happen
+ at a constant average rate.
+ 
+
+ The following graph shows how the distribution changes for different
+ values of the rate parameter lambda:
+ 
+
+ <img src="../../../../../graphs/exponential_dist.png" alt="exponential_dist">
+ 
+<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">
+exponential_distribution(RealType lambda = 1);
+</pre>
+
+ Constructs an <a href="http://en.wikipedia.org/wiki/Exponential_distribution" target="_top">Exponential
+ distribution</a> with parameter lambda. Lambda
+ is defined as the reciprocal of the scale parameter.
+ 
+
+ Requires lambda > 0, otherwise calls domain_error.
+ 
+<pre class="programlisting">
+RealType lambda()const;
+</pre>
+
+ Accessor function returns the lambda parameter of the distribution.
+ 
+<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>
+
+ 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.
+ 
+
+ The domain of the random variable is [0, +∞].
+ 
+<a name="math_toolkit.dist.dist_ref.dists.exp_dist.accuracy"></a><h5>
+<a name="id590856"></a>
+ Accuracy
+ </h5>
+
+ The exponential distribution is implemented in terms of the standard
+ library functions <code class="computeroutput">exp</code>,
+ <code class="computeroutput">log</code>, <code class="computeroutput">log1p</code>
+ and <code class="computeroutput">expm1</code> and as such
+ should have very low error rates.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.exp_dist.implementation"></a><h5>
+<a name="id590933"></a>
+ Implementation
+ </h5>
+
+ In the following table λ is the parameter lambda of the distribution,
+ x is the random variate, p
+ is the probability and q = 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: pdf = λ * exp(-λ * x)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: p = 1 - exp(-x * λ) = -expm1(-x * λ)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: q = exp(-x * λ)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = -log(1-p) / λ = -log1p(-p) / λ
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = -log(q) / λ
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ 1/λ
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ standard deviation
+ 
+ </td>
+<td>
+ 
+ 1/λ
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ 0
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ 2
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ 9
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ 6
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/extreme.hpp></pre>
+
+ 
+<pre class="programlisting">
+template <class RealType = double,
+ class Policy = policies::policy<> >
+class extreme_value_distribution;
+
+typedef extreme_value_distribution<> extreme_value;
+
+template <class RealType, class Policy>
+class extreme_value_distribution
+{
+public:
+ typedef RealType value_type;
+
+ extreme_value_distribution(RealType location = 0, RealType scale = 1);
+
+ RealType scale()const;
+ RealType location()const;
+};
+</pre>
+
+ 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.
+ 
+
+ Extreme value theory is important for assessing risk for highly unusual
+ events, such as 100-year floods.
+ 
+
+ 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.
+ 
+
+ The distribution has a PDF given by:
+ 
+
+ f(x) = (1/scale) e-(x-location)/scale e-e-(x-location)/scale
+ 
+
+ Which in the standard case (scale = 1, location = 0) reduces to:
+ 
+
+ f(x) = e-xe-e-x
+ 
+
+ The following graph illustrates how the PDF varies with the location
+ parameter:
+ 
+
+ <img src="../../../../../graphs/extreme_val_dist.png" alt="extreme_val_dist">
+ 
+
+ And this graph illustrates how the PDF varies with the shape parameter:
+ 
+
+ <img src="../../../../../graphs/extreme_val_dist2.png" alt="extreme_val_dist2">
+ 
+<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">
+extreme_value_distribution(RealType location = 0, RealType scale = 1);
+</pre>
+
+ Constructs an Extreme Value distribution with the specified location
+ and scale parameters.
+ 
+
+ Requires <code class="computeroutput">scale >
+ 0</code>, otherwise calls domain_error.
+ 
+<pre class="programlisting">
+RealType location()const;
+</pre>
+
+ Returns the location parameter of the distribution.
+ 
+<pre class="programlisting">
+RealType scale()const;
+</pre>
+
+ Returns the scale parameter of the distribution.
+ 
+<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>
+
+ 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.
+ 
+
+ The domain of the random parameter is [-∞, +∞].
+ 
+<a name="math_toolkit.dist.dist_ref.dists.extreme_dist.accuracy"></a><h5>
+<a name="id592316"></a>
+ Accuracy
+ </h5>
+
+ The extreme value distribution is implemented in terms of the standard
+ library <code class="computeroutput">exp</code> and <code class="computeroutput">log</code> functions and as such should have
+ very low error rates.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.extreme_dist.implementation"></a><h5>
+<a name="id592369"></a>
+ Implementation
+ </h5>
+
+ In the following table: a is the location parameter,
+ b is the scale parameter, x
+ is the random variate, p is the probability and
+ q = 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: pdf = exp((a-x)/b) * exp(-exp((a-x)/b)) /
+ b
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: p = exp(-exp((a-x)/b))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: q = -expm1(-exp((a-x)/b))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ Using the relation: a - log(-log(p)) * b
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: a - log(-log1p(-q)) * b
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ a + Euler-Mascheroni-constant
+ * b
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ standard deviation
+ 
+ </td>
+<td>
+ 
+ pi * b / sqrt(6)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ The same as the location parameter a.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ 12 * sqrt(6) * zeta(3) / pi3
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ 27 / 5
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ kurtosis - 3 or 12 / 5
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/fisher_f.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class RealType = double,
+ class Policy = policies::policy<> >
+class fisher_f_distribution;
+
+typedef fisher_f_distribution<> fisher_f;
+
+template <class RealType, class Policy>
+class fisher_f_distribution
+{
+public:
+ typedef RealType value_type;
+
+ // Construct:
+ fisher_f_distribution(const RealType& i, const RealType& j);
+
+ // Accessors:
+ RealType degrees_of_freedom1()const;
+ RealType degrees_of_freedom2()const;
+};
+
+}} //namespaces
+</pre>
+
+ The F distribution is a continuous distribution that arises when testing
+ whether two samples have the same variance. If χ2m and χ2n are independent
+ variates each distributed as Chi-Squared with m
+ and n degrees of freedom, then the test statistic:
+ 
+
+ Fn,m = (χ2n / n) / (χ2m / m)
+ 
+
+ Is distributed over the range [0, ∞] with an F distribution, and has the
+ PDF:
+ 
+
+ <img src="../../../../../equations/fisher_pdf.png">
+ 
+
+ The following graph illustrates how the PDF varies depending on the two
+ degrees of freedom parameters.
+ 
+
+ <img src="../../../../../graphs/fisher_f.png" alt="fisher_f">
+ 
+<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">
+fisher_f_distribution(const RealType& df1, const RealType& df2);
+</pre>
+
+ Constructs an F-distribution with numerator degrees of freedom df1
+ and denominator degrees of freedom df2.
+ 
+
+ Requires that df1 and df2 are
+ both greater than zero, otherwise domain_error
+ is called.
+ 
+<pre class="programlisting">
+RealType degrees_of_freedom1()const;
+</pre>
+
+ Returns the numerator degrees of freedom parameter of the distribution.
+ 
+<pre class="programlisting">
+RealType degrees_of_freedom2()const;
+</pre>
+
+ Returns the denominator degrees of freedom parameter of the distribution.
+ 
+<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>
+
+ 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.
+ 
+
+ The domain of the random variable is [0, +∞].
+ 
+<a name="math_toolkit.dist.dist_ref.dists.f_dist.examples"></a><h5>
+<a name="id593704"></a>
+ Examples
+ </h5>
+
+ Various worked examples
+ are available illustrating the use of the F Distribution.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.f_dist.accuracy"></a><h5>
+<a name="id593744"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.f_dist.implementation"></a><h5>
+<a name="id593793"></a>
+ Implementation
+ </h5>
+
+ In the following table v1 and v2
+ are the first and second degrees of freedom parameters of the distribution,
+ x is the random variate, p
+ is the probability, and q = 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ The usual form of the PDF is given by:
+ 
+ 
+ <img src="../../../../../equations/fisher_pdf.png">
+ 
+ 
+ However, that form is hard to evaluate directly without incurring
+ problems with either accuracy or numeric overflow.
+ 
+ 
+ Direct differentiation of the CDF expressed in terms of the incomplete
+ beta function
+ 
+ 
+ led to the following two formulas:
+ 
+ 
+ fv1,v2(x) = y * ibeta_derivative(v2
+ / 2, v1 / 2, v2 / (v2 + v1 * x))
+ 
+ 
+ with y = (v2 * v1) / ((v2 + v1 * x) * (v2 + v1 * x))
+ 
+ 
+ and
+ 
+ 
+ fv1,v2(x) = y * ibeta_derivative(v1
+ / 2, v2 / 2, v1 * x / (v2 + v1 * x))
+ 
+ 
+ with y = (z * v1 - x * v1 * v1) / z2
+ 
+ 
+ and z = v2 + v1 * x
+ 
+ 
+ The first of these is used for v1 * x > v2, otherwise the
+ second is used.
+ 
+ 
+ The aim is to keep the x argument to ibeta_derivative
+ away from 1 to avoid rounding error.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relations:
+ 
+ 
+ p = ibeta(v1
+ / 2, v2 / 2, v1 * x / (v2 + v1 * x))
+ 
+ 
+ and
+ 
+ 
+ p = ibetac(v2
+ / 2, v1 / 2, v2 / (v2 + v1 * x))
+ 
+ 
+ The first is used for v1 * x > v2, otherwise the second is
+ used.
+ 
+ 
+ The aim is to keep the x argument to ibeta
+ well away from 1 to avoid rounding error.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ Using the relations:
+ 
+ 
+ p = ibetac(v1
+ / 2, v2 / 2, v1 * x / (v2 + v1 * x))
+ 
+ 
+ and
+ 
+ 
+ p = ibeta(v2
+ / 2, v1 / 2, v2 / (v2 + v1 * x))
+ 
+ 
+ The first is used for v1 * x < v2, otherwise the second is
+ used.
+ 
+ 
+ The aim is to keep the x argument to ibeta
+ well away from 1 to avoid rounding error.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ Using the relation:
+ 
+ 
+ x = v2 * a / (v1 * b)
+ 
+ 
+ where:
+ 
+ 
+ a = ibeta_inv(v1
+ / 2, v2 / 2, p)
+ 
+ 
+ and
+ 
+ 
+ b = 1 - a
+ 
+ 
+ Quantities a and b
+ are both computed by ibeta_inv
+ without the subtraction implied above.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ 
+ from the complement
+ 
+ </td>
+<td>
+ 
+ Using the relation:
+ 
+ 
+ x = v2 * a / (v1 * b)
+ 
+ 
+ where
+ 
+ 
+ a = ibetac_inv(v1
+ / 2, v2 / 2, p)
+ 
+ 
+ and
+ 
+ 
+ b = 1 - a
+ 
+ 
+ Quantities a and b
+ are both computed by ibetac_inv
+ without the subtraction implied above.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ v2 / (v2 - 2)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ variance
+ 
+ </td>
+<td>
+ 
+ 2 * v22 * (v1 + v2 - 2) / (v1 * (v2 - 2) * (v2 - 2) * (v2 - 4))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ v2 * (v1 - 2) / (v1 * (v2 + 2))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ 2 * (v2 + 2 * v1 - 2) * sqrt((2 * v2 - 8) / (v1 * (v2 + v1 -
+ 2))) / (v2 - 6)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis and kurtosis excess
+ 
+ </td>
+<td>
+ 
+ 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>
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/gamma.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class RealType = double,
+ class Policy = policies::policy<> >
+class gamma_distribution
+{
+public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ gamma_distribution(RealType shape, RealType scale = 1)
+
+ RealType shape()const;
+ RealType scale()const;
+};
+
+}} // namespaces
+</pre>
+
+ 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.
+ 
+
+ 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 > 0, the Erlang distribution
+ is not separately implemented.
+ 
+<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">
+
+ To avoid potential confusion with the gamma functions, this distribution
+ does not provide the typedef:
+ 
+
+
+
+<pre class="programlisting">
+typedef gamma_distibution<double> gamma;</pre>
+
+ 
+
+ Instead if you want a double precision gamma distribution you can use
+ 
+
+
+
+<pre class="programlisting">
+boost::gamma_distribution<></pre>
+
+ 
+</td></tr>
+</table></div>
+
+ For shape parameter k and scale parameter θ it is
+ defined by the probability density function:
+ 
+
+ <img src="../../../../../equations/gamma_dist_ref1.png">
+ 
+
+ Sometimes an alternative formulation is used: given parameters α= k and
+ β= 1 / θ, then the distribution can be defined by the PDF:
+ 
+
+ <img src="../../../../../equations/gamma_dist_ref2.png">
+ 
+
+ In this form the inverse scale parameter is called a rate parameter.
+ 
+
+ Both forms are in common usage: this library uses the first definition
+ throughout. Therefore to construct a Gamma Distribution from a rate
+ parameter, you should pass the reciprocal of the rate as the
+ scale parameter.
+ 
+
+ The following two graphs illustrate how the PDF of the gamma distribution
+ varies as the parameters vary:
+ 
+
+ <img src="../../../../../graphs/gamma_dist1.png" alt="gamma_dist1">
+ 
+
+ <img src="../../../../../graphs/gamma_dist2.png" alt="gamma_dist2">
+ 
+
+ The Erlang Distribution is the same
+ as the Gamma, but with the shape parameter an integer. It is often expressed
+ using a rate rather than a scale
+ as the second parameter (remember that the rate is the reciprocal of
+ the scale).
+ 
+
+ 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.
+ 
+<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">
+gamma_distribution(RealType shape, RealType scale = 1);
+</pre>
+
+ Constructs a gamma distribution with shape shape
+ and scale scale.
+ 
+
+ Requires that the shape and scale parameters are greater than zero, otherwise
+ calls domain_error.
+ 
+<pre class="programlisting">
+RealType shape()const;
+</pre>
+
+ Returns the shape parameter of this distribution.
+ 
+<pre class="programlisting">
+RealType scale()const;
+</pre>
+
+ Returns the scale parameter of this distribution.
+ 
+<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>
+
+ 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.
+ 
+
+ The domain of the random variable is [0,+∞].
+ 
+<a name="math_toolkit.dist.dist_ref.dists.gamma_dist.accuracy"></a><h5>
+<a name="id595568"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.gamma_dist.implementation"></a><h5>
+<a name="id595637"></a>
+ Implementation
+ </h5>
+
+ In the following table k is the shape parameter
+ of the distribution, θ is it's scale parameter, x
+ is the random variate, p is the probability and
+ q = 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: pdf = gamma_p_derivative(k,
+ x / θ) / θ
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: p = gamma_p(k,
+ x / θ)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: q = gamma_q(k,
+ x / θ)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = θ* gamma_p_inv(k,
+ p)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = θ* gamma_q_inv(k,
+ p)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ kθ
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ variance
+ 
+ </td>
+<td>
+ 
+ kθ2
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ (k-1)θ for k>1 otherwise a domain_error
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ 2 / sqrt(k)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ 3 + 6 / k
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ 6 / k
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/lognormal.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class RealType = double,
+ class Policy = policies::policy<> >
+class lognormal_distribution;
+
+typedef lognormal_distribution<> lognormal;
+
+template <class RealType, class Policy>
+class lognormal_distribution
+{
+public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Construct:
+ lognormal_distribution(RealType location = 0, RealType scale = 1);
+ // Accessors:
+ RealType location()const;
+ RealType scale()const;
+};
+
+}} // namespaces
+</pre>
+
+ 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.
+ 
+
+ For location and scale parameters m and s
+ it is defined by the probability density function:
+ 
+
+ <img src="../../../../../equations/lognormal_ref.png">
+ 
+
+ The location and scale parameters are equivalent to the mean and standard
+ deviation of the logarithm of the random variable.
+ 
+
+ The following graph illustrates the effect of the location parameter
+ on the PDF, note that the range of the random variable remains [0,+∞]
+ irrespective of the value of the location parameter:
+ 
+
+ <img src="../../../../../graphs/lognormal1.png" alt="lognormal1">
+ 
+
+ The next graph illustrates the effect of the scale parameter on the PDF:
+ 
+
+ <img src="../../../../../graphs/lognormal2.png" alt="lognormal2">
+ 
+<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">
+lognormal_distribution(RealType location = 0, RealType scale = 1);
+</pre>
+
+ Constructs a lognormal distribution with location location
+ and scale scale.
+ 
+
+ The location parameter is the same as the mean of the logarithm of the
+ random variate.
+ 
+
+ The scale parameter is the same as the standard deviation of the logarithm
+ of the random variate.
+ 
+
+ Requires that the scale parameter is greater than zero, otherwise calls
+ domain_error.
+ 
+<pre class="programlisting">
+RealType location()const;
+</pre>
+
+ Returns the location parameter of this distribution.
+ 
+<pre class="programlisting">
+RealType scale()const;
+</pre>
+
+ Returns the scale parameter of this distribution.
+ 
+<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>
+
+ 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.
+ 
+
+ The domain of the random variable is [0,+∞].
+ 
+<a name="math_toolkit.dist.dist_ref.dists.lognormal_dist.accuracy"></a><h5>
+<a name="id597058"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.lognormal_dist.implementation"></a><h5>
+<a name="id597099"></a>
+ Implementation
+ </h5>
+
+ In the following table m is the location parameter
+ of the distribution, s is it's scale parameter,
+ x is the random variate, p
+ is the probability and q = 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: pdf = e-(ln(x) - m)2 / 2s2 / (x * s * sqrt(2pi))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: p = cdf(normal_distribtion<RealType>(m,
+ s), log(x))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: q = cdf(complement(normal_distribtion<RealType>(m,
+ s), log(x)))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = exp(quantile(normal_distribtion<RealType>(m,
+ s), p))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = exp(quantile(complement(normal_distribtion<RealType>(m,
+ s), q)))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ em + s2 / 2 
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ variance
+ 
+ </td>
+<td>
+ 
+ (es2 - 1) * e2m + s2 
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ em + s2 
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ sqrt(es2 - 1) * (2 + es2 )
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ e4s2 + 2e3s2 + 3e2s2 - 3
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ e4s2 + 2e3s2 + 3e2s2 - 6
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/negative_binomial.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class RealType = double,
+ class Policy = policies::policy<> >
+class negative_binomial_distribution;
+
+typedef negative_binomial_distribution<> negative_binomial;
+
+template <class RealType, class Policy>
+class negative_binomial_distribution
+{
+public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Constructor from successes and success_fraction:
+ negative_binomial_distribution(RealType r, RealType p);
+
+ // Parameter accessors:
+ RealType success_fraction() const;
+ RealType successes() const;
+
+ // Bounds on success fraction:
+ static RealType find_lower_bound_on_p(
+ RealType trials,
+ RealType successes,
+ RealType probability); // alpha
+ static RealType find_upper_bound_on_p(
+ RealType trials,
+ RealType successes,
+ RealType probability); // alpha
+
+ // Estimate min/max number of trials:
+ static RealType find_minimum_number_of_trials(
+ RealType k, // Number of failures.
+ RealType p, // Success fraction.
+ RealType probability); // Probability threshold alpha.
+ static RealType find_maximum_number_of_trials(
+ RealType k, // Number of failures.
+ RealType p, // Success fraction.
+ RealType probability); // Probability threshold alpha.
+};
+
+}} // namespaces
+</pre>
+
+ The class type <code class="computeroutput">negative_binomial_distribution</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".
+ 
+
+ 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.
+ 
+<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">
+ 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.
+ </td></tr>
+</table></div>
+
+ It has the PDF:
+ 
+
+ <img src="../../../../../equations/neg_binomial_ref.png">
+ 
+
+ The following graph illustrate how the PDF varies as the success fraction
+ p changes:
+ 
+
+ <img src="../../../../../graphs/neg_binomial_pdf1.png" alt="neg_binomial_pdf1">
+ 
+
+ Alternatively, this graph shows how the shape of the PDF varies as the
+ number of successes changes:
+ 
+
+ <img src="../../../../../graphs/neg_binomial_pdf2.png" alt="neg_binomial_pdf2">
+ 
+<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>
+
+ 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>.
+ 
+
+ This implementation uses real numbers for the computation throughout
+ (because it uses the real-valued incomplete
+ beta function family of functions). This real-valued version is also
+ called the Polya Distribution.
+ 
+
+ 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.
+ 
+
+ For large values of r (successes), the negative binomial distribution
+ converges to the Poisson distribution.
+ 
+
+ 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).
+ 
+
+ The Poisson distribution is a special case for large successes
+ 
+
+ poisson(λ) = lim r → ∞ negative_binomial(r, r / (λ + r)))
+ 
+
+ 
+<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">
+
+ The Negative Binomial distribution is a discrete distribution: internally
+ functions like the <code class="computeroutput">cdf</code>
+ and <code class="computeroutput">pdf</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.
+ 
+
+ The quantile function will by default return an integer result that
+ has been rounded outwards. That is to say lower
+ quantiles (where the probability is less than 0.5) are rounded downward,
+ and upper quantiles (where the probability is greater than 0.5) are
+ rounded upwards. This behaviour ensures that if an X% quantile is
+ requested, then at least the requested coverage
+ will be present in the central region, and no more than
+ the requested coverage will be present in the tails.
+ 
+
+ This behaviour can be changed so that the quantile functions are
+ rounded differently, or even return a real-valued result using 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.
+ 
+</td></tr>
+</table></div>
+
+ 
+<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">
+negative_binomial_distribution(RealType r, RealType p);
+</pre>
+
+ Constructor: r is the total number of successes,
+ p is the probability of success of a single trial.
+ 
+
+ Requires: <code class="computeroutput">r >
+ 0</code> and <code class="computeroutput">0
+ <= p
+ <= 1</code>.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.accessors"></a><h6>
+<a name="id598938"></a>
+ Accessors
+ </h6>
+<pre class="programlisting">
+RealType success_fraction() const; // successes / trials (0 <= p <= 1)
+</pre>
+
+ Returns the parameter p from which this distribution
+ was constructed.
+ 
+<pre class="programlisting">
+RealType successes() const; // required successes (r > 0)
+</pre>
+
+ Returns the parameter r from which this distribution
+ was constructed.
+ 
+<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">
+static RealType find_lower_bound_on_p(
+ RealType failures,
+ RealType successes,
+ RealType probability) // (0 <= alpha <= 1), 0.05 equivalent to 95% confidence.
+</pre>
+
+ Returns a lower bound on the success
+ fraction:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>failures</dt>
+<dd>
+ The total number of failures before the r th success.
+ </dd>
+<dt>successes</dt>
+<dd>
+ The number of successes required.
+ </dd>
+<dt>alpha</dt>
+<dd>
+ The largest acceptable probability that the true value of the success
+ fraction is less than the value
+ returned.
+ </dd>
+</dl>
+</div>
+
+ For example, if you observe k failures and r
+ successes from n = k + r trials the best estimate
+ for the success fraction is simply r/n, but if you
+ want to be 95% sure that the true value is greater
+ than some value, pmin, then:
+ 
+<pre class="programlisting">
+pmin = negative_binomial_distribution<RealType>::find_lower_bound_on_p(
+ failures, successes, 0.05);
+</pre>
+
+ <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>
+ 
+
+ 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 at least the coverage required,
+ and may produce pessimistic estimates for some combinations of failures
+ and successes. See:
+ 
+
+ <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>.
+ 
+<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">
+static RealType find_upper_bound_on_p(
+ RealType trials,
+ RealType successes,
+ RealType alpha); // (0 <= alpha <= 1), 0.05 equivalent to 95% confidence.
+</pre>
+
+ Returns an upper bound on the success
+ fraction:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>trials</dt>
+<dd>
+ The total number of trials conducted.
+ </dd>
+<dt>successes</dt>
+<dd>
+ The number of successes that occurred.
+ </dd>
+<dt>alpha</dt>
+<dd>
+ The largest acceptable probability that the true value of the success
+ fraction is greater than the value
+ returned.
+ </dd>
+</dl>
+</div>
+
+ For example, if you observe k successes from n
+ trials the best estimate for the success fraction is simply k/n,
+ but if you want to be 95% sure that the true value is less
+ than some value, pmax, then:
+ 
+<pre class="programlisting">
+pmax = negative_binomial_distribution<RealType>::find_upper_bound_on_p(
+ r, k, 0.05);
+</pre>
+
+ <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>
+ 
+
+ 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 at least the coverage required,
+ and may produce pessimistic estimates for some combinations of failures
+ and successes. See:
+ 
+
+ <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>.
+ 
+<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">
+static RealType find_minimum_number_of_trials(
+ RealType k, // number of failures.
+ RealType p, // success fraction.
+ RealType alpha); // probability threshold (0.05 equivalent to 95%).
+</pre>
+
+ This functions estimates the number of trials required to achieve a certain
+ probability that more than k failures will be observed.
+ 
+<div class="variablelist">
+
+<dl>
+<dt>k</dt>
+<dd>
+ The target number of failures to be observed.
+ </dd>
+<dt>p</dt>
+<dd>
+ The probability of success for each trial.
+ </dd>
+<dt>alpha</dt>
+<dd>
+ The maximum acceptable risk that only k failures or fewer will be
+ observed.
+ </dd>
+</dl>
+</div>
+
+ For example:
+ 
+<pre class="programlisting">
+negative_binomial_distribution<RealType>::find_minimum_number_of_trials(10, 0.5, 0.05);
+</pre>
+
+ Returns the smallest number of trials we must conduct to be 95% sure
+ of seeing 10 failures that occur with frequency one half.
+ 
+
+ <a href="../../stat_tut/weg/neg_binom_eg/neg_binom_size_eg.html" title="Estimating Sample Sizes for the Negative Binomial.">Worked
+ Example.</a>
+ 
+
+ 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 alpha
+ probability of observing k failures or fewer.
+ 
+<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">
+static RealType find_maximum_number_of_trials(
+ RealType k, // number of failures.
+ RealType p, // success fraction.
+ RealType alpha); // probability threshold (0.05 equivalent to 95%).
+</pre>
+
+ This functions estimates the maximum number of trials we can conduct
+ and achieve a certain probability that k failures
+ or fewer will be observed.
+ 
+<div class="variablelist">
+
+<dl>
+<dt>k</dt>
+<dd>
+ The maximum number of failures to be observed.
+ </dd>
+<dt>p</dt>
+<dd>
+ The probability of success for each trial.
+ </dd>
+<dt>alpha</dt>
+<dd>
+ The maximum acceptable risk that more than k
+ failures will be observed.
+ </dd>
+</dl>
+</div>
+
+ For example:
+ 
+<pre class="programlisting">
+negative_binomial_distribution<RealType>::find_maximum_number_of_trials(0, 1.0-1.0/1000000, 0.05);
+</pre>
+
+ 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.
+ 
+
+ 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 alpha
+ probability of observing more than k failures.
+ 
+<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>
+
+ 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.
+ 
+
+ However it's worth taking a moment to define what these actually mean
+ in the context of this distribution:
+ 
+<div class="table">
+<a name="id600589"></a>Table 8. Meaning of the non-member accessors.
+<div class="table-contents"><table class="table" summary="Meaning of the non-member accessors.">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Meaning
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Probability Density Function
+ 
+ </td>
+<td>
+ 
+ The probability of obtaining exactly k failures
+ from k+r trials with success fraction p. For example:
+ 
+ 
+
+
+<pre class="programlisting">
+pdf(negative_binomial(r, p), k)</pre>
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Cumulative Distribution Function
+ 
+ </td>
+<td>
+ 
+ The probability of obtaining k failures or
+ fewer from k+r trials with success fraction p and success
+ on the last trial. For example:
+ 
+ 
+
+
+<pre class="programlisting">
+cdf(negative_binomial(r, p), k)</pre>
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../nmp.html#math.dist.ccdf">Complement of the Cumulative Distribution
+ Function</a>
+ 
+ </td>
+<td>
+ 
+ The probability of obtaining more than k
+ failures from k+r trials with success fraction p and
+ success on the last trial. For example:
+ 
+ 
+
+
+<pre class="programlisting">
+cdf(complement(negative_binomial(r, p), k))</pre>
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Quantile
+ 
+ </td>
+<td>
+ 
+ The greatest 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:
+ 
+ 
+
+
+<pre class="programlisting">
+quantile(negative_binomial(r, p), P)</pre>
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../nmp.html#math.dist.quantile_c">Quantile from the complement
+ of the probability</a>
+ 
+ </td>
+<td>
+ 
+ The smallest 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:
+
+<pre class="programlisting">
+quantile(complement(negative_binomial(r, p), P))</pre>
+
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.accuracy"></a><h5>
+<a name="id601153"></a>
+ Accuracy
+ </h5>
+
+ This distribution is implemented using the incomplete beta functions
+ ibeta
+ and ibetac:
+ please refer to these functions for information on accuracy.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.implementation"></a><h5>
+<a name="id601202"></a>
+ Implementation
+ </h5>
+
+ In the following table, p is the probability that
+ any one trial will be successful (the success fraction), r
+ is the number of successes, k is the number of failures,
+ p is the probability and q = 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ pdf = exp(lgamma(r + k) - lgamma(r) - lgamma(k+1)) * pow(p, r)
+ * pow((1-p), k)
+ 
+ 
+ Implementation is in terms of ibeta_derivative:
+ 
+ 
+ (p/(r + k)) * ibeta_derivative(r, static_cast<RealType>(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.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relation:
+ 
+ 
+ cdf = Ip(r, k+1) = ibeta(r, k+1, p)
+ 
+ 
+ = ibeta(r, static_cast<RealType>(k+1), p)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ Using the relation:
+ 
+ 
+ 1 - cdf = Ip(k+1, r)
+ 
+ 
+ = ibetac(r, static_cast<RealType>(k+1), p)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ ibeta_invb(r, p, P) - 1
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ ibetac_invb(r, p, Q) -1)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">r(1-p)/p</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ variance
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">r (1-p)
+ / p
+ * p</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">floor((r-1) * (1 - p)/p)</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">(2
+ - p) /
+ sqrt(r *
+ (1
+ - p))</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">6 /
+ r +
+ (p
+ * p) /
+ r *
+ (1
+ - p
+ )</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ <code class="computeroutput">6 /
+ r +
+ (p
+ * p) /
+ r *
+ (1
+ - p
+ ) -3</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ parameter estimation member functions
+ 
+ </td>
+<td>
+ 
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">find_lower_bound_on_p</code>
+ 
+ </td>
+<td>
+ 
+ ibeta_inv(successes, failures + 1, alpha)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">find_upper_bound_on_p</code>
+ 
+ </td>
+<td>
+ 
+ ibetac_inv(successes, failures, alpha) plus see comments in code.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">find_minimum_number_of_trials</code>
+ 
+ </td>
+<td>
+ 
+ ibeta_inva(k + 1, p, alpha)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">find_maximum_number_of_trials</code>
+ 
+ </td>
+<td>
+ 
+ ibetac_inva(k + 1, p, alpha)
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+
+ Implementation notes:
+ 
+<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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/normal.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class RealType = double,
+ class Policy = policies::policy<> >
+class normal_distribution;
+
+typedef normal_distribution<> normal;
+
+template <class RealType, class Policy>
+class normal_distribution
+{
+public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Construct:
+ normal_distribution(RealType mean = 0, RealType sd = 1);
+ // Accessors:
+ RealType mean()const; // location.
+ RealType standard_deviation()const; // scale.
+ // Synonyms, provided to allow generic use of find_location and find_scale.
+ RealType location()const;
+ RealType scale()const;
+};
+
+}} // namespaces
+</pre>
+
+ 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 Standard
+ Normal Distribution.
+ 
+
+ Given mean μ and standard deviation σ it has the PDF:
+ 
+
+ <img src="../../../../../equations/normal_ref1.png">
+ 
+
+ The variation the PDF with its parameters is illustrated in the following
+ graph:
+ 
+
+ <img src="../../../../../graphs/normal.png" alt="normal">
+ 
+<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">
+normal_distribution(RealType mean = 0, RealType sd = 1);
+</pre>
+
+ Constructs a normal distribution with mean mean
+ and standard deviation sd.
+ 
+
+ Requires sd > 0, otherwise domain_error
+ is called.
+ 
+<pre class="programlisting">
+RealType mean()const;
+RealType location()const;
+</pre>
+
+ both return the mean of this distribution.
+ 
+<pre class="programlisting">
+RealType standard_deviation()const;
+RealType scale()const;
+</pre>
+
+ both return the standard deviation 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).
+ 
+<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>
+
+ 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.
+ 
+
+ The domain of the random variable is [-[max_value], +[min_value]]. However,
+ the pdf of +∞ and -∞ = 0 is also supported, and cdf at -∞ = 0, cdf at +∞ = 1,
+ and complement cdf -∞ = 1 and +∞ = 0, if RealType permits.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.normal_dist.accuracy"></a><h5>
+<a name="id603354"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.normal_dist.implementation"></a><h5>
+<a name="id603393"></a>
+ Implementation
+ </h5>
+
+ In the following table m is the mean of the distribution,
+ and s is its standard deviation.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: pdf = e-(x-m)2/(2s2) / (s * sqrt(2*pi))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: p = 0.5 * erfc(-(x-m)/(s*sqrt(2)))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: q = 0.5 * erfc((x-m)/(s*sqrt(2)))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = m - s * sqrt(2) * erfc_inv(2*p)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = m + s * sqrt(2) * erfc_inv(2*p)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean and standard deviation
+ 
+ </td>
+<td>
+ 
+ The same as <code class="computeroutput">dist.mean()</code> and <code class="computeroutput">dist.standard_deviation()</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ The same as the mean.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ 0
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ 3
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ 0
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/pareto.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class RealType = double,
+ class Policy = policies::policy<> >
+class pareto_distribution;
+
+typedef pareto_distribution<> pareto;
+
+template <class RealType, class Policy>
+class pareto_distribution
+{
+public:
+ typedef RealType value_type;
+ // Constructor:
+ pareto_distribution(RealType location = 1, RealType shape = 1)
+ // Accessors:
+ RealType location()const;
+ RealType shape()const;
+};
+
+}} // namespaces
+</pre>
+
+ 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>:
+ 
+
+ f(x; α, β) = αβα / xα+ 1
+ 
+
+ For shape parameter α > 0, and location parameter β > 0, and α > 0.
+ 
+
+ 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.
+ 
+
+ The following graph illustrates how the PDF varies with the shape parameter
+ α:
+ 
+
+ <a href="http://upload.wikimedia.org/wikipedia/commons/thumb/d/d9/Pareto_distributionPDF.png/325px-Pareto_distributionPDF.png" target="_top">Pareto
+ pdf</a>
+ 
+<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">
+pareto_distribution(RealType location = 1, RealType shape = 1);
+</pre>
+
+ Constructs a <a href="http://en.wikipedia.org/wiki/pareto_distribution" target="_top">pareto
+ distribution</a> with shape shape and scale
+ scale.
+ 
+
+ Requires that the shape and scale
+ parameters are both greater than zero, otherwise calls domain_error.
+ 
+<pre class="programlisting">
+RealType location()const;
+</pre>
+
+ Returns the location parameter of this distribution.
+ 
+<pre class="programlisting">
+RealType shape()const;
+</pre>
+
+ Returns the shape parameter of this distribution.
+ 
+<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>
+
+ 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.
+ 
+
+ The supported domain of the random variable is [location, ∞].
+ 
+<a name="math_toolkit.dist.dist_ref.dists.pareto.accuracy"></a><h5>
+<a name="id604783"></a>
+ Accuracy
+ </h5>
+
+ The pareto distribution is implemented in terms of the standard library
+ <code class="computeroutput">exp</code> functions plus expm1 and as such
+ should have very low error rates except when probability is very close
+ to unity.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.pareto.implementation"></a><h5>
+<a name="id604837"></a>
+ Implementation
+ </h5>
+
+ In the following table α is the shape parameter of the distribution, and
+ β is its location parameter, x is the random variate,
+ p is the probability and its complement q
+ = 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: pdf p = αβα/xα +1
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: cdf p = 1 - (β / x)α
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: q = 1 - p = -(β / x)α
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = α / (1 - p)1/β
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = α / (q)1/β
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ αβ / (β - 1)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ variance
+ 
+ </td>
+<td>
+ 
+ βα2 / (β - 1)2 (β - 2)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ α
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ Refer to <a href="http://mathworld.wolfram.com/paretoDistribution.html" target="_top">Weisstein,
+ Eric W. "Pareto Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ Refer to <a href="http://mathworld.wolfram.com/paretoDistribution.html" target="_top">Weisstein,
+ Eric W. "Pareto Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ Refer to <a href="http://mathworld.wolfram.com/paretoDistribution.html" target="_top">Weisstein,
+ Eric W. "pareto Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/poisson.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost { namespace math {
+
+template <class RealType = double,
+ class Policy = policies::policy<> >
+class poisson_distribution;
+
+typedef poisson_distribution<> poisson;
+
+template <class RealType, class Policy>
+class poisson_distribution
+{
+public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ poisson_distribution(RealType mean = 1); // Constructor.
+ RealType mean()const; // Accessor.
+}
+
+}} // namespaces boost::math
+</pre>
+
+ 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 λ
+(events/time), and are independent
+ of the time since the last event.
+ 
+
+ The distribution was discovered by Simé on-Denis Poisson (1781 to 1840).
+ 
+
+ It has the Probability Mass Function:
+ 
+
+ <img src="../../../../../equations/poisson_ref1.png">
+ 
+
+ for k events, with an expected number of events λ.
+ 
+
+ The following graph illustrates how the PDF varies with the parameter
+ λ:
+ 
+
+ <img src="../../../../../graphs/poisson.png" alt="poisson">
+ 
+
+ 
+<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">
+
+ The Poisson distribution is a discrete distribution: internally functions
+ like the <code class="computeroutput">cdf</code> and
+ <code class="computeroutput">pdf</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.
+ 
+
+ The quantile function will by default return an integer result that
+ has been rounded outwards. That is to say lower
+ quantiles (where the probability is less than 0.5) are rounded downward,
+ and upper quantiles (where the probability is greater than 0.5) are
+ rounded upwards. This behaviour ensures that if an X% quantile is
+ requested, then at least the requested coverage
+ will be present in the central region, and no more than
+ the requested coverage will be present in the tails.
+ 
+
+ This behaviour can be changed so that the quantile functions are
+ rounded differently, or even return a real-valued result using 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.
+ 
+</td></tr>
+</table></div>
+
+ 
+<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">
+poisson_distribution(RealType mean = 1);
+</pre>
+
+ Constructs a poisson distribution with mean mean.
+ 
+<pre class="programlisting">
+RealType mean()const;
+</pre>
+
+ Returns the mean of this distribution.
+ 
+<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>
+
+ 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.
+ 
+
+ The domain of the random variable is [0, ∞].
+ 
+<a name="math_toolkit.dist.dist_ref.dists.poisson_dist.accuracy"></a><h5>
+<a name="id606233"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.poisson_dist.implementation"></a><h5>
+<a name="id606282"></a>
+ Implementation
+ </h5>
+
+ In the following table λ is the mean of the distribution, k
+ is the random variable, p is the probability and
+ q = 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: pdf = e-λ λk / k!
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: p = Γ(k+1, λ) / k! = gamma_q(k+1,
+ λ)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: q = gamma_p(k+1,
+ λ)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ Using the relation: k = gamma_q_inva(λ,
+ p) - 1
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: k = gamma_p_inva(λ,
+ q) - 1
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ λ
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ floor (λ) or ⌊λ⌋
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ 1/√λ
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ 3 + 1/λ
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ 1/λ
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/rayleigh.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class RealType = double,
+ class Policy = policies::policy<> >
+class rayleigh_distribution;
+
+typedef rayleigh_distribution<> rayleigh;
+
+template <class RealType, class Policy>
+class rayleigh_distribution
+{
+public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Construct:
+ rayleigh_distribution(RealType sigma = 1)
+ // Accessors:
+ RealType sigma()const;
+};
+
+}} // namespaces
+</pre>
+
+ 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>:
+ 
+
+ f(x; sigma) = x * exp(-x2/2 σ2) / σ2
+ 
+
+ For sigma parameter σ > 0, and x > 0.
+ 
+
+ 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.
+ 
+
+ The following graph illustrates how the Probability density Function(pdf)
+ varies with the shape parameter σ:
+ 
+
+ <img src="../../../../../graphs/rayleigh_pdf.png" alt="rayleigh_pdf">
+ 
+
+ and the Cumulative Distribution Function (cdf)
+ 
+
+ <img src="../../../../../graphs/rayleigh_cdf.png" alt="rayleigh_cdf">
+ 
+<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>
+
+ The absolute value of two independent normal distributions X and Y, √ (X2 +
+ Y2) is a Rayleigh distribution.
+ 
+
+ The Chi,
+ Rice
+ and Weibull
+ distributions are generalizations of the <a href="http://en.wikipedia.org/wiki/Rayleigh_distribution" target="_top">Rayleigh
+ distribution</a>.
+ 
+<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">
+rayleigh_distribution(RealType sigma = 1);
+</pre>
+
+ Constructs a <a href="http://en.wikipedia.org/wiki/Rayleigh_distribution" target="_top">Rayleigh
+ distribution</a> with σ sigma.
+ 
+
+ Requires that the σ parameter is greater than zero, otherwise calls domain_error.
+ 
+<pre class="programlisting">
+RealType sigma()const;
+</pre>
+
+ Returns the sigma parameter of this distribution.
+ 
+<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>
+
+ 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.
+ 
+
+ The domain of the random variable is [0, max_value].
+ 
+<a name="math_toolkit.dist.dist_ref.dists.rayleigh.accuracy"></a><h5>
+<a name="id607589"></a>
+ Accuracy
+ </h5>
+
+ The Rayleigh distribution is implemented in terms of the standard library
+ <code class="computeroutput">sqrt</code> and <code class="computeroutput">exp</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.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.rayleigh.implementation"></a><h5>
+<a name="id607645"></a>
+ Implementation
+ </h5>
+
+ In the following table σ is the sigma parameter of the distribution, x
+ is the random variate, p is the probability and
+ q = 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: pdf = x * exp(-x2)/2 σ2
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: p = 1 - exp(-x2/2) σ2 = -expm1(-x2/2)
+ σ2
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: q = exp(-x2/ 2) * σ2
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = sqrt(-2 * σ 2) * log(1 - p)) = sqrt(-2
+ * σ 2) * log1p(-p))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = sqrt(-2 * σ 2) * log(q))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ σ * sqrt(π/2)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ variance
+ 
+ </td>
+<td>
+ 
+ σ2 * (4 - π/2)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ σ
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ Constant from <a href="http://mathworld.wolfram.com/RayleighDistribution.html" target="_top">Weisstein,
+ Eric W. "Weibull Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ Constant from <a href="http://mathworld.wolfram.com/RayleighDistribution.html" target="_top">Weisstein,
+ Eric W. "Weibull Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ Constant from <a href="http://mathworld.wolfram.com/RayleighDistribution.html" target="_top">Weisstein,
+ Eric W. "Weibull Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/students_t.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class RealType = double,
+ class Policy = policies::policy<> >
+class students_t_distribution;
+
+typedef students_t_distribution<> students_t;
+
+template <class RealType, class Policy>
+class students_t_distribution
+{
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ // Construct:
+ students_t_distribution(const RealType& v);
+
+ // Accessor:
+ RealType degrees_of_freedom()const;
+
+ // degrees of freedom estimation:
+ static RealType find_degrees_of_freedom(
+ RealType difference_from_mean,
+ RealType alpha,
+ RealType beta,
+ RealType sd,
+ RealType hint = 100);
+};
+
+}} // namespaces
+</pre>
+
+ 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
+ 
+
+ <img src="../../../../../equations/students_t_dist.png">
+ 
+
+ where M is the population mean,μ
+ is the sample mean, and s is the sample variance.
+ 
+
+ 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:
+ 
+
+ <img src="../../../../../equations/students_t_ref1.png">
+ 
+
+ The Student's t-distribution takes a single parameter: the number of
+ degrees of freedom of the sample. When the degrees of freedom is one
+ 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 ν:
+ 
+
+ <img src="../../../../../graphs/students_t.png" alt="students_t">
+ 
+<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">
+students_t_distribution(const RealType& v);
+</pre>
+
+ Constructs a Student's t-distribution with v degrees
+ of freedom.
+ 
+
+ Requires v > 0, otherwise calls domain_error.
+ Note that non-integral degrees of freedom are supported, and meaningful
+ under certain circumstances.
+ 
+<pre class="programlisting">
+RealType degrees_of_freedom()const;
+</pre>
+
+ Returns the number of degrees of freedom of this distribution.
+ 
+<pre class="programlisting">
+static RealType find_degrees_of_freedom(
+ RealType difference_from_mean,
+ RealType alpha,
+ RealType beta,
+ RealType sd,
+ RealType hint = 100);
+</pre>
+
+ 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 difference_from_mean.
+ 
+<div class="variablelist">
+
+<dl>
+<dt>difference_from_mean</dt>
+<dd>
+ The difference between the true mean and the sample mean that we
+ wish to show is significant.
+ </dd>
+<dt>alpha</dt>
+<dd>
+ The maximum acceptable probability of rejecting the null hypothesis
+ when it is in fact true.
+ </dd>
+<dt>beta</dt>
+<dd>
+ The maximum acceptable probability of failing to reject the null
+ hypothesis when it is in fact false.
+ </dd>
+<dt>sd</dt>
+<dd>
+ The sample standard deviation.
+ </dd>
+<dt>hint</dt>
+<dd>
+ 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.
+ </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">
+ Remember that for a two-sided test, you must divide alpha by two before
+ calling this function.
+ </td></tr>
+</table></div>
+
+ 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>.
+ 
+<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>
+
+ 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.
+ 
+
+ The domain of the random variable is [-∞, +∞].
+ 
+<a name="math_toolkit.dist.dist_ref.dists.students_t_dist.examples"></a><h5>
+<a name="id609384"></a>
+ Examples
+ </h5>
+
+ Various worked examples
+ are available illustrating the use of the Student's t distribution.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.students_t_dist.accuracy"></a><h5>
+<a name="id609423"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.students_t_dist.implementation"></a><h5>
+<a name="id609472"></a>
+ Implementation
+ </h5>
+
+ In the following table v is the degrees of freedom
+ of the distribution, t is the random variate, p
+ is the probability and q = 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: pdf = (v / (v + t2))(1+v)/2 / (sqrt(v) *
+ beta(v/2,
+ 0.5))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relations:
+ 
+ 
+ p = 1 - z iff t > 0
+ 
+ 
+ p = z otherwise
+ 
+ 
+ where z is given by:
+ 
+ 
+ ibeta(v
+ / 2, 0.5, v / (v + t2)) / 2 iff v < 2t2
+ 
+ 
+ ibetac(0.5,
+ v / 2, t2 / (v + t2) / 2 otherwise
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: q = cdf(-t)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ Using the relation: t = sign(p - 0.5) * sqrt(v * y / x)
+ 
+ 
+ where:
+ 
+ 
+ x = ibeta_inv(v
+ / 2, 0.5, 2 * min(p, q))
+ 
+ 
+ y = 1 - x
+ 
+ 
+ The quantities x and y
+ are both returned by ibeta_inv
+ without the subtraction implied above.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: t = -quantile(q)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ 0
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ variance
+ 
+ </td>
+<td>
+ 
+ v / (v - 2)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ 0
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ 0
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ 3 * (v - 2) / (v - 4)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ 6 / (df - 4)
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/triangular.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+ template <class RealType = double,
+ class Policy = policies::policy<> >
+ class triangular_distribution;
+
+ typedef triangular_distribution<> triangular;
+
+ template <class RealType, class Policy>
+ class triangular_distribution
+ {
+ public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+
+ triangular_distribution(RealType lower = -1, RealType mode = 0) RealType upper = 1); // Constructor.
+ : m_lower(lower), m_mode(mode), m_upper(upper) // Default is -1, 0, +1 triangular distribution.
+ // Accessor functions.
+ RealType lower()const;
+ RealType mode()const;
+ RealType upper()const;
+ }; // class triangular_distribution
+
+}} // namespaces
+</pre>
+
+ 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.
+ 
+
+ 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.
+ 
+
+ 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>:
+ 
+
+ f(x) =
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ 2(x-a)/(b-a) (c-a) for a <= x <= c
+ </li>
+<li>
+ 2(b-x)/(b-a)(b-c) for c < x <= b
+ </li>
+</ul></div>
+
+ Parameter a (lower) can be any finite value. Parameter b (upper) can
+ be any finite value > a (lower). Parameter c (mode) a <= c <=
+ b. This is the most probable value.
+ 
+
+ The random variate
+ x must also be finite, and is supported lower <= x <= upper.
+ 
+
+ 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.
+ 
+
+ 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.
+ 
+
+ 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:
+ 
+
+ <img src="../../../../../graphs/triangular_pdf.png" alt="triangular_pdf">
+ 
+
+ and cumulative distribution function
+ 
+
+ <img src="../../../../../graphs/triangular_cdf.png" alt="triangular_cdf">
+ 
+<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">
+triangular_distribution(RealType lower = 0, RealType mode = 0 RealType upper = 1);
+</pre>
+
+ Constructs a <a href="http://en.wikipedia.org/wiki/triangular_distribution" target="_top">triangular
+ distribution</a> with lower lower (a) and upper
+ upper (b).
+ 
+
+ Requires that the lower, mode
+ and upper parameters are all finite, otherwise calls
+ domain_error.
+ 
+<pre class="programlisting">
+RealType lower()const;
+</pre>
+
+ Returns the lower parameter of this distribution
+ (default -1).
+ 
+<pre class="programlisting">
+RealType mode()const;
+</pre>
+
+ Returns the mode parameter of this distribution
+ (default 0).
+ 
+<pre class="programlisting">
+RealType upper()const;
+</pre>
+
+ Returns the upper parameter of this distribution
+ (default+1).
+ 
+<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>
+
+ 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.
+ 
+
+ The domain of the random variable is \lowerto \upper, and the supported
+ range is lower <= x <= upper.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.triangular_dist.accuracy"></a><h5>
+<a name="id611271"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.triangular_dist.implementation"></a><h5>
+<a name="id611303"></a>
+ Implementation
+ </h5>
+
+ In the following table, a is the lower parameter
+ of the distribution, c is the mode parameter, b
+ is the upper parameter, x is
+ the random variate, p is the probability and q
+ = 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: pdf = 0 for x < mode, 2(x-a)/(b-a)(c-a)
+ else 2*(b-x)/((b-a)(b-c))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: cdf = 0 for x < mode (x-a)2/((b-a)(c-a))
+ else 1 - (b-x)2/((b-a)(b-c))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: q = 1 - p
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ let p0 = (c-a)/(b-a) the point of inflection on the cdf, then
+ given probability p and q = 1-p:
+ 
+ 
+ x = sqrt((b-a)(c-a)p) + a ; for p < p0
+ 
+ 
+ x = c ; for p == p0
+ 
+ 
+ x = b - sqrt((b-a)(b-c)q) ; for p > p0
+ 
+ 
+ (See /boost/math/distributions/triangular.hpp
+ for details.)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ As quantile (See /boost/math/distributions/triangular.hpp
+ for details.)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ (a + b + 3) / 3
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ variance
+ 
+ </td>
+<td>
+ 
+ (a2+b2+c2 - ab - ac - bc)/18
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ c
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ (See /boost/math/distributions/triangular.hpp
+ for details).
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ 12/5
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ -3/5
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+
+ 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>
+ 
+<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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/uniform.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+ template <class RealType = double,
+ class Policy = policies::policy<> >
+ class uniform_distribution;
+
+ typedef uniform_distribution<> uniform;
+
+ template <class RealType, class Policy>
+ class uniform_distribution
+ {
+ public:
+ typedef RealType value_type;
+
+ uniform_distribution(RealType lower = 0, RealType upper = 1); // Constructor.
+ : m_lower(lower), m_upper(upper) // Default is standard uniform distribution.
+ // Accessor functions.
+ RealType lower()const;
+ RealType upper()const;
+ }; // class uniform_distribution
+
+}} // namespaces
+</pre>
+
+ The uniform distribution, also known as a rectangular distribution, is
+ a probability distribution that has constant probability.
+ 
+
+ 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>:
+ 
+
+ f(x) =
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ 1 / (upper - lower) for lower < x < upper
+ </li>
+<li>
+ zero for x < lower or x > upper
+ </li>
+</ul></div>
+
+ and in this implementation:
+ 
+<div class="itemizedlist"><ul type="disc"><li>
+ 1 / (upper - lower) for x = lower or x = upper
+ </li></ul></div>
+
+ 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.
+ 
+
+ There is also a discrete uniform distribution.
+ 
+
+ Parameters lower and upper can be any finite value.
+ 
+
+ The random variate
+ x must also be finite, and is supported lower <= x <= upper.
+ 
+
+ 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>.
+ 
+
+ 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:
+ 
+
+ <img src="../../../../../graphs/uniform_pdf.png" alt="uniform_pdf">
+ 
+
+ Likewise for the CDF:
+ 
+
+ <img src="../../../../../graphs/uniform_cdf.png" alt="uniform_cdf">
+ 
+<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">
+uniform_distribution(RealType lower = 0, RealType upper = 1);
+</pre>
+
+ Constructs a <a href="http://en.wikipedia.org/wiki/uniform_distribution" target="_top">uniform
+ distribution</a> with lower lower (a) and upper
+ upper (b).
+ 
+
+ Requires that the lower and upper
+ parameters are both finite; otherwise if infinity or NaN then calls
+ domain_error.
+ 
+<pre class="programlisting">
+RealType lower()const;
+</pre>
+
+ Returns the lower parameter of this distribution.
+ 
+<pre class="programlisting">
+RealType upper()const;
+</pre>
+
+ Returns the upper parameter of this distribution.
+ 
+<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>
+
+ 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.
+ 
+
+ The domain of the random variable is any finite value, but the supported
+ range is only lower <= x <= upper.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.uniform_dist.accuracy"></a><h5>
+<a name="id614606"></a>
+ Accuracy
+ </h5>
+
+ The uniform distribution is implemented with simple arithmetic operators
+ and so should have errors within an epsilon or two.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.uniform_dist.implementation"></a><h5>
+<a name="id614637"></a>
+ Implementation
+ </h5>
+
+ In the following table a is the lower parameter
+ of the distribution, b is the upper parameter,
+ x is the random variate, p
+ is the probability and q = 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: pdf = 0 for x < a, 1 / (b - a) for a <=
+ x <= b, 0 for x > b
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: cdf = 0 for x < a, (x - a) / (b - a) for
+ a <= x <= b, 1 for x > b
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: q = 1 - p, (b - x) / (b - a)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = p * (b - a) + a;
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ x = -q * (b - a) + b
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ (a + b) / 2
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ variance
+ 
+ </td>
+<td>
+ 
+ (b - a) 2 / 12
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ any value in [a, b] but a is chosen. (Would NaN be better?)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ 0
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ -6/5 = -1.2 exactly. (kurtosis - 3)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ 9/5
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/weibull.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class RealType = double,
+ class Policy = policies::policy<> >
+class weibull_distribution;
+
+typedef weibull_distribution<> weibull;
+
+template <class RealType, class Policy>
+class weibull_distribution
+{
+public:
+ typedef RealType value_type;
+ typedef Policy policy_type;
+ // Construct:
+ weibull_distribution(RealType shape, RealType scale = 1)
+ // Accessors:
+ RealType shape()const;
+ RealType scale()const;
+};
+
+}} // namespaces
+</pre>
+
+ 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>:
+ 
+
+ f(x; α, β) = (α/β) * (x / β)α - 1 * e-(x/β)α
+ 
+
+ For shape parameter α > 0, and scale parameter β > 0, and x > 0.
+ 
+
+ 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:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ constant over time, then α = 1, suggests that items are failing from
+ random events.
+ </li>
+<li>
+ decreases over time, then α < 1, suggesting "infant mortality".
+ </li>
+<li>
+ increases over time, then α > 1, suggesting "wear out" -
+ more likely to fail as time goes by.
+ </li>
+</ul></div>
+
+ The following graph illustrates how the PDF varies with the shape parameter
+ α:
+ 
+
+ <img src="../../../../../graphs/weibull.png" alt="weibull">
+ 
+
+ While this graph illustrates how the PDF varies with the scale parameter
+ β:
+ 
+
+ <img src="../../../../../graphs/weibull2.png" alt="weibull2">
+ 
+<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>
+
+ When α = 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 α = 1, the Weibull distribution reduces to the
+ <a href="http://en.wikipedia.org/wiki/Exponential_distribution" target="_top">exponential
+ distribution</a>.
+ 
+<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">
+weibull_distribution(RealType shape, RealType scale = 1);
+</pre>
+
+ Constructs a <a href="http://en.wikipedia.org/wiki/Weibull_distribution" target="_top">Weibull
+ distribution</a> with shape shape and scale
+ scale.
+ 
+
+ Requires that the shape and scale
+ parameters are both greater than zero, otherwise calls domain_error.
+ 
+<pre class="programlisting">
+RealType shape()const;
+</pre>
+
+ Returns the shape parameter of this distribution.
+ 
+<pre class="programlisting">
+RealType scale()const;
+</pre>
+
+ Returns the scale parameter of this distribution.
+ 
+<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>
+
+ 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.
+ 
+
+ The domain of the random variable is [0, ∞].
+ 
+<a name="math_toolkit.dist.dist_ref.dists.weibull.accuracy"></a><h5>
+<a name="id612905"></a>
+ Accuracy
+ </h5>
+
+ The Weibull distribution is implemented in terms of the standard library
+ <code class="computeroutput">log</code> and <code class="computeroutput">exp</code> functions plus expm1
+ and log1p and
+ as such should have very low error rates.
+ 
+<a name="math_toolkit.dist.dist_ref.dists.weibull.implementation"></a><h5>
+<a name="id612977"></a>
+ Implementation
+ </h5>
+
+ In the following table α is the shape parameter of the distribution, β is
+ it's scale parameter, x is the random variate,
+ p is the probability and q = 1-p.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Implementation Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ pdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: pdf = αβ-α xα - 1 e-(x/beta)alpha
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf
+ 
+ </td>
+<td>
+ 
+ Using the relation: p = -expm1(-(x/β)α)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: q = e-(x/β)α
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = β * (-log1p(-p))1/α
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile from the complement
+ 
+ </td>
+<td>
+ 
+ Using the relation: x = β * (-log(q))1/α
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean
+ 
+ </td>
+<td>
+ 
+ β * Γ(1 + 1/α)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ variance
+ 
+ </td>
+<td>
+ 
+ β2(Γ(1 + 2/α) - Γ2(1 + 1/α))
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode
+ 
+ </td>
+<td>
+ 
+ β((α - 1) / α)1/α
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness
+ 
+ </td>
+<td>
+ 
+ Refer to <a href="http://mathworld.wolfram.com/WeibullDistribution.html" target="_top">Weisstein,
+ Eric W. "Weibull Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis
+ 
+ </td>
+<td>
+ 
+ Refer to <a href="http://mathworld.wolfram.com/WeibullDistribution.html" target="_top">Weisstein,
+ Eric W. "Weibull Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis excess
+ 
+ </td>
+<td>
+ 
+ Refer to <a href="http://mathworld.wolfram.com/WeibullDistribution.html" target="_top">Weisstein,
+ Eric W. "Weibull Distribution." From MathWorld--A Wolfram
+ Web Resource.</a>
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+<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">
+template <class RealType, class Policy>
+RealType cdf(const Distribution-Type<RealType, Policy>& dist, const RealType& x);
+</pre>
+
+ 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>.
+ 
+
+ This function may return a domain_error
+ if the random variable is outside the defined range for the distribution.
+ 
+
+ For example the following graph shows the cdf for the normal distribution:
+ 
+
+ <img src="../../../../graphs/cdf.png" alt="cdf">
+ 
+<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">
+template <class Distribution, class RealType>
+RealType cdf(const Unspecified-Complement-Type<Distribution, RealType>& comp);
+</pre>
+
+ 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.
+ 
+
+ This is also known as the survival function.
+ 
+
+ This function may return a domain_error
+ if the random variable is outside the defined range for the distribution.
+ 
+
+ In this library, it is obtained by wrapping the arguments to the <code class="computeroutput">cdf</code> function in a call to <code class="computeroutput">complement</code>, for example:
+ 
+<pre class="programlisting">
+// standard normal distribution object:
+boost::math::normal norm;
+// print survival function for x=2.0:
+std::cout << cdf(complement(norm, 2.0)) << std::endl;
+</pre>
+
+ For example the following graph shows the __complement of the cdf for the
+ normal distribution:
+ 
+
+ <img src="../../../../graphs/survival.png" alt="survival">
+ 
+
+ See why complements? for why the
+ complement is useful and when it should be used.
+ 
+<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">
+template <class RealType, class Policy>
+RealType hazard(const Distribution-Type<RealType, Policy>& dist, const RealType& x);
+</pre>
+
+ Returns the Hazard Function of
+ x and distibution dist.
+ 
+
+ This function may return a domain_error
+ if the random variable is outside the defined range for the distribution.
+ 
+
+ <img src="../../../../equations/hazard.png">
+ 
+<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">
+ Some authors refer to this as the conditional failure density function
+ rather than the hazard function.
+ </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">
+template <class RealType, class Policy>
+RealType chf(const Distribution-Type<RealType, Policy>& dist, const RealType& x);
+</pre>
+
+ Returns the Cumulative Hazard Function
+ of x and distibution dist.
+ 
+
+ This function may return a domain_error
+ if the random variable is outside the defined range for the distribution.
+ 
+
+ <img src="../../../../equations/chf.png">
+ 
+<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">
+ Some authors refer to this as simply the "Hazard Function".
+ </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">
+template<class RealType, class Policy>
+RealType mean(const Distribution-Type<RealType, Policy>& dist);
+</pre>
+
+ Returns the mean of the distribution dist.
+ 
+
+ This function may return a domain_error
+ if the distribution does not have a defined mean (for example the Cauchy
+ distribution).
+ 
+<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">
+template<class RealType, class Policy>
+RealType median(const Distribution-Type<RealType, Policy>& dist);
+</pre>
+
+ Returns the median of the distribution dist.
+ 
+<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">
+template<class RealType, Policy>
+RealType mode(const Distribution-Type<RealType, Policy>& dist);
+</pre>
+
+ Returns the mode of the distribution dist.
+ 
+
+ This function may return a domain_error
+ if the distribution does not have a defined mode.
+ 
+<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">
+template <class RealType, class Policy>
+RealType pdf(const Distribution-Type<RealType, Policy>& dist, const RealType& x);
+</pre>
+
+ 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.
+ 
+
+ For a discrete distribution, the pdf is the probability that the variate
+ takes the value x.
+ 
+
+ This function may return a domain_error
+ if the random variable is outside the defined range for the distribution.
+ 
+
+ For example for a standard normal distribution the pdf looks like this:
+ 
+
+ <img src="../../../../graphs/pdf.png" alt="pdf">
+ 
+<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">
+template<class RealType, class Policy>
+std::pair<RealType, RealType> range(const Distribution-Type<RealType, Policy>& dist);
+</pre>
+
+ Returns the valid range of the random variable over distribution dist.
+ 
+<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">
+template <class RealType, class Policy>
+RealType quantile(const Distribution-Type<RealType, Policy>& dist, const RealType& p);
+</pre>
+
+ 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 x
+ such that <code class="computeroutput">cdf(dist, x) ==
+ p</code>.
+ 
+
+ This is also known as the percent point function,
+ or a percentile, it is also the same as calculating
+ the lower critical value of a distribution.
+ 
+
+ 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.
+ 
+
+ The following graph shows the quantile function for a standard normal distribution:
+ 
+
+ <img src="../../../../graphs/quantile.png" alt="quantile">
+ 
+<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>
+
+ complements
+ 
+<pre class="programlisting">
+template <class Distribution, class RealType>
+RealType quantile(const Unspecified-Complement-Type<Distribution, RealType>& comp);
+</pre>
+
+ 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 complement.
+ For example:
+ 
+<pre class="programlisting">
+// define a standard normal distribution:
+boost::math::normal norm;
+// print the value of x for which the complement
+// of the probability is 0.05:
+std::cout << quantile(complement(norm, 0.05)) << std::endl;
+</pre>
+
+ The function computes a value x such that <code class="computeroutput">cdf(complement(dist, x)) == q</code>
+ where q is complement of the probability.
+ 
+
+ Why complements?
+ 
+
+ This function is also called the inverse survival function, and is the
+ same as calculating the upper critical value of a
+ distribution.
+ 
+
+ 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.
+ 
+
+ The following graph show the inverse survival function for the normal distribution:
+ 
+
+ <img src="../../../../graphs/survival_inv.png" alt="survival_inv">
+ 
+<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">
+template <class RealType, class Policy>
+RealType standard_deviation(const Distribution-Type<RealType, Policy>& dist);
+</pre>
+
+ Returns the standard deviation of distribution dist.
+ 
+
+ This function may return a domain_error
+ if the distribution does not have a defined standard deviation.
+ 
+<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">
+template<class RealType, class Policy>
+std::pair<RealType, RealType> support(const Distribution-Type<RealType, Policy>& dist);
+</pre>
+
+ Returns the supported range of random variable over the distribution dist.
+ 
+
+ 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.
+ 
+<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">
+template <class RealType, class Policy>
+RealType variance(const Distribution-Type<RealType, Policy>& dist);
+</pre>
+
+ Returns the variance of the distribution dist.
+ 
+
+ This function may return a domain_error
+ if the distribution does not have a defined variance.
+ 
+<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">
+template <class RealType, class Policy>
+RealType skewness(const Distribution-Type<RealType, Policy>& dist);
+</pre>
+
+ Returns the skewness of the distribution dist.
+ 
+
+ This function may return a domain_error
+ if the distribution does not have a defined skewness.
+ 
+<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">
+template <class RealType, class Policy>
+RealType kurtosis(const Distribution-Type<RealType, Policy>& dist);
+</pre>
+
+ Returns the 'proper' kurtosis (normalized fourth moment) of the distribution
+ dist.
+ 
+
+ kertosis = β2= μ4 / μ22
+ 
+
+ Where μi is the i'th central moment of the distribution, and in particular
+ μ2 is the variance of the distribution.
+ 
+
+ The kurtosis is a measure of the "peakedness" of a distribution.
+ 
+
+ 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.
+ 
+<pre class="programlisting">
+kurtosis_excess = 'proper' kurtosis - 3
+</pre>
+
+ This subtraction of 3 is convenient so that the kurtosis excess
+ of a normal distribution is zero.
+ 
+
+ This function may return a domain_error
+ if the distribution does not have a defined kurtosis.
+ 
+
+ 'Proper' kurtosis can have a value from zero to + infinity.
+ 
+<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">
+template <class RealType, Policy>
+RealType kurtosis_excess(const Distribution-Type<RealType, Policy>& dist);
+</pre>
+
+ Returns the kurtosis excess of the distribution dist.
+ 
+
+ kurtosis excess = γ2= μ4 / μ22- 3 = kurtosis - 3
+ 
+
+ Where μi is the i'th central moment of the distribution, and in particular
+ μ2 is the variance of the distribution.
+ 
+
+ 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.
+ 
+
+ This function may return a domain_error
+ if the distribution does not have a defined kurtosis excess.
+ 
+
+ Kurtosis excess can have a value from -2 to + infinity.
+ 
+<pre class="programlisting">
+kurtosis = kurtosis_excess +3;
+</pre>
+
+ The kurtosis excess of a normal distribution is zero.
+ 
+<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>
+
+ 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.
+ 
+<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>
+
+ The percent point function, also known as the percentile, is the same as
+ the Quantile.
+ 
+<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>
+
+ The inverse of the cumulative distribution function, is the same as the
+ Quantile.
+ 
+<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>
+
+ The inverse of the survival function, is the same as computing the quantile from the complement of the probability.
+ 
+<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>
+
+ The Probability Mass Function is the same as the <a href="nmp.html#math.dist.pdf">Probability
+ Density Function</a>.
+ 
+
+ The term Mass Function is usually applied to discrete distributions, while
+ the term Probability Density Function
+ applies to continuous distributions.
+ 
+<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>
+
+ 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.
+ 
+<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>
+
+ 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>.
+ 
+<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>
+
+ Refer to the <a href="nmp.html#math.dist.ccdf">Complement of the Cumulative
+ Distribution Function</a>.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ The obvious way to handle this is via an adapter template:
+ 
+<pre class="programlisting">
+template <class Dist>
+class scaled_distribution
+{
+ scaled_distribution(
+ const Dist dist,
+ typename Dist::value_type location,
+ typename Dist::value_type scale = 0);
+};
+</pre>
+
+ Which would then have its own set of overloads for the non-member accessor
+ functions.
+ 
+<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>
+
+ 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:
+ 
+<pre class="programlisting">
+template <class RealType>
+class any_distribution
+{
+public:
+ template <class Distribution>
+ any_distribution(const Distribution& d);
+};
+
+// Get the cdf of the underlying distribution:
+template <class RealType>
+RealType cdf(const any_distribution<RealType>& d, RealType x);
+// etc....
+</pre>
+
+ 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.
+ 
+<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>
+
+ 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:
+ 
+<pre class="programlisting">
+template <class InputIterator>
+typename std::iterator_traits<InputIterator>::value_type
+ test_equal_mean(
+ InputIterator a,
+ InputIterator b,
+ typename std::iterator_traits<InputIterator>::value_type expected_mean);
+</pre>
+
+ Returns the probability that the data in the sequence [a,b) has the mean
+ expected_mean.
+ 
+<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>
+
+ <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:
+ 
+<pre class="programlisting">
+// Define an accumulator, all required statistics to calculate the test
+// are calculated automatically:
+accumulator_set<double, features<tag::test_expected_mean> > acc(expected_mean=4);
+// Pass our data to the accumulator:
+acc = std::for_each(mydata.begin(), mydata.end(), acc);
+// Extract the result:
+double p = probability(acc);
+</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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> Overview</dt>
+<dt> Worked Examples</dt>
+<dd><dl>
+<dt><a href="stat_tut/weg/dist_construct_eg.html">
+ Distribution Construction Example</a></dt>
+<dt><a href="stat_tut/weg/st_eg.html"> Student's
+ t Distribution Examples</a></dt>
+<dd><dl>
+<dt><a href="stat_tut/weg/st_eg/tut_mean_intervals.html">
+ Calculating confidence intervals on the mean with the Students-t distribution</a></dt>
+<dt><a href="stat_tut/weg/st_eg/tut_mean_test.html">
+ Testing a sample mean for difference from a "true" mean</a></dt>
+<dt><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></dt>
+<dt><a href="stat_tut/weg/st_eg/two_sample_students_t.html">
+ Comparing the means of two samples with the Students-t test</a></dt>
+<dt><a href="stat_tut/weg/st_eg/paired_st.html">
+ Comparing two paired samples with the Student's t distribution</a></dt>
+</dl></dd>
+<dt><a href="stat_tut/weg/cs_eg.html"> Chi Squared
+ Distribution Examples</a></dt>
+<dd><dl>
+<dt><a href="stat_tut/weg/cs_eg/chi_sq_intervals.html">
+ Confidence Intervals on the Standard Deviation</a></dt>
+<dt><a href="stat_tut/weg/cs_eg/chi_sq_test.html">
+ Chi-Square Test for the Standard Deviation</a></dt>
+<dt><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></dt>
+</dl></dd>
+<dt><a href="stat_tut/weg/f_eg.html"> F Distribution
+ Examples</a></dt>
+<dt><a href="stat_tut/weg/binom_eg.html"> Binomial
+ Distribution Examples</a></dt>
+<dd><dl>
+<dt><a href="stat_tut/weg/binom_eg/binomial_coinflip_example.html">
+ Binomial Coin-Flipping Example</a></dt>
+<dt><a href="stat_tut/weg/binom_eg/binomial_quiz_example.html">
+ Binomial Quiz Example</a></dt>
+<dt><a href="stat_tut/weg/binom_eg/binom_conf.html">
+ Calculating Confidence Limits on the Frequency of Occurrence for a Binomial
+ Distribution</a></dt>
+<dt><a href="stat_tut/weg/binom_eg/binom_size_eg.html">
+ Estimating Sample Sizes for a Binomial Distribution.</a></dt>
+</dl></dd>
+<dt><a href="stat_tut/weg/neg_binom_eg.html"> Negative
+ Binomial Distribution Examples</a></dt>
+<dd><dl>
+<dt><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></dt>
+<dt><a href="stat_tut/weg/neg_binom_eg/neg_binom_size_eg.html">
+ Estimating Sample Sizes for the Negative Binomial.</a></dt>
+<dt><a href="stat_tut/weg/neg_binom_eg/negative_binomial_example1.html">
+ Negative Binomial Sales Quota Example.</a></dt>
+<dt><a href="stat_tut/weg/neg_binom_eg/negative_binomial_example2.html">
+ Negative Binomial Table Printing Example.</a></dt>
+</dl></dd>
+<dt><a href="stat_tut/weg/normal_example.html"> Normal
+ Distribution Examples</a></dt>
+<dd><dl><dt><a href="stat_tut/weg/normal_example/normal_misc.html">
+ Some Miscellaneous Examples of the Normal (Gaussian) Distribution</a></dt></dl></dd>
+<dt><a href="stat_tut/weg/error_eg.html"> Error Handling
+ Example</a></dt>
+<dt><a href="stat_tut/weg/find_eg.html"> Find Location
+ and Scale Examples</a></dt>
+<dd><dl>
+<dt><a href="stat_tut/weg/find_eg/find_location_eg.html">
+ Find Location (Mean) Example</a></dt>
+<dt><a href="stat_tut/weg/find_eg/find_scale_eg.html">
+ Find Scale (Standard Deviation) Example</a></dt>
+<dt><a href="stat_tut/weg/find_eg/find_mean_and_sd_eg.html">
+ Find mean and standard deviation example</a></dt>
+</dl></dd>
+<dt><a href="stat_tut/weg/nag_library.html"> Comparison
+ with C, R, FORTRAN-style Free Functions</a></dt>
+</dl></dd>
+<dt><a href="stat_tut/variates.html"> Random Variates
+ and Distribution Parameters</a></dt>
+<dt><a href="stat_tut/dist_params.html"> Discrete Probability
+ Distributions</a></dt>
+</dl></div>
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ Note that the <a href="http://en.wikipedia.org/wiki/Discrete_probability_distribution" target="_top">discrete
+ distributions</a>, including the binomial, negative binomial, Poisson
+ & 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.
+ 
+
+ 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.
+ 
+
+ 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.
+ 
+
+ 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.
+ 
+<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">
+
+ The quantile function of a discrete distribution will by default return
+ an integer result that has been rounded outwards.
+ That is to say lower quantiles (where the probability is less than 0.5)
+ are rounded downward, and upper quantiles (where the probability is greater
+ than 0.5) are rounded upwards. This behaviour ensures that if an X% quantile
+ is requested, then at least the requested coverage
+ will be present in the central region, and no more than
+ the requested coverage will be present in the tails.
+ 
+
+ This behaviour can be changed so that the quantile functions are rounded
+ differently, or even return a real-valued result using 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.
+ 
+</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ All the code in this library is inside namespace boost::math.
+ 
+
+ In order to use a distribution my_distribution you
+ will need to include either the header <boost/math/distributions/my_distribution.hpp>
+ or the "include everything" header: <boost/math/distributions.hpp>.
+ 
+
+ For example, to use the Students-t distribution include either <boost/math/distributions/students_t.hpp>
+ or <boost/math/distributions.hpp>
+ 
+<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>
+
+ Each kind of distribution in this library is a class type.
+ 
+
+ 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.
+ 
+<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">
+ 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>
+ </td></tr>
+</table></div>
+
+ Making distributions class types does two things:
+ 
+<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 degrees of freedom
+ parameter that controls the shape of the distribution. This degrees
+ of freedom parameter has to be provided to the Students-t
+ object when it is constructed.
+ </li>
+</ul></div>
+
+ Although the distribution classes in this library are templates, there
+ are typedefs on type double 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">RealType =
+ double</code> - is nearly as convenient).
+ Probably 95% of uses are covered by these typedefs:
+ 
+<pre class="programlisting">
+using namespace boost::math;
+
+// Construct a students_t distribution with 4 degrees of freedom:
+students_t d1(4);
+
+// Construct a double-precision beta distribution
+// with parameters a = 10, b = 20
+beta_distribution<> d2(10, 20); // Note: _distribution<> suffix !
+</pre>
+
+ If you need to use the distributions with a type other than <code class="computeroutput">double</code>, then you can instantiate the template
+ directly: the names of the templates are the same as the <code class="computeroutput">double</code> typedef but with <code class="computeroutput">_distribution</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>:
+ 
+<pre class="programlisting">
+// Construct a students_t distribution, of float type,
+// with 4 degrees of freedom:
+students_t_distribution<float> d3(4);
+
+// Construct a binomial distribution, of long double type,
+// with probability of success 0.3
+// and 20 trials in total:
+binomial_distribution<long double> d4(20, 0.3);
+</pre>
+
+ The parameters passed to the distributions can be accessed via getter member
+ functions:
+ 
+<pre class="programlisting">
+d1.degrees_of_freedom(); // returns 4.0
+</pre>
+
+ This is all well and good, but not very useful so far. What we often want
+ is to be able to calculate the cumulative distribution functions
+ and quantiles etc for these distributions.
+ 
+<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>
+
+ Want to calculate the PDF (Probability Density Function) of a distribution?
+ No problem, just use:
+ 
+<pre class="programlisting">
+pdf(my_dist, x); // Returns PDF (density) at point x of distribution my_dist.
+</pre>
+
+ Or how about the CDF (Cumulative Distribution Function):
+ 
+<pre class="programlisting">
+cdf(my_dist, x); // Returns CDF (integral from -infinity to point x)
+ // of distribution my_dist.
+</pre>
+
+ And quantiles are just the same:
+ 
+<pre class="programlisting">
+quantile(my_dist, p); // Returns the value of the random variable x
+ // such that cdf(my_dist, x) == p.
+</pre>
+
+ 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 n'th moment - then all you have to
+ do is add the appropriate non-member functions, overloaded for each implemented
+ distribution type.
+ 
+<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">
+
+ 
+
+ Random numbers that approximate Quantiles of Distributions
+ 
+
+ If you want random numbers that are distributed in a specific way, for
+ example in a uniform, normal or triangular, see Boost.Random.
+ 
+
+ 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.
+ 
+</td></tr>
+</table></div>
+
+ For example, the binomial distribution has two parameters: n (the number
+ of trials) and p (the probability of success on one trial).
+ 
+
+ The <code class="computeroutput">binomial_distribution</code>
+ constructor therefore has two parameters:
+ 
+
+ <code class="computeroutput">binomial_distribution(RealType n, RealType
+ p);</code>
+ 
+
+ For this distribution the random variate is k: the number of successes
+ observed. The probability density/mass function (pdf) is therefore written
+ as f(k; n, 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">
+
+ 
+
+ Random Variates and Distribution Parameters
+ 
+
+ 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.
+ 
+</td></tr>
+</table></div>
+
+ As noted above the non-member function <code class="computeroutput">pdf</code>
+ has one parameter for the distribution object, and a second for the random
+ variate. So taking our binomial distribution example, we would write:
+ 
+
+ <code class="computeroutput">pdf(binomial_distribution<RealType>(n, p), k);</code>
+ 
+
+ 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">max</code>
+ to <code class="computeroutput">min</code> for the <code class="computeroutput">RealType</code>. (See <a href="../../backgrounders/implementation.html#math_toolkit.backgrounders.implementation.handling_of_floating_point_infinity">Handling
+ of Floating-Point Infinity</a> for rationale).
+ 
+
+ The range of random variate values that is permitted and supported can
+ be tested by using two functions <code class="computeroutput">range</code>
+ and <code class="computeroutput">support</code>.
+ 
+<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">
+
+ 
+
+ Discrete Probability Distributions
+ 
+
+ Note that the <a href="http://en.wikipedia.org/wiki/Discrete_probability_distribution" target="_top">discrete
+ distributions</a>, including the binomial, negative binomial, Poisson
+ & Bernoulli, are all mathematically defined as discrete functions:
+ that is to say the functions <code class="computeroutput">cdf</code>
+ and <code class="computeroutput">pdf</code> are only defined
+ for integral values of the random variate.
+ 
+
+ 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.
+ 
+
+ Users wanting to enforce a strict mathematical model may use <code class="computeroutput">floor</code> or <code class="computeroutput">ceil</code>
+ functions on the random variate prior to calling the distribution function.
+ 
+
+ 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 outwards:
+ 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 at least the requested coverage
+ will be present in the central region, and no more than
+ the requested coverage will be present in the tails.
+ 
+
+ This behaviour can be changed so that the quantile functions are rounded
+ differently, or 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.
+ 
+
+ 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.
+ 
+</td></tr>
+</table></div>
+<a name="complements"></a>
+ 
+<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>
+
+ Often you don't want the value of the CDF, but its complement, which is
+ to say <code class="computeroutput">1-p</code> rather than <code class="computeroutput">p</code>.
+ You could calculate the CDF and subtract it from <code class="computeroutput">1</code>,
+ but if <code class="computeroutput">p</code> is very close
+ to <code class="computeroutput">1</code> then cancellation error
+ will cause you to lose significant digits. In extreme cases, <code class="computeroutput">p</code> may actually be equal to <code class="computeroutput">1</code>, even though the true value of the complement
+ is non-zero.
+ 
+
+ See also "Why complements?"
+ 
+
+ In this library, whenever you want to receive a complement, just wrap all
+ the function arguments in a call to <code class="computeroutput">complement(...)</code>, for example:
+ 
+<pre class="programlisting">
+students_t dist(5);
+cout << "CDF at t = 1 is " << cdf(dist, 1.0) << endl;
+cout << "Complement of CDF at t = 1 is " << cdf(complement(dist, 1.0)) << endl;
+</pre>
+
+ 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">complement(...)</code>,
+ for example:
+ 
+<pre class="programlisting">
+students_t dist(5);
+
+for(double i = 10; i < 1e10; i *= 10)
+{
+ // Calculate the quantile for a 1 in i chance:
+ double t = quantile(complement(dist, 1/i));
+ // Print it out:
+ cout << "Quantile of students-t with 5 degrees of freedom\n"
+ "for a 1 in " << i << " chance is " << t << endl;
+}
+</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">
+
+ 
+
+ Critical values are just quantiles
+ 
+
+ Some texts talk about quantiles, others about critical values, the basic
+ rule is:
+ 
+
+ Lower critical values are the same as the quantile.
+ 
+
+ Upper critical values are the same as the quantile
+ from the complement of the probability.
+ 
+
+ 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 lower
+ critical value for a probability of 0.05 is given by:
+ 
+
+ <code class="computeroutput">quantile(binomial(100, 0.1), 0.05)</code>
+ 
+
+ and the upper critical value is given by:
+ 
+
+ <code class="computeroutput">quantile(complement(binomial(100, 0.1), 0.05))</code>
+ 
+
+ which return 4.82 and 14.63 respectively.
+ 
+</td></tr>
+</table></div>
+<a name="why_complements"></a>
+ 
+<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">
+
+ 
+
+ Why bother with complements anyway?
+ 
+
+ 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">0.999999940f</code>,
+ then <code class="computeroutput">1 -
+ 0.999999940f =
+ 5.96046448e-008</code>, but the result
+ is actually accurate to just one single bit: the
+ only bit that didn't cancel out!
+ 
+
+ 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-9, 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:
+ 
+
+ <code class="computeroutput">quantile(complement(students_t(10000), 1e-9))</code>
+ 
+
+ returns the expected t-statistic <code class="computeroutput">6.00336</code>,
+ where as:
+ 
+
+ <code class="computeroutput">quantile(students_t(10000), 1-1e-9f)</code>
+ 
+
+ raises an overflow error, since it is the same as:
+ 
+
+ <code class="computeroutput">quantile(students_t(10000), 1)</code>
+ 
+
+ Which has no finite result.
+ 
+</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>
+
+ 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:
+ 
+<pre class="programlisting">
+students_t::find_degrees_of_freedom(
+ 1.3, // difference from true mean to detect
+ 0.05, // maximum risk of falsely rejecting the null-hypothesis.
+ 0.1, // maximum risk of falsely failing to reject the null-hypothesis.
+ 0.13); // sample standard deviation
+</pre>
+
+ 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.
+ 
+<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">complement(...)</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">complement(...)</code>.
+ </li>
+<li>
+ Static member functions allow the parameters of a distribution to be
+ found from other information.
+ </li>
+</ul></div>
+
+ Now that you have the basics, the next section looks at some worked examples.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ 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 k: the number of successes observed.
+ This means the probability density/mass function (pdf) is written as f(k;
+ n, p).
+ 
+
+ Translating this into code the <code class="computeroutput">binomial_distribution</code>
+ constructor therefore has two parameters:
+ 
+<pre class="programlisting">
+binomial_distribution(RealType n, RealType p);
+</pre>
+
+ While the function <code class="computeroutput">pdf</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:
+ 
+<pre class="programlisting">
+pdf(binomial_distribution<RealType>(n, p), k);
+</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="weg/dist_construct_eg.html">
+ Distribution Construction Example</a></dt>
+<dt><a href="weg/st_eg.html"> Student's
+ t Distribution Examples</a></dt>
+<dd><dl>
+<dt><a href="weg/st_eg/tut_mean_intervals.html">
+ Calculating confidence intervals on the mean with the Students-t distribution</a></dt>
+<dt><a href="weg/st_eg/tut_mean_test.html">
+ Testing a sample mean for difference from a "true" mean</a></dt>
+<dt><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></dt>
+<dt><a href="weg/st_eg/two_sample_students_t.html">
+ Comparing the means of two samples with the Students-t test</a></dt>
+<dt><a href="weg/st_eg/paired_st.html">
+ Comparing two paired samples with the Student's t distribution</a></dt>
+</dl></dd>
+<dt><a href="weg/cs_eg.html"> Chi Squared
+ Distribution Examples</a></dt>
+<dd><dl>
+<dt><a href="weg/cs_eg/chi_sq_intervals.html">
+ Confidence Intervals on the Standard Deviation</a></dt>
+<dt><a href="weg/cs_eg/chi_sq_test.html">
+ Chi-Square Test for the Standard Deviation</a></dt>
+<dt><a href="weg/cs_eg/chi_sq_size.html">
+ Estimating the Required Sample Sizes for a Chi-Square Test for the Standard
+ Deviation</a></dt>
+</dl></dd>
+<dt><a href="weg/f_eg.html"> F Distribution
+ Examples</a></dt>
+<dt><a href="weg/binom_eg.html"> Binomial
+ Distribution Examples</a></dt>
+<dd><dl>
+<dt><a href="weg/binom_eg/binomial_coinflip_example.html">
+ Binomial Coin-Flipping Example</a></dt>
+<dt><a href="weg/binom_eg/binomial_quiz_example.html">
+ Binomial Quiz Example</a></dt>
+<dt><a href="weg/binom_eg/binom_conf.html">
+ Calculating Confidence Limits on the Frequency of Occurrence for a Binomial
+ Distribution</a></dt>
+<dt><a href="weg/binom_eg/binom_size_eg.html">
+ Estimating Sample Sizes for a Binomial Distribution.</a></dt>
+</dl></dd>
+<dt><a href="weg/neg_binom_eg.html"> Negative
+ Binomial Distribution Examples</a></dt>
+<dd><dl>
+<dt><a href="weg/neg_binom_eg/neg_binom_conf.html">
+ Calculating Confidence Limits on the Frequency of Occurrence for the
+ Negative Binomial Distribution</a></dt>
+<dt><a href="weg/neg_binom_eg/neg_binom_size_eg.html">
+ Estimating Sample Sizes for the Negative Binomial.</a></dt>
+<dt><a href="weg/neg_binom_eg/negative_binomial_example1.html">
+ Negative Binomial Sales Quota Example.</a></dt>
+<dt><a href="weg/neg_binom_eg/negative_binomial_example2.html">
+ Negative Binomial Table Printing Example.</a></dt>
+</dl></dd>
+<dt><a href="weg/normal_example.html"> Normal
+ Distribution Examples</a></dt>
+<dd><dl><dt><a href="weg/normal_example/normal_misc.html">
+ Some Miscellaneous Examples of the Normal (Gaussian) Distribution</a></dt></dl></dd>
+<dt><a href="weg/error_eg.html"> Error Handling
+ Example</a></dt>
+<dt><a href="weg/find_eg.html"> Find Location
+ and Scale Examples</a></dt>
+<dd><dl>
+<dt><a href="weg/find_eg/find_location_eg.html">
+ Find Location (Mean) Example</a></dt>
+<dt><a href="weg/find_eg/find_scale_eg.html">
+ Find Scale (Standard Deviation) Example</a></dt>
+<dt><a href="weg/find_eg/find_mean_and_sd_eg.html">
+ Find mean and standard deviation example</a></dt>
+</dl></dd>
+<dt><a href="weg/nag_library.html"> Comparison
+ with C, R, FORTRAN-style Free Functions</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="binom_eg/binomial_coinflip_example.html">
+ Binomial Coin-Flipping Example</a></dt>
+<dt><a href="binom_eg/binomial_quiz_example.html">
+ Binomial Quiz Example</a></dt>
+<dt><a href="binom_eg/binom_conf.html">
+ Calculating Confidence Limits on the Frequency of Occurrence for a Binomial
+ Distribution</a></dt>
+<dt><a href="binom_eg/binom_size_eg.html">
+ Estimating Sample Sizes for a Binomial Distribution.</a></dt>
+</dl></div>
+
+ See also the reference documentation for the <a href="../../dist_ref/dists/binomial_dist.html" title="Binomial Distribution">Binomial
+ Distribution</a>.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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 k / N,
+ for k successes out of N
+ 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">binomial_distribution<>::find_lower_bound_on_p</code>
+ and <code class="computeroutput">binomial_distribution<>::find_upper_bound_on_p</code>
+ allow you to calculate the confidence intervals for your estimate of
+ the occurrence frequency.
+ 
+
+ 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:
+ 
+<pre class="programlisting">
+#include <iostream>
+#include <iomanip>
+#include <boost/math/distributions/binomial.hpp>
+
+void confidence_limits_on_frequency(unsigned trials, unsigned successes)
+{
+ //
+ // trials = Total number of trials.
+ // successes = Total number of observed successes.
+ //
+ // Calculate confidence limits for an observed
+ // frequency of occurrence that follows a binomial
+ // distribution.
+ //
+ using namespace std;
+ using namespace boost::math;
+
+ // Print out general info:
+ cout <<
+ "___________________________________________\n"
+ "2-Sided Confidence Limits For Success Ratio\n"
+ "___________________________________________\n\n";
+ cout << setprecision(7);
+ cout << setw(40) << left << "Number of Observations" << "= " << trials << "\n";
+ cout << setw(40) << left << "Number of successes" << "= " << successes << "\n";
+ cout << setw(40) << left << "Sample frequency of occurrence" << "= " << double(successes) / trials << "\n";
+</pre>
+
+ The procedure now defines a table of significance levels: these are
+ the probabilities that the true occurrence frequency lies outside the
+ calculated interval:
+ 
+<pre class="programlisting">
+double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };
+</pre>
+
+ Some pretty printing of the table header follows:
+ 
+<pre class="programlisting">
+cout << "\n\n"
+ "_______________________________________________________________________\n"
+ "Confidence Lower CP Upper CP Lower JP Upper JP\n"
+ " Value (%) Limit Limit Limit Limit\n"
+ "_______________________________________________________________________\n";
+</pre>
+
+ And now for the important part - the intervals themselves - for each
+ value of alpha, we call <code class="computeroutput">find_lower_bound_on_p</code>
+ and <code class="computeroutput">find_lower_upper_on_p</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.
+ 
+
+ Please note that calculating two separate single sided bounds,
+ each with risk level α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 α, then:
+ 
+<div class="itemizedlist"><ul type="disc"><li>
+ The risk that it is less than the lower bound is α.
+ </li></ul></div>
+
+ and
+ 
+<div class="itemizedlist"><ul type="disc"><li>
+ The risk that it is greater than the upper bound is also α.
+ </li></ul></div>
+
+ So the risk it is outside upper or lower bound,
+ is twice alpha, and the probability
+ that it is inside the bounds is therefore not nearly as high as one
+ might have thought. This is why α/2 must be used in the calculations
+ below.
+ 
+
+ In contrast, had we been calculating a single-sided interval, for example:
+ "Calculate a lower bound so that we are P% sure that
+ the true occurrence frequency is greater than some value"
+ then we would not have divided by
+ two.
+ 
+
+ Finally note that <code class="computeroutput">binomial_distribution</code>
+ provides a choice of two methods for the calculation, we print out
+ the results from both methods in this example:
+ 
+<pre class="programlisting">
+ for(unsigned i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
+ {
+ // Confidence value:
+ cout << fixed << setprecision(3) << setw(10) << right << 100 * (1-alpha[i]);
+ // Calculate Clopper Pearson bounds:
+ double l = binomial_distribution<>::find_lower_bound_on_p(
+ trials, successes, alpha[i]/2);
+ double u = binomial_distribution<>::find_upper_bound_on_p(
+ trials, successes, alpha[i]/2);
+ // Print Clopper Pearson Limits:
+ cout << fixed << setprecision(5) << setw(15) << right << l;
+ cout << fixed << setprecision(5) << setw(15) << right << u;
+ // Calculate Jeffreys Prior Bounds:
+ l = binomial_distribution<>::find_lower_bound_on_p(
+ trials, successes, alpha[i]/2,
+ binomial_distribution<>::jeffreys_prior_interval);
+ u = binomial_distribution<>::find_upper_bound_on_p(
+ trials, successes, alpha[i]/2,
+ binomial_distribution<>::jeffreys_prior_interval);
+ // Print Jeffreys Prior Limits:
+ cout << fixed << setprecision(5) << setw(15) << right << l;
+ cout << fixed << setprecision(5) << setw(15) << right << u << std::endl;
+ }
+ cout << endl;
+}
+</pre>
+
+ 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:
+ 
+<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>
+
+ 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).
+ 
+
+ Compare that with the program output for 2000 trials:
+ 
+<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>
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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">binomial_distibution<>::find_maximum_number_of_trials</code>
+ can be used to estimate the maximum number of "uses" of that
+ component for some acceptable risk level alpha.
+ 
+
+ 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:
+ 
+<pre class="programlisting">
+void find_max_sample_size(
+ double p, // success ratio.
+ unsigned successes) // Total number of observed successes permitted.
+{
+</pre>
+
+ The routine then declares a table of probability thresholds: these
+ are the maximum acceptable probability that successes
+ or fewer events will be observed. In our example, successes
+ will be always zero, since we want no component failures, but in other
+ situations non-zero values may well make sense.
+ 
+<pre class="programlisting">
+double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };
+</pre>
+
+ 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:
+ 
+<pre class="programlisting">
+for(unsigned i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
+{
+ // Confidence value:
+ cout << fixed << setprecision(3) << setw(10) << right << 100 * (1-alpha[i]);
+ // calculate trials:
+ double t = binomial::find_maximum_number_of_trials(
+ successes, p, alpha[i]);
+ t = floor(t);
+ // Print Trials:
+ cout << fixed << setprecision(5) << setw(15) << right << t << endl;
+}
+</pre>
+
+ 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 minimum number of trials
+ required to observe a certain number of successes
+ using <code class="computeroutput">find_minimum_number_of_trials</code>
+ we would have taken the ceiling instead.
+ 
+
+ We'll finish off by looking at some sample output, firstly for a 1
+ in 1000 chance of component failure with each use:
+ 
+<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>
+
+ So 51 "uses" of the component would yield a 95% chance that
+ no component failures would be observed.
+ 
+
+ Compare that with a 1 in 1 million chance of component failure:
+ 
+<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>
+
+ 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).
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 
+
+ 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.
+ 
+
+ 
+
+ This example shows using the Binomial distribution to predict the
+ probability of heads and tails when throwing a coin.
+ 
+
+ 
+
+ 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).
+ 
+
+ 
+
+ (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).
+ 
+
+ 
+
+ First we need some includes and using statements to be able to use
+ the binomial distribution, some std input and output, and get started:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/binomial.hpp>
+ using boost::math::binomial;
+
+#include <iostream>
+ using std::cout; using std::endl; using std::left;
+#include <iomanip>
+ using std::setw;
+
+int main()
+{
+ cout << "Using Binomial distribution to predict how many heads and tails." << endl;
+ try
+ {</pre>
+
+ 
+
+ 
+
+ See note with the catch block
+ about why a try and catch block is always a good idea.
+ 
+
+ 
+
+ First, construct a binomial distribution with parameters success_fraction
+ 1/2, and how many flips.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+const double success_fraction = 0.5; // = 50% = 1/2 for a 'fair' coin.
+int flips = 10;
+binomial flip(flips, success_fraction);
+
+cout.precision(4);</pre>
+
+ 
+
+ 
+
+ Then some examples of using Binomial moments (and echoing the parameters).
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "From " << flips << " one can expect to get on average "
+ << mean(flip) << " heads (or tails)." << endl;
+cout << "Mode is " << mode(flip) << endl;
+cout << "Standard deviation is " << standard_deviation(flip) << endl;
+cout << "So about 2/3 will lie within 1 standard deviation and get between "
+ << ceil(mean(flip) - standard_deviation(flip)) << " and "
+ << floor(mean(flip) + standard_deviation(flip)) << " correct." << endl;
+cout << "Skewness is " << skewness(flip) << endl;
+// Skewness of binomial distributions is only zero (symmetrical)
+// if success_fraction is exactly one half,
+// for example, when flipping 'fair' coins.
+cout << "Skewness if success_fraction is " << flip.success_fraction()
+ << " is " << skewness(flip) << endl << endl; // Expect zero for a 'fair' coin.</pre>
+
+ 
+
+ 
+
+ Now we show a variety of predictions on the probability of heads:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "For " << flip.trials() << " coin flips: " << endl;
+cout << "Probability of getting no heads is " << pdf(flip, 0) << endl;
+cout << "Probability of getting at least one head is " << 1. - pdf(flip, 0) << endl;</pre>
+
+ 
+
+ 
+
+ When we want to calculate the probability for a range or values we
+ can sum the PDF's:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability of getting 0 or 1 heads is "
+ << pdf(flip, 0) + pdf(flip, 1) << endl; // sum of exactly == probabilities</pre>
+
+ 
+
+ 
+
+ Or we can use the cdf.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability of getting 0 or 1 (<= 1) heads is " << cdf(flip, 1) << endl;
+cout << "Probability of getting 9 or 10 heads is " << pdf(flip, 9) + pdf(flip, 10) << endl;</pre>
+
+ 
+
+ 
+
+ Note that using
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability of getting 9 or 10 heads is " << 1. - cdf(flip, 8) << endl;</pre>
+
+ 
+
+ 
+
+ is less accurate than using the complement
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability of getting 9 or 10 heads is " << cdf(complement(flip, 8)) << endl;</pre>
+
+ 
+
+ 
+
+ 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">cdf(complement(flip, 8))</code> does not use such a subtraction
+ internally, and so does not exhibit the problem.
+ 
+
+ 
+
+ To get the probability for a range of heads, we can either add the
+ pdfs for each number of heads
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability of between 4 and 6 heads (4 or 5 or 6) is "
+ // P(X == 4) + P(X == 5) + P(X == 6)
+ << pdf(flip, 4) + pdf(flip, 5) + pdf(flip, 6) << endl;</pre>
+
+ 
+
+ 
+
+ But this is probably less efficient than using the cdf
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability of between 4 and 6 heads (4 or 5 or 6) is "
+ // P(X <= 6) - P(X <= 3) == P(X < 4)
+ << cdf(flip, 6) - cdf(flip, 3) << endl;</pre>
+
+ 
+
+ 
+
+ Certainly for a bigger range like, 3 to 7
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability of between 3 and 7 heads (3, 4, 5, 6 or 7) is "
+ // P(X <= 7) - P(X <= 2) == P(X < 3)
+ << cdf(flip, 7) - cdf(flip, 2) << endl;
+cout << endl;</pre>
+
+ 
+
+ 
+
+ Finally, print two tables of probability for the exactly
+ and at least a number of heads.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+// Print a table of probability for the exactly a number of heads.
+cout << "Probability of getting exactly (==) heads" << endl;
+for (int successes = 0; successes <= flips; successes++)
+{ // Say success means getting a head (or equally success means getting a tail).
+ double probability = pdf(flip, successes);
+ cout << left << setw(2) << successes << " " << setw(10)
+ << probability << " or 1 in " << 1. / probability
+ << ", or " << probability * 100. << "%" << endl;
+} // for i
+cout << endl;
+
+// Tabulate the probability of getting between zero heads and 0 upto 10 heads.
+cout << "Probability of getting upto (<=) heads" << endl;
+for (int successes = 0; successes <= flips; successes++)
+{ // Say success means getting a head
+ // (equally success could mean getting a tail).
+ double probability = cdf(flip, successes); // P(X <= heads)
+ cout << setw(2) << successes << " " << setw(10) << left
+ << probability << " or 1 in " << 1. / probability << ", or "
+ << probability * 100. << "%"<< endl;
+} // for i</pre>
+
+ 
+
+ 
+
+ The last (0 to 10 heads) must, of course, be 100% probability.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+}
+catch(const std::exception& e)
+{
+ //</pre>
+
+ 
+
+ <a name="coinflip_eg_catch"></a>
+ 
+
+ It is always essential to include try & catch blocks because
+ default policies are to throw exceptions on arguments that are out
+ of domain or cause errors like numeric-overflow.
+ 
+
+ 
+
+ Lacking try & 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.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+ std::cout <<
+ "\n""Message from thrown exception was:\n " << e.what() << std::endl;
+}
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ See binomial_coinflip_example.cpp
+ for full source code, the program output looks like this:
+ 
+
+
+
+<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 (<= 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 (<</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>
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 
+
+ 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.
+ 
+
+ 
+
+ First, we need to be able to use the binomial distribution constructor
+ (and some std input/output, of course).
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/binomial.hpp>
+ using boost::math::binomial;
+
+#include <iostream>
+ using std::cout; using std::endl;
+ using std::ios; using std::flush; using std::left; using std::right; using std::fixed;
+#include <iomanip>
+ using std::setw; using std::setprecision;
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ 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:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+int questions = 16; // All the questions in the quiz.
+int answers = 4; // Possible answers to each question.
+double success_fraction = (double)answers / (double)questions; // If a random guess.
+// Caution: = answers / questions would be zero (because they are integers)!
+binomial quiz(questions, success_fraction);</pre>
+
+ 
+
+ 
+
+ and display the distribution parameters we used thus:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "In a quiz with " << quiz.trials()
+ << " questions and with a probability of guessing right of "
+ << quiz.success_fraction() * 100 << " %"
+ << " or 1 in " << static_cast<int>(1. / quiz.success_fraction()) << endl;</pre>
+
+ 
+
+ 
+
+ Show a few probabilities of just guessing:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability of getting none right is " << pdf(quiz, 0) << endl; // 0.010023
+cout << "Probability of getting exactly one right is " << pdf(quiz, 1) << endl;
+cout << "Probability of getting exactly two right is " << pdf(quiz, 2) << endl;
+int pass_score = 11;
+cout << "Probability of getting exactly " << pass_score << " answers right by chance is "
+ << pdf(quiz, questions) << endl;</pre>
+
+ 
+
+
+
+<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>
+
+ 
+
+ These don't give any encouragement to guessers!
+ 
+
+ 
+
+ We can tabulate the 'getting exactly right' ( == ) probabilities
+ thus:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "\n" "Guessed Probability" << right << endl;
+for (int successes = 0; successes <= questions; successes++)
+{
+ double probability = pdf(quiz, successes);
+ cout << setw(2) << successes << " " << probability << endl;
+}
+cout << endl;</pre>
+
+ 
+
+
+
+<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>
+
+ 
+
+ Then we can add the probabilities of some 'exactly right' like this:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability of getting none or one right is " << pdf(quiz, 0) + pdf(quiz, 1) << endl;</pre>
+
+ 
+
+
+
+<pre class="programlisting">Probability of getting none or one right is 0.0634764
+</pre>
+
+ 
+
+ 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:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability of getting none or one right is " << cdf(quiz, 1) << endl;</pre>
+
+ 
+
+
+
+<pre class="programlisting">Probability of getting none or one right is 0.0634764
+</pre>
+
+ 
+
+ Since the cdf is inclusive, we can get the probability of getting
+ up to 10 right ( <= )
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability of getting <= 10 right (to fail) is " << cdf(quiz, 10) << endl;</pre>
+
+ 
+
+
+
+<pre class="programlisting">Probability of getting <= 10 right (to fail) is 0.999715
+</pre>
+
+ 
+
+ To get the probability of getting 11 or more right (to pass), it
+ is tempting to use
+
+<pre class="programlisting">
+1 - cdf(quiz, 10)</pre>
+
+ to get the probability of > 10
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability of getting > 10 right (to pass) is " << 1 - cdf(quiz, 10) << endl;</pre>
+
+ 
+
+
+
+<pre class="programlisting">Probability of getting > 10 right (to pass) is 0.000285239
+</pre>
+
+ 
+
+ But this should be resisted in favor of using the complement function.
+ Why complements?
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability of getting > 10 right (to pass) is " << cdf(complement(quiz, 10)) << endl;</pre>
+
+ 
+
+
+
+<pre class="programlisting">Probability of getting > 10 right (to pass) is 0.000285239
+</pre>
+
+ 
+
+ And we can check that these two, <= 10 and > 10, add up to
+ unity.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+BOOST_ASSERT((cdf(quiz, 10) + cdf(complement(quiz, 10))) == 1.);</pre>
+
+ 
+
+ 
+
+ If we want a < rather than a <= test, because the CDF is inclusive,
+ we must subtract one from the score.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability of getting less than " << pass_score
+ << " (< " << pass_score << ") answers right by guessing is "
+ << cdf(quiz, pass_score -1) << endl;</pre>
+
+ 
+
+
+
+<pre class="programlisting">Probability of getting less than 11 (< 11) answers right by guessing is 0.999715
+</pre>
+
+ 
+
+ and similarly to get a >= rather than a > 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 inclusive, then
+ its complement must be exclusive otherwise there
+ would be one possible outcome counted twice!
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability of getting at least " << pass_score
+ << "(>= " << pass_score << ") answers right by guessing is "
+ << cdf(complement(quiz, pass_score-1))
+ << ", only 1 in " << 1/cdf(complement(quiz, pass_score-1)) << endl;
+
+BOOST_ASSERT((cdf(quiz, pass_score -1) + cdf(complement(quiz, pass_score-1))) == 1);</pre>
+
+ 
+
+
+
+<pre class="programlisting">Probability of getting at least 11 (>= 11) answers right by guessing is 0.000285239, only 1 in 3505.83
+</pre>
+
+ 
+
+ Finally we can tabulate some probabilities:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "\n" "At most (<=)""\n""Guessed OK Probability" << right << endl;
+for (int score = 0; score <= questions; score++)
+{
+ cout << setw(2) << score << " " << setprecision(10)
+ << cdf(quiz, score) << endl;
+}
+cout << endl;</pre>
+
+ 
+
+
+
+<pre class="programlisting">At most (<=)
+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>
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "\n" "At least (>)""\n""Guessed OK Probability" << right << endl;
+for (int score = 0; score <= questions; score++)
+{
+ cout << setw(2) << score << " " << setprecision(10)
+ << cdf(complement(quiz, score)) << endl;
+}</pre>
+
+ 
+
+
+
+<pre class="programlisting">At least (>)
+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>
+
+ 
+
+ We now consider the probabilities of ranges
+ of correct guesses.
+ 
+
+ 
+
+ First, calculate the probability of getting a range of guesses right,
+ by adding the exact probabilities of each from low ... high.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+int low = 3; // Getting at least 3 right.
+int high = 5; // Getting as most 5 right.
+double sum = 0.;
+for (int i = low; i <= high; i++)
+{
+ sum += pdf(quiz, i);
+}
+cout.precision(4);
+cout << "Probability of getting between "
+ << low << " and " << high << " answers right by guessing is "
+ << sum << endl; // 0.61323</pre>
+
+ 
+
+
+
+<pre class="programlisting">Probability of getting between 3 and 5 answers right by guessing is 0.6132
+</pre>
+
+ 
+
+ Or, usually better, we can use the difference of cdfs instead:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability of getting between " << low << " and " << high << " answers right by guessing is "
+ << cdf(quiz, high) - cdf(quiz, low - 1) << endl; // 0.61323</pre>
+
+ 
+
+
+
+<pre class="programlisting">Probability of getting between 3 and 5 answers right by guessing is 0.6132
+</pre>
+
+ 
+
+ And we can also try a few more combinations of high and low choices:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+low = 1; high = 6;
+cout << "Probability of getting between " << low << " and " << high << " answers right by guessing is "
+ << cdf(quiz, high) - cdf(quiz, low - 1) << endl; // 1 and 6 P= 0.91042
+low = 1; high = 8;
+cout << "Probability of getting between " << low << " and " << high << " answers right by guessing is "
+ << cdf(quiz, high) - cdf(quiz, low - 1) << endl; // 1 <= x 8 P = 0.9825
+low = 4; high = 4;
+cout << "Probability of getting between " << low << " and " << high << " answers right by guessing is "
+ << cdf(quiz, high) - cdf(quiz, low - 1) << endl; // 4 <= x 4 P = 0.22520</pre>
+
+ 
+
+
+
+<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>
+
+ <a name="math_toolkit.dist.stat_tut.weg.binom_eg.binomial_quiz_example.using_binomial_distribution_moments"></a>
+ 
+<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>
+
+ 
+
+ Using moments of the distribution, we can say more about the spread
+ of results from guessing.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "By guessing, on average, one can expect to get " << mean(quiz) << " correct answers." << endl;
+cout << "Standard deviation is " << standard_deviation(quiz) << endl;
+cout << "So about 2/3 will lie within 1 standard deviation and get between "
+ << ceil(mean(quiz) - standard_deviation(quiz)) << " and "
+ << floor(mean(quiz) + standard_deviation(quiz)) << " correct." << endl;
+cout << "Mode (the most frequent) is " << mode(quiz) << endl;
+cout << "Skewness is " << skewness(quiz) << endl;</pre>
+
+ 
+
+
+
+<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>
+
+ <a name="math_toolkit.dist.stat_tut.weg.binom_eg.binomial_quiz_example.quantiles"></a>
+ 
+<h5>
+<a name="id527704"></a>
+ Quantiles
+ </h5>
+
+ 
+
+ The quantiles (percentiles or percentage points) for a few probability
+ levels:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Quartiles " << quantile(quiz, 0.25) << " to "
+ << quantile(complement(quiz, 0.25)) << endl; // Quartiles
+cout << "1 standard deviation " << quantile(quiz, 0.33) << " to "
+ << quantile(quiz, 0.67) << endl; // 1 sd
+cout << "Deciles " << quantile(quiz, 0.1) << " to "
+ << quantile(complement(quiz, 0.1))<< endl; // Deciles
+cout << "5 to 95% " << quantile(quiz, 0.05) << " to "
+ << quantile(complement(quiz, 0.05))<< endl; // 5 to 95%
+cout << "2.5 to 97.5% " << quantile(quiz, 0.025) << " to "
+ << quantile(complement(quiz, 0.025)) << endl; // 2.5 to 97.5%
+cout << "2 to 98% " << quantile(quiz, 0.02) << " to "
+ << quantile(complement(quiz, 0.02)) << endl; // 2 to 98%
+
+cout << "If guessing then percentiles 1 to 99% will get " << quantile(quiz, 0.01)
+ << " to " << quantile(complement(quiz, 0.01)) << " right." << endl;</pre>
+
+ 
+
+ 
+
+ Notice that these output integral values because the default policy
+ is <code class="computeroutput">integer_round_outwards</code>.
+ 
+
+
+
+<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>
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ 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">integer_round_outwards</code>,
+ so the lower quantile is rounded down, and the upper quantile is
+ rounded up.
+ 
+
+ 
+
+ 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>.
+ 
+
+ 
+
+ We could control the policy for all
+ distributions by
+ 
+
+
+
+<pre class="programlisting">
+#define BOOST_MATH_DISCRETE_QUANTILE_POLICY real
+
+at the head of the program would make this policy apply
+</pre>
+
+ 
+
+ #define BOOST_MATH_DISCRETE_QUANTILE_POLICY real
+ 
+
+
+
+<pre class="programlisting">
+at the head of the program would make this policy apply
+</pre>
+
+ 
+
+ at the head of the program would make this policy apply to this
+ one, and only, translation unit.
+ 
+
+ 
+
+ Or we can now create a (typedef for) policy that has discrete quantiles
+ real (here avoiding any 'using namespaces ...' statements):
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+using boost::math::policies::policy;
+using boost::math::policies::discrete_quantile;
+using boost::math::policies::real;
+using boost::math::policies::integer_round_outwards; // Default.
+typedef boost::math::policies::policy<discrete_quantile<real> > real_quantile_policy;</pre>
+
+ 
+
+ 
+
+ Add a custom binomial distribution called
+
+<pre class="programlisting">
+real_quantile_binomial</pre>
+
+ that uses
+
+<pre class="programlisting">
+real_quantile_policy</pre>
+
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+using boost::math::binomial_distribution;
+typedef binomial_distribution<double, real_quantile_policy> real_quantile_binomial;</pre>
+
+ 
+
+ 
+
+ Construct an object of this custom distribution:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+real_quantile_binomial quiz_real(questions, success_fraction);</pre>
+
+ 
+
+ 
+
+ And use this to show some quantiles - that now have real rather than
+ integer values.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Quartiles " << quantile(quiz, 0.25) << " to "
+ << quantile(complement(quiz_real, 0.25)) << endl; // Quartiles 2 to 4.6212
+cout << "1 standard deviation " << quantile(quiz_real, 0.33) << " to "
+ << quantile(quiz_real, 0.67) << endl; // 1 sd 2.6654 4.194
+cout << "Deciles " << quantile(quiz_real, 0.1) << " to "
+ << quantile(complement(quiz_real, 0.1))<< endl; // Deciles 1.3487 5.7583
+cout << "5 to 95% " << quantile(quiz_real, 0.05) << " to "
+ << quantile(complement(quiz_real, 0.05))<< endl; // 5 to 95% 0.83739 6.4559
+cout << "2.5 to 97.5% " << quantile(quiz_real, 0.025) << " to "
+ << quantile(complement(quiz_real, 0.025)) << endl; // 2.5 to 97.5% 0.42806 7.0688
+cout << "2 to 98% " << quantile(quiz_real, 0.02) << " to "
+ << quantile(complement(quiz_real, 0.02)) << endl; // 2 to 98% 0.31311 7.7880
+
+cout << "If guessing, then percentiles 1 to 99% will get " << quantile(quiz_real, 0.01)
+ << " to " << quantile(complement(quiz_real, 0.01)) << " right." << endl;</pre>
+
+ 
+
+
+
+<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>
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ See binomial_quiz_example.cpp
+ for full source code and output.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="cs_eg/chi_sq_intervals.html">
+ Confidence Intervals on the Standard Deviation</a></dt>
+<dt><a href="cs_eg/chi_sq_test.html">
+ Chi-Square Test for the Standard Deviation</a></dt>
+<dt><a href="cs_eg/chi_sq_size.html">
+ Estimating the Required Sample Sizes for a Chi-Square Test for the Standard
+ Deviation</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ The full example code & sample output is in chi_square_std_deviation_test.cpp.
+ 
+
+ We'll begin by defining the procedure that will calculate and print
+ out the confidence intervals:
+ 
+<pre class="programlisting">
+void confidence_limits_on_std_deviation(
+ double Sd, // Sample Standard Deviation
+ unsigned N) // Sample size
+{
+</pre>
+
+ We'll begin by printing out some general information:
+ 
+<pre class="programlisting">
+cout <<
+ "________________________________________________\n"
+ "2-Sided Confidence Limits For Standard Deviation\n"
+ "________________________________________________\n\n";
+cout << setprecision(7);
+cout << setw(40) << left << "Number of Observations" << "= " << N << "\n";
+cout << setw(40) << left << "Standard Deviation" << "= " << Sd << "\n";
+</pre>
+
+ and then define a table of significance levels for which we'll calculate
+ intervals:
+ 
+<pre class="programlisting">
+double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };
+</pre>
+
+ The distribution we'll need to calculate the confidence intervals is
+ a Chi Squared distribution, with N-1 degrees of freedom:
+ 
+<pre class="programlisting">
+chi_squared dist(N - 1);
+</pre>
+
+ For each value of alpha, the formula for the confidence interval is
+ given by:
+ 
+
+ <img src="../../../../../../equations/chi_squ_tut1.png">
+ 
+
+ Where <img src="../../../../../../equations/chi_squ_tut2.png"> is the upper critical value, and <img src="../../../../../../equations/chi_squ_tut3.png"> is
+ the lower critical value of the Chi Squared distribution.
+ 
+
+ In code we begin by printing out a table header:
+ 
+<pre class="programlisting">
+cout << "\n\n"
+ "_____________________________________________\n"
+ "Confidence Lower Upper\n"
+ " Value (%) Limit Limit\n"
+ "_____________________________________________\n";
+</pre>
+
+ 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:
+ 
+<pre class="programlisting">
+for(unsigned i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
+{
+ // Confidence value:
+ cout << fixed << setprecision(3) << setw(10) << right << 100 * (1-alpha[i]);
+ // Calculate limits:
+ double lower_limit = sqrt((N - 1) * Sd * Sd / quantile(complement(dist, alpha[i] / 2)));
+ double upper_limit = sqrt((N - 1) * Sd * Sd / quantile(dist, alpha[i] / 2));
+ // Print Limits:
+ cout << fixed << setprecision(5) << setw(15) << right << lower_limit;
+ cout << fixed << setprecision(5) << setw(15) << right << upper_limit << endl;
+}
+cout << endl;
+</pre>
+
+ 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.
+ 
+<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>
+
+ So at the 95% confidence level we conclude that the standard deviation
+ is between 0.00551 and 0.00729.
+ 
+<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>
+
+ Similarly, we can also list the confidence intervals for the standard
+ deviation for the common confidence levels 95%, for increasing numbers
+ of observations.
+ 
+
+ The standard deviation used to compute these values is unity, so the
+ limits listed are multipliers 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.
+ 
+<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>
+
+ With just 2 observations the limits are from 0.445
+ up to to 31.9, so the standard deviation
+ might be about half the observed value
+ up to 30 times the observed value!
+ 
+
+ 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.
+ 
+
+ 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 twice
+ the median.
+ 
+
+ 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%.
+ 
+
+ 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).
+ 
+
+ For 10000 observations, the interval is 0.99 to 1.1 - finally a really
+ convincing + or -1% confidence.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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?"
+ 
+
+ The class template chi_squared_distribution
+ has a static method <code class="computeroutput">find_degrees_of_freedom</code>
+ that will calculate this value for some acceptable risk of type I failure
+ alpha, type II failure beta,
+ and difference from the standard deviation diff.
+ Please note that the method used works on variance, and not standard
+ deviation as is usual for the Chi Squared Test.
+ 
+
+ The code for this example is located in chi_square_std_dev_test.cpp.
+ 
+
+ We begin by defining a procedure to print out the sample sizes required
+ for various risk levels:
+ 
+<pre class="programlisting">
+void chi_squared_sample_sized(
+ double diff, // difference from variance to detect
+ double variance) // true variance
+{
+</pre>
+
+ The procedure begins by printing out the input data:
+ 
+<pre class="programlisting">
+using namespace std;
+using namespace boost::math;
+
+// Print out general info:
+cout <<
+ "_____________________________________________________________\n"
+ "Estimated sample sizes required for various confidence levels\n"
+ "_____________________________________________________________\n\n";
+cout << setprecision(5);
+cout << setw(40) << left << "True Variance" << "= " << variance << "\n";
+cout << setw(40) << left << "Difference to detect" << "= " << diff << "\n";
+</pre>
+
+ And defines a table of significance levels for which we'll calculate
+ sample sizes:
+ 
+<pre class="programlisting">
+double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };
+</pre>
+
+ For each value of alpha we can calculate two sample sizes: one where
+ the sample variance is less than the true value by diff
+ and one where it is greater than the true value by diff.
+ 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 diff that's passed
+ to <code class="computeroutput">find_degrees_of_freedom</code>.
+ Finally in this example we'll simply things, and let risk level beta
+ be the same as alpha:
+ 
+<pre class="programlisting">
+cout << "\n\n"
+ "_______________________________________________________________\n"
+ "Confidence Estimated Estimated\n"
+ " Value (%) Sample Size Sample Size\n"
+ " (lower one (upper one\n"
+ " sided test) sided test)\n"
+ "_______________________________________________________________\n";
+//
+// Now print out the data for the table rows.
+//
+for(unsigned i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
+{
+ // Confidence value:
+ cout << fixed << setprecision(3) << setw(10) << right << 100 * (1-alpha[i]);
+ // calculate df for a lower single sided test:
+ double df = chi_squared::find_degrees_of_freedom(
+ -diff, alpha[i], alpha[i], variance);
+ // convert to sample size:
+ double size = ceil(df) + 1;
+ // Print size:
+ cout << fixed << setprecision(0) << setw(16) << right << size;
+ // calculate df for an upper single sided test:
+ df = chi_squared::find_degrees_of_freedom(
+ diff, alpha[i], alpha[i], variance);
+ // convert to sample size:
+ size = ceil(df) + 1;
+ // Print size:
+ cout << fixed << setprecision(0) << setw(16) << right << size << endl;
+}
+cout << endl;
+</pre>
+
+ 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?".
+ 
+
+ To use our procedure above, we have to convert the standard deviations
+ to variance (square them), after which the program output looks like
+ this:
+ 
+<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>
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ 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:
+ 
+<pre class="programlisting">
+void chi_squared_test(
+ double Sd, // Sample std deviation
+ double D, // True std deviation
+ unsigned N, // Sample size
+ double alpha) // Significance level
+{
+</pre>
+
+ The procedure begins by printing a summary of the input data:
+ 
+<pre class="programlisting">
+using namespace std;
+using namespace boost::math;
+
+// Print header:
+cout <<
+ "______________________________________________\n"
+ "Chi Squared test for sample standard deviation\n"
+ "______________________________________________\n\n";
+cout << setprecision(5);
+cout << setw(55) << left << "Number of Observations" << "= " << N << "\n";
+cout << setw(55) << left << "Sample Standard Deviation" << "= " << Sd << "\n";
+cout << setw(55) << left << "Expected True Standard Deviation" << "= " << D << "\n\n";
+</pre>
+
+ 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):
+ 
+<pre class="programlisting">
+double t_stat = (N - 1) * (Sd / D) * (Sd / D);
+cout << setw(55) << left << "Test Statistic" << "= " << t_stat << "\n";
+</pre>
+
+ The distribution we need to use, is a Chi Squared distribution with
+ N-1 degrees of freedom:
+ 
+<pre class="programlisting">
+chi_squared dist(N - 1);
+</pre>
+
+ The various hypothesis that can be tested are summarised in the following
+ table:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Hypothesis
+ 
+ </th>
+<th>
+ 
+ Test
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ The null-hypothesis: there is no difference in standard deviation
+ from the specified value
+ 
+ </td>
+<td>
+ 
+ Reject if T < χ2(1-alpha/2; N-1) or T > χ2(alpha/2; N-1)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ The alternative hypothesis: there is a difference in standard
+ deviation from the specified value
+ 
+ </td>
+<td>
+ 
+ Reject if χ2(1-alpha/2; N-1) >= T >= χ2(alpha/2; N-1)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ The alternative hypothesis: the standard deviation is less
+ than the specified value
+ 
+ </td>
+<td>
+ 
+ Reject if χ2(1-alpha; N-1) <= T
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ The alternative hypothesis: the standard deviation is greater
+ than the specified value
+ 
+ </td>
+<td>
+ 
+ Reject if χ2(alpha; N-1) >= T
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+
+ Where χ2(alpha; N-1) is the upper critical value of the Chi Squared distribution,
+ and χ2(1-alpha; N-1) is the lower critical value.
+ 
+
+ 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:
+ 
+<pre class="programlisting">
+double ucv = quantile(complement(dist, alpha));
+double ucv2 = quantile(complement(dist, alpha / 2));
+double lcv = quantile(dist, alpha);
+double lcv2 = quantile(dist, alpha / 2);
+cout << setw(55) << left << "Upper Critical Value at alpha: " << "= "
+ << setprecision(3) << scientific << ucv << "\n";
+cout << setw(55) << left << "Upper Critical Value at alpha/2: " << "= "
+ << setprecision(3) << scientific << ucv2 << "\n";
+cout << setw(55) << left << "Lower Critical Value at alpha: " << "= "
+ << setprecision(3) << scientific << lcv << "\n";
+cout << setw(55) << left << "Lower Critical Value at alpha/2: " << "= "
+ << setprecision(3) << scientific << lcv2 << "\n\n";
+</pre>
+
+ 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:
+ 
+<pre class="programlisting">
+cout << setw(55) << left <<
+ "Results for Alternative Hypothesis and alpha" << "= "
+ << setprecision(4) << fixed << alpha << "\n\n";
+cout << "Alternative Hypothesis Conclusion\n";
+
+cout << "Standard Deviation != " << setprecision(3) << fixed << D << " ";
+if((ucv2 < t_stat) || (lcv2 > t_stat))
+ cout << "ACCEPTED\n";
+else
+ cout << "REJECTED\n";
+
+cout << "Standard Deviation < " << setprecision(3) << fixed << D << " ";
+if(lcv > t_stat)
+ cout << "ACCEPTED\n";
+else
+ cout << "REJECTED\n";
+
+cout << "Standard Deviation > " << setprecision(3) << fixed << D << " ";
+if(ucv < t_stat)
+ cout << "ACCEPTED\n";
+else
+ cout << "REJECTED\n";
+cout << endl << endl;
+</pre>
+
+ 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>.
+ 
+<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 < 0.100 ACCEPTED
+Standard Deviation > 0.100 REJECTED
+</pre>
+
+ 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 is not 0.1.
+ 
+
+ 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?".
+ 
+
+ The program output now looks like this:
+ 
+<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 < 10.000 REJECTED
+Standard Deviation > 10.000 ACCEPTED
+</pre>
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ See distribution_construction.cpp
+ for full source code.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ First we need some includes to access the negative binomial distribution
+ (and the binomial, beta and gamma too).
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/negative_binomial.hpp> // for negative_binomial_distribution
+ using boost::math::negative_binomial_distribution; // default type is double.
+ using boost::math::negative_binomial; // typedef provides default type is double.
+#include <boost/math/distributions/binomial.hpp> // for binomial_distribution.
+#include <boost/math/distributions/beta.hpp> // for beta_distribution.
+#include <boost/math/distributions/gamma.hpp> // for gamma_distribution.
+#include <boost/math/distributions/normal.hpp> // for normal_distribution.</pre>
+
+ 
+
+ 
+
+ Several examples of constructing distributions follow: 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ First, a negative binomial distribution with 8 successes and a success
+ fraction 0.25, 25% or 1 in 4, is constructed like this:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+boost::math::negative_binomial_distribution<double> mydist0(8., 0.25);</pre>
+
+ 
+
+ 
+
+ But this is inconveniently long, so by writing
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+using namespace boost::math;</pre>
+
+ 
+
+ 
+
+ or
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+using boost::math::negative_binomial_distribution;</pre>
+
+ 
+
+ 
+
+ we can reduce typing.
+ 
+
+ 
+
+ 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:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+negative_binomial_distribution<> mydist9(8., 0.25); // Uses default RealType = double.</pre>
+
+ 
+
+ 
+
+ But the name "negative_binomial_distribution" is still inconveniently
+ long, so for most distributions, a convenience typedef is provided,
+ for example:
+ 
+
+
+
+<pre class="programlisting">
+typedef negative_binomial_distribution<double> negative_binomial; // Reserved name of type double.
+</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">
+ This convenience typedef is not provided if
+ a clash would occur with the name of a function: currently only "beta"
+ and "gamma" fall into this category.
+ </td></tr>
+</table></div>
+
+ 
+
+ So, after a using statement,
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+using boost::math::negative_binomial;</pre>
+
+ 
+
+ 
+
+ we have a convenient typedef to <code class="computeroutput">negative_binomial_distribution<double></code>:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+negative_binomial mydist(8., 0.25);</pre>
+
+ 
+
+ 
+
+ Some more examples using the convenience typedef:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+negative_binomial mydist10(5., 0.4); // Both arguments double.</pre>
+
+ 
+
+ 
+
+ And automatic conversion takes place, so you can use integers and floats:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+negative_binomial mydist11(5, 0.4); // Using provided typedef double, int and double arguments.</pre>
+
+ 
+
+ 
+
+ This is probably the most common usage.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+negative_binomial mydist12(5., 0.4F); // Double and float arguments.
+negative_binomial mydist13(5, 1); // Both arguments integer.</pre>
+
+ 
+
+ 
+
+ Similarly for most other distributions like the binomial.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+binomial mybinomial(1, 0.5); // is more concise than
+binomial_distribution<> mybinomd1(1, 0.5);</pre>
+
+ 
+
+ 
+
+ 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:
+ 
+
+
+
+<pre class="programlisting">
+using boost::math::beta;
+beta mybetad0(1, 0.5); // Error beta is a math FUNCTION!
+</pre>
+
+ 
+
+ Which produces the error messages:
+ 
+
+
+
+<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>
+
+ 
+
+ Instead you should use:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+using boost::math::beta_distribution;
+beta_distribution<> mybetad1(1, 0.5);</pre>
+
+ 
+
+ 
+
+ or for the gamma distribution:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+gamma_distribution<> mygammad1(1, 0.5);</pre>
+
+ 
+
+ 
+
+ We can, of course, still provide the type explicitly thus:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+// Explicit double precision:
+negative_binomial_distribution<double> mydist1(8., 0.25);
+
+// Explicit float precision, double arguments are truncated to float:
+negative_binomial_distribution<float> mydist2(8., 0.25);
+
+// Explicit float precision, integer & double arguments converted to float.
+negative_binomial_distribution<float> mydist3(8, 0.25);
+
+// Explicit float precision, float arguments, so no conversion:
+negative_binomial_distribution<float> mydist4(8.F, 0.25F);
+
+// Explicit float precision, integer arguments promoted to float.
+negative_binomial_distribution<float> mydist5(8, 1);
+
+// Explicit double precision:
+negative_binomial_distribution<double> mydist6(8., 0.25);
+
+// Explicit long double precision:
+negative_binomial_distribution<long double> mydist7(8., 0.25);</pre>
+
+ 
+
+ 
+
+ And if you have your own RealType called MyFPType, for example NTL
+ RR (an arbitrary precision type), then we can write:
+ 
+
+
+
+<pre class="programlisting">
+negative_binomial_distribution<MyFPType> mydist6(8, 1); // Integer arguments -> MyFPType.
+</pre>
+
+ <a name="math_toolkit.dist.stat_tut.weg.dist_construct_eg.default_arguments_to_distribution_constructors_"></a>
+ 
+<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>
+
+ 
+
+ 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:
+ 
+
+
+
+<pre class="programlisting">
+negative_binomial_distribution<> mydist8;
+</pre>
+
+
+
+<pre class="programlisting">error C2512 no appropriate default constructor available.</pre>
+
+ 
+
+ 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:
+ 
+
+
+
+<pre class="programlisting">
+normal_distribution(RealType mean = 0, RealType sd = 1);
+</pre>
+
+ 
+
+ So in this case we can write:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+ using boost::math::normal;
+
+ normal norm1; // Standard normal distribution.
+ normal norm2(2); // Mean = 2, std deviation = 1.
+ normal norm3(2, 3); // Mean = 2, std deviation = 3.
+
+ return 0;
+} // int main()</pre>
+
+ 
+
+ 
+
+ There is no useful output from this program, of course. 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ But, by default, exceptions will be raised,
+ 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.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Since we know that this is a single file program we could just add:
+ 
+
+
+
+<pre class="programlisting">
+#define BOOST_MATH_DOMAIN_ERROR_POLICY ignore_error
+</pre>
+
+ 
+
+ 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:
+ 
+
+
+
+<pre class="programlisting">
+#define BOOST_MATH_DOMAIN_ERROR_POLICY errno_on_error
+</pre>
+
+ 
+
+ To ensure the <code class="computeroutput">::errno</code>
+ is set when a domain error occurs as well as returning a NaN.
+ 
+
+ 
+
+ This is safe provided the program consists of a single translation
+ unit and we place the define before
+ any #includes. Note that should we add the define after the includes
+ then it will have no effect! A warning such as:
+ 
+
+
+
+<pre class="programlisting">warning C4005: 'BOOST_MATH_OVERFLOW_ERROR_POLICY' : macro redefinition</pre>
+
+ 
+
+ is a certain sign that it will not have the desired
+ effect.
+ 
+
+ 
+
+ We'll begin our sample program with the needed includes:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+// Boost
+#include <boost/math/distributions/students_t.hpp>
+ using boost::math::students_t; // Probability of students_t(df, t).
+
+// std
+#include <iostream>
+ using std::cout;
+ using std::endl;
+
+#include <stdexcept>
+ using std::exception;</pre>
+
+ 
+
+ 
+
+ 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:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+int main()
+{
+ cout << "Example error handling using Student's t function. " << endl;
+ cout << "BOOST_MATH_DOMAIN_ERROR_POLICY is set to: "
+ << BOOST_STRINGIZE(BOOST_MATH_DOMAIN_ERROR_POLICY) << endl;
+
+ double degrees_of_freedom = -1; // A bad argument!
+ double t = 10;
+
+ try
+ {
+ errno = 0;
+ students_t dist(degrees_of_freedom); // exception is thrown here if enabled
+ double p = cdf(dist, t);
+ // test for error reported by other means:
+ if((boost::math::isnan)(p))
+ {
+ cout << "cdf returned a NaN!" << endl;
+ cout << "errno is set to: " << errno << endl;
+ }
+ else
+ cout << "Probability of Student's t is " << p << endl;
+ }
+ catch(const std::exception& e)
+ {
+ std::cout <<
+ "\n""Message from thrown exception was:\n " << e.what() << std::endl;
+ }
+
+ return 0;
+} // int main()</pre>
+
+ 
+
+ 
+
+ Here's what the program output looks like with a default build (one
+ that does throw exceptions):
+ 
+
+
+
+<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<double>::students_t_distribution:
+ Degrees of freedom argument is -1, but must be > 0 !
+</pre>
+
+ 
+
+ Alternatively let's build with:
+ 
+
+
+
+<pre class="programlisting">
+#define BOOST_MATH_DOMAIN_ERROR_POLICY ignore_error
+</pre>
+
+ 
+
+ Now the program output is:
+ 
+
+
+
+<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>
+
+ 
+
+ And finally let's build with:
+ 
+
+
+
+<pre class="programlisting">
+#define BOOST_MATH_DOMAIN_ERROR_POLICY errno_on_error
+</pre>
+
+ 
+
+ Which gives the output:
+ 
+
+
+
+<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>
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">
+
+ If throwing of exceptions is enabled (the default) but you do not have try & catch block, then the program
+ will terminate with an uncaught exception and probably abort.
+ 
+
+ Therefore to get the benefit of helpful error messages, enabling all exceptions and using try & catch is
+ recommended for most applications.
+ 
+
+ However, for simplicity, the is not done for most examples.
+ 
+</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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?".
+ 
+
+ 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.
+ 
+
+ 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>.
+ 
+
+ We'll begin by defining the procedure to conduct the test:
+ 
+<pre class="programlisting">
+void f_test(
+ double sd1, // Sample 1 std deviation
+ double sd2, // Sample 2 std deviation
+ double N1, // Sample 1 size
+ double N2, // Sample 2 size
+ double alpha) // Significance level
+{
+</pre>
+
+ The procedure begins by printing out a summary of our input data:
+ 
+<pre class="programlisting">
+using namespace std;
+using namespace boost::math;
+
+// Print header:
+cout <<
+ "____________________________________\n"
+ "F test for equal standard deviations\n"
+ "____________________________________\n\n";
+cout << setprecision(5);
+cout << "Sample 1:\n";
+cout << setw(55) << left << "Number of Observations" << "= " << N1 << "\n";
+cout << setw(55) << left << "Sample Standard Deviation" << "= " << sd1 << "\n\n";
+cout << "Sample 2:\n";
+cout << setw(55) << left << "Number of Observations" << "= " << N2 << "\n";
+cout << setw(55) << left << "Sample Standard Deviation" << "= " << sd2 << "\n\n";
+</pre>
+
+ The test statistic for an F-test is simply the ratio of the square of
+ the two standard deviations:
+ 
+
+ F = s12 / s22
+ 
+
+ where s1 is the standard deviation of the first sample and s2
+is the standard
+ deviation of the second sample. Or in code:
+ 
+<pre class="programlisting">
+double F = (sd1 / sd2);
+F *= F;
+cout << setw(55) << left << "Test Statistic" << "= " << F << "\n\n";
+</pre>
+
+ 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:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Hypothesis
+ 
+ </th>
+<th>
+ 
+ Test
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ The null-hypothesis: there is no difference in standard deviations
+ (two sided test)
+ 
+ </td>
+<td>
+ 
+ Reject if F <= F(1-alpha/2; N1-1, N2-1) or F >= F(alpha/2;
+ N1-1, N2-1)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ The alternative hypothesis: there is a difference in means (two
+ sided test)
+ 
+ </td>
+<td>
+ 
+ Reject if F(1-alpha/2; N1-1, N2-1) <= F <= F(alpha/2; N1-1,
+ N2-1)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ The alternative hypothesis: Standard deviation of sample 1 is
+ greater than that of sample 2
+ 
+ </td>
+<td>
+ 
+ Reject if F < F(alpha; N1-1, N2-1)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ The alternative hypothesis: Standard deviation of sample 1 is
+ less than that of sample 2
+ 
+ </td>
+<td>
+ 
+ Reject if F > F(1-alpha; N1-1, N2-1)
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+
+ Where F(1-alpha; N1-1, N2-1) is the lower critical value of the F distribution
+ with degrees of freedom N1-1 and N2-1, and F(alpha; N1-1, N2-1) is the
+ upper critical value of the F distribution with degrees of freedom N1-1
+ and N2-1.
+ 
+
+ The upper and lower critical values can be computed using the quantile
+ function:
+ 
+
+ F(1-alpha; N1-1, N2-1) = <code class="computeroutput">quantile(fisher_f(N1-1,
+ N2-1), alpha)</code>
+ 
+
+ F(alpha; N1-1, N2-1) = <code class="computeroutput">quantile(complement(fisher_f(N1-1,
+ N2-1), alpha))</code>
+ 
+
+ In our example program we need both upper and lower critical values for
+ alpha and for alpha/2:
+ 
+<pre class="programlisting">
+double ucv = quantile(complement(dist, alpha));
+double ucv2 = quantile(complement(dist, alpha / 2));
+double lcv = quantile(dist, alpha);
+double lcv2 = quantile(dist, alpha / 2);
+cout << setw(55) << left << "Upper Critical Value at alpha: " << "= "
+ << setprecision(3) << scientific << ucv << "\n";
+cout << setw(55) << left << "Upper Critical Value at alpha/2: " << "= "
+ << setprecision(3) << scientific << ucv2 << "\n";
+cout << setw(55) << left << "Lower Critical Value at alpha: " << "= "
+ << setprecision(3) << scientific << lcv << "\n";
+cout << setw(55) << left << "Lower Critical Value at alpha/2: " << "= "
+ << setprecision(3) << scientific << lcv2 << "\n\n";
+</pre>
+
+ The final step is to perform the comparisons given above, and print out
+ whether the hypothesis is rejected or not:
+ 
+<pre class="programlisting">
+cout << setw(55) << left <<
+ "Results for Alternative Hypothesis and alpha" << "= "
+ << setprecision(4) << fixed << alpha << "\n\n";
+cout << "Alternative Hypothesis Conclusion\n";
+
+cout << "Standard deviations are unequal (two sided test) ";
+if((ucv2 < F) || (lcv2 > F))
+ cout << "ACCEPTED\n";
+else
+ cout << "REJECTED\n";
+
+cout << "Standard deviation 1 is less than standard deviation 2 ";
+if(lcv > F)
+ cout << "ACCEPTED\n";
+else
+ cout << "REJECTED\n";
+
+cout << "Standard deviation 1 is greater than standard deviation 2 ";
+if(ucv < F)
+ cout << "ACCEPTED\n";
+else
+ cout << "REJECTED\n";
+cout << endl << endl;
+</pre>
+
+ Using the ceramic strength data as an example we get the following output:
+ 
+<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>
+
+ In this case we are unable to reject the null-hypothesis, and must instead
+ reject the alternative hypothesis.
+ 
+
+ 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).
+ 
+<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>
+
+ 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 alpha (a one sided test) with
+ the test statistic, and since 3.35 < 3.6 this hypothesis must be rejected.
+ We therefore conclude that there is a change for the better in our standard
+ deviation.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="find_eg/find_location_eg.html">
+ Find Location (Mean) Example</a></dt>
+<dt><a href="find_eg/find_scale_eg.html">
+ Find Scale (Standard Deviation) Example</a></dt>
+<dt><a href="find_eg/find_mean_and_sd_eg.html">
+ Find mean and standard deviation example</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 
+
+ First we need some includes to access the normal distribution, the
+ algorithms to find location (and some std output of course).
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/normal.hpp> // for normal_distribution
+ using boost::math::normal; // typedef provides default type is double.
+#include <boost/math/distributions/cauchy.hpp> // for cauchy_distribution
+ using boost::math::cauchy; // typedef provides default type is double.
+#include <boost/math/distributions/find_location.hpp>
+ using boost::math::find_location;
+ using boost::math::complement; // Needed if you want to use the complement version.
+ using boost::math::policies::policy;
+
+#include <iostream>
+ using std::cout; using std::endl;
+#include <iomanip>
+ using std::setw; using std::setprecision;
+#include <limits>
+ using std::numeric_limits;
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+normal N01; // Default 'standard' normal distribution with zero mean and
+double sd = 1.; // normal default standard deviation is 1.</pre>
+
+ 
+
+ 
+
+ 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).
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double z = -2.; // z to give prob p
+double p = 0.001; // only 0.1% below z
+
+cout << "Normal distribution with mean = " << N01.location()
+ << ", standard deviation " << N01.scale()
+ << ", has " << "fraction <= " << z
+ << ", p = " << cdf(N01, z) << endl;
+cout << "Normal distribution with mean = " << N01.location()
+ << ", standard deviation " << N01.scale()
+ << ", has " << "fraction > " << z
+ << ", p = " << cdf(complement(N01, z)) << endl; // Note: uses complement.</pre>
+
+ 
+
+
+
+<pre class="programlisting">Normal distribution with mean = 0, standard deviation 1, has fraction <= -2, p = 0.0227501
+Normal distribution with mean = 0, standard deviation 1, has fraction > -2, p = 0.97725
+</pre>
+
+ 
+
+ We can now use ''find_location'' to give a new offset mean.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double l = find_location<normal>(z, p, sd);
+cout << "offset location (mean) = " << l << endl;</pre>
+
+ 
+
+ 
+
+ that outputs:
+ 
+
+
+
+<pre class="programlisting">offset location (mean) = 1.09023
+</pre>
+
+ 
+
+ showing that we need to shift the mean just over one standard deviation
+ from its previous value of zero.
+ 
+
+ 
+
+ Then we can check that we have achieved our objective by constructing
+ a new distribution with the offset mean (but same standard deviation):
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+normal np001pc(l, sd); // Same standard_deviation (scale) but with mean (location) shifted.</pre>
+
+ 
+
+ 
+
+ And re-calculating the fraction below our chosen limit.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Normal distribution with mean = " << l
+ << " has " << "fraction <= " << z
+ << ", p = " << cdf(np001pc, z) << endl;
+ cout << "Normal distribution with mean = " << l
+ << " has " << "fraction > " << z
+ << ", p = " << cdf(complement(np001pc, z)) << endl;</pre>
+
+ 
+
+
+
+<pre class="programlisting">Normal distribution with mean = 1.09023 has fraction <= -2, p = 0.001
+Normal distribution with mean = 1.09023 has fraction > -2, p = 0.999
+</pre>
+
+ <a name="math_toolkit.dist.stat_tut.weg.find_eg.find_location_eg.controlling_error_handling_from_find_location"></a>
+ 
+<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>
+
+ 
+
+ 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).
+ 
+
+ 
+
+ Unless we are using the boost::math namespace, we will need:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+using boost::math::policies::policy;
+using boost::math::policies::domain_error;
+using boost::math::policies::ignore_error;</pre>
+
+ 
+
+ 
+
+ Using a typedef is often convenient, especially if it is re-used,
+ although it is not required, as the various examples below show.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+typedef policy<domain_error<ignore_error> > ignore_domain_policy;
+// find_location with new policy, using typedef.
+l = find_location<normal>(z, p, sd, ignore_domain_policy());
+// Default policy policy<>, needs "using boost::math::policies::policy;"
+l = find_location<normal>(z, p, sd, policy<>());
+// Default policy, fully specified.
+l = find_location<normal>(z, p, sd, boost::math::policies::policy<>());
+// A new policy, ignoring domain errors, without using a typedef.
+l = find_location<normal>(z, p, sd, policy<domain_error<ignore_error> >());</pre>
+
+ 
+
+ 
+
+ 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">find_location<normal>(z, 1 - p, sd)</code>,
+ but, to avoid loss of accuracy,
+ use the complement version.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+z = 2.;
+double q = 0.95; // = 1 - p; // complement.
+l = find_location<normal>(complement(z, q, sd));
+
+normal np95pc(l, sd); // Same standard_deviation (scale) but with mean(location) shifted
+cout << "Normal distribution with mean = " << l << " has "
+ << "fraction <= " << z << " = " << cdf(np95pc, z) << endl;
+cout << "Normal distribution with mean = " << l << " has "
+ << "fraction > " << z << " = " << cdf(complement(np95pc, z)) << endl;
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ See find_location_example.cpp
+ for full source code: the program output looks like this:
+
+<pre class="programlisting">Example: Find location (mean).
+Normal distribution with mean = 0, standard deviation 1, has fraction <= -2, p = 0.0227501
+Normal distribution with mean = 0, standard deviation 1, has fraction > -2, p = 0.97725
+offset location (mean) = 1.09023
+Normal distribution with mean = 1.09023 has fraction <= -2, p = 0.001
+Normal distribution with mean = 1.09023 has fraction > -2, p = 0.999
+Normal distribution with mean = 0.355146 has fraction <= 2 = 0.95
+Normal distribution with mean = 0.355146 has fraction > 2 = 0.05
+</pre>
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 
+
+ First we need some includes to access the normal distribution, the
+ algorithms to find location and scale (and some std output of course).
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/normal.hpp> // for normal_distribution
+ using boost::math::normal; // typedef provides default type is double.
+#include <boost/math/distributions/cauchy.hpp> // for cauchy_distribution
+ using boost::math::cauchy; // typedef provides default type is double.
+#include <boost/math/distributions/find_location.hpp>
+ using boost::math::find_location;
+#include <boost/math/distributions/find_scale.hpp>
+ using boost::math::find_scale;
+ using boost::math::complement;
+ using boost::math::policies::policy;
+
+#include <iostream>
+ using std::cout; using std::endl; using std::left; using std::showpoint; using std::noshowpoint;
+#include <iomanip>
+ using std::setw; using std::setprecision;
+#include <limits>
+ using std::numeric_limits;
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ <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>
+ 
+<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>
+
+ 
+
+ Consider an example from K Krishnamoorthy, Handbook of Statistical
+ Distributions with Applications, ISBN 1-58488-635-8, (2006) p 126,
+ example 10.3.7.
+ 
+
+ 
+
+ "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."
+ 
+
+ 
+
+ We start by constructing a normal distribution with the given parameters:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double mean = 3.; // kg
+double standard_deviation = 0.1; // kg
+normal packs(mean, standard_deviation);</pre>
+
+ 
+
+ 
+
+ We can then find the fraction (or %) of packages that weigh more
+ than 3.1 kg.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double max_weight = 3.1; // kg
+cout << "Percentage of packs > " << max_weight << " is "
+<< cdf(complement(packs, max_weight)) * 100. << endl; // P(X > 3.1)</pre>
+
+ 
+
+ 
+
+ 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 <
+ 2.9) = 0.05.
+ 
+
+ 
+
+ Using the mean of 3 kg, we can estimate the fraction of packs that
+ fail to meet the specification of 2.9 kg.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double minimum_weight = 2.9;
+cout <<"Fraction of packs <= " << minimum_weight << " with a mean of " << mean
+ << " is " << cdf(complement(packs, minimum_weight)) << endl;
+// fraction of packs <= 2.9 with a mean of 3 is 0.841345</pre>
+
+ 
+
+ 
+
+ 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?
+ 
+
+ 
+
+ Using the KK StatCalc program supplied with the book and the method
+ given on page 126 gives 3.06449.
+ 
+
+ 
+
+ We can confirm this by constructing a new distribution which we call
+ 'xpacks' with a safety margin mean of 3.06449 thus:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double over_mean = 3.06449;
+normal xpacks(over_mean, standard_deviation);
+cout << "Fraction of packs >= " << minimum_weight
+<< " with a mean of " << xpacks.mean()
+ << " is " << cdf(complement(xpacks, minimum_weight)) << endl;
+// fraction of packs >= 2.9 with a mean of 3.06449 is 0.950005</pre>
+
+ 
+
+ 
+
+ Using this Math Toolkit, we can calculate the required mean directly
+ thus:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double under_fraction = 0.05; // so 95% are above the minimum weight mean - sd = 2.9
+double low_limit = standard_deviation;
+double offset = mean - low_limit - quantile(packs, under_fraction);
+double nominal_mean = mean + offset;
+// mean + (mean - low_limit - quantile(packs, under_fraction));
+
+normal nominal_packs(nominal_mean, standard_deviation);
+cout << "Setting the packer to " << nominal_mean << " will mean that "
+ << "fraction of packs >= " << minimum_weight
+ << " is " << cdf(complement(nominal_packs, minimum_weight)) << endl;
+// Setting the packer to 3.06449 will mean that fraction of packs >= 2.9 is 0.95</pre>
+
+ 
+
+ 
+
+ This calculation is generalized as the free function called find_location.
+ 
+
+ 
+
+ To use this we will need to
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/find_location.hpp>
+ using boost::math::find_location;</pre>
+
+ 
+
+ 
+
+ and then use find_location function to find safe_mean, & construct
+ a new normal distribution called 'goodpacks'.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double safe_mean = find_location<normal>(minimum_weight, under_fraction, standard_deviation);
+normal good_packs(safe_mean, standard_deviation);</pre>
+
+ 
+
+ 
+
+ with the same confirmation as before:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Setting the packer to " << nominal_mean << " will mean that "
+ << "fraction of packs >= " << minimum_weight
+ << " is " << cdf(complement(good_packs, minimum_weight)) << endl;
+// Setting the packer to 3.06449 will mean that fraction of packs >= 2.9 is 0.95</pre>
+
+ 
+
+ <a name="math_toolkit.dist.stat_tut.weg.find_eg.find_mean_and_sd_eg.using_cauchy_lorentz_instead_of_normal_distribution"></a>
+ 
+<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>
+
+ 
+
+ 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.
+ 
+
+ 
+
+ This might happen because a larger than normal lump of meat is either
+ included or excluded.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cauchy cpacks(mean, standard_deviation);
+cout << "Cauchy Setting the packer to " << mean << " will mean that "
+ << "fraction of packs >= " << minimum_weight
+ << " is " << cdf(complement(cpacks, minimum_weight)) << endl;
+// Cauchy Setting the packer to 3 will mean that fraction of packs >= 2.9 is 0.75</pre>
+
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double lc = find_location<cauchy>(minimum_weight, under_fraction, standard_deviation);
+cout << "find_location<cauchy>(minimum_weight, over fraction, standard_deviation); " << lc << endl;
+// find_location<cauchy>(minimum_weight, over fraction, packs.standard_deviation()); 3.53138</pre>
+
+ 
+
+ 
+
+ Note that the safe_mean setting needs to be much higher, 3.53138
+ instead of 3.06449, so we will make rather less profit.
+ 
+
+ 
+
+ And again confirm that the fraction meeting specification is as expected.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cauchy goodcpacks(lc, standard_deviation);
+cout << "Cauchy Setting the packer to " << lc << " will mean that "
+ << "fraction of packs >= " << minimum_weight
+ << " is " << cdf(complement(goodcpacks, minimum_weight)) << endl;
+// Cauchy Setting the packer to 3.53138 will mean that fraction of packs >= 2.9 is 0.95</pre>
+
+ 
+
+ 
+
+ Finally we could estimate the effect of a much tighter specification,
+ that 99% of packs met the specification.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Cauchy Setting the packer to "
+ << find_location<cauchy>(minimum_weight, 0.99, standard_deviation)
+ << " will mean that "
+ << "fraction of packs >= " << minimum_weight
+ << " is " << cdf(complement(goodcpacks, minimum_weight)) << endl;</pre>
+
+ 
+
+ 
+
+ Setting the packer to 3.13263 will mean that fraction of packs >=
+ 2.9 is 0.99, but will more than double the mean loss from 0.0644
+ to 0.133 kg per pack.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ For other applications, where it is more difficult or expensive to
+ make many observations, the confidence intervals are depressingly
+ wide.
+ 
+
+ 
+
+ 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.
+ 
+
+ <a name="math_toolkit.dist.stat_tut.weg.find_eg.find_mean_and_sd_eg.changing_the_scale_or_standard_deviation"></a>
+ 
+<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>
+
+ 
+
+ Alternatively, we could invest in a better (more precise) packer
+ (or measuring device) with a lower standard deviation, or scale.
+ 
+
+ 
+
+ This might cost more, but would reduce the amount we have to 'give
+ away' in order to meet the specification.
+ 
+
+ 
+
+ 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
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double p = 0.05; // wanted p th quantile.
+cout << "Quantile of " << p << " = " << quantile(packs, p)
+ << ", mean = " << packs.mean() << ", sd = " << packs.standard_deviation() << endl;</pre>
+
+ 
+
+ 
+
+ Quantile of 0.05 = 2.83551, mean = 3, sd = 0.1
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Let's start by guessing that it (now 0.1) needs to be halved, to
+ a standard deviation of 0.05 kg.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+normal pack05(mean, 0.05);
+cout << "Quantile of " << p << " = " << quantile(pack05, p)
+ << ", mean = " << pack05.mean() << ", sd = " << pack05.standard_deviation() << endl;
+// Quantile of 0.05 = 2.91776, mean = 3, sd = 0.05
+
+cout <<"Fraction of packs >= " << minimum_weight << " with a mean of " << mean
+ << " and standard deviation of " << pack05.standard_deviation()
+ << " is " << cdf(complement(pack05, minimum_weight)) << endl;
+// Fraction of packs >= 2.9 with a mean of 3 and standard deviation of 0.05 is 0.97725</pre>
+
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+normal pack06(mean, 0.06);
+cout << "Quantile of " << p << " = " << quantile(pack06, p)
+ << ", mean = " << pack06.mean() << ", sd = " << pack06.standard_deviation() << endl;
+// Quantile of 0.05 = 2.90131, mean = 3, sd = 0.06
+
+cout <<"Fraction of packs >= " << minimum_weight << " with a mean of " << mean
+ << " and standard deviation of " << pack06.standard_deviation()
+ << " is " << cdf(complement(pack06, minimum_weight)) << endl;
+// Fraction of packs >= 2.9 with a mean of 3 and standard deviation of 0.06 is 0.95221</pre>
+
+ 
+
+ 
+
+ 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>.
+ 
+
+ 
+
+ But in this (normal) distribution case, we can and should be even
+ smarter and make a direct calculation.
+ 
+
+ 
+
+ 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).
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Rearranging, we can directly calculate the required standard deviation:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+normal N01; // standard normal distribution with meamn zero and unit standard deviation.
+p = 0.05;
+double qp = quantile(N01, p);
+double sd95 = (minimum_weight - mean) / qp;
+
+cout << "For the "<< p << "th quantile to be located at "
+ << minimum_weight << ", would need a standard deviation of " << sd95 << endl;
+// For the 0.05th quantile to be located at 2.9, would need a standard deviation of 0.0607957</pre>
+
+ 
+
+ 
+
+ We can now construct a new (normal) distribution pack95 for the 'better'
+ packer, and check that our distribution will meet the specification.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+normal pack95(mean, sd95);
+cout <<"Fraction of packs >= " << minimum_weight << " with a mean of " << mean
+ << " and standard deviation of " << pack95.standard_deviation()
+ << " is " << cdf(complement(pack95, minimum_weight)) << endl;
+// Fraction of packs >= 2.9 with a mean of 3 and standard deviation of 0.0607957 is 0.95</pre>
+
+ 
+
+ 
+
+ This calculation is generalized in the free function find_scale,
+ as shown below, giving the same standard deviation.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double ss = find_scale<normal>(minimum_weight, under_fraction, packs.mean());
+cout << "find_scale<normal>(minimum_weight, under_fraction, packs.mean()); " << ss << endl;
+// find_scale<normal>(minimum_weight, under_fraction, packs.mean()); 0.0607957</pre>
+
+ 
+
+ 
+
+ If we had defined an over_fraction, or percentage that must pass
+ specification
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double over_fraction = 0.95;</pre>
+
+ 
+
+ 
+
+ And (wrongly) written
+ 
+
+
+
+<pre class="programlisting">
+double sso = find_scale<normal>(minimum_weight, over_fraction, packs.mean());
+</pre>
+
+ 
+
+ With the default policy, we would get a message like
+ 
+
+
+
+<pre class="programlisting">Message from thrown exception was:
+ Error in function boost::math::find_scale<Dist, Policy>(double, double, double, Policy):
+ Computed scale (-0.060795683191176959) is <= 0! Was the complement intended?
+</pre>
+
+ 
+
+ But this would return a negative
+ standard deviation - obviously impossible. The probability should
+ be 1 - over_fraction, not over_fraction, thus:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double ss1o = find_scale<normal>(minimum_weight, 1 - over_fraction, packs.mean());
+cout << "find_scale<normal>(minimum_weight, under_fraction, packs.mean()); " << ss1o << endl;
+// find_scale<normal>(minimum_weight, under_fraction, packs.mean()); 0.0607957</pre>
+
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double ssc = find_scale<normal>(complement(minimum_weight, over_fraction, packs.mean()));
+cout << "find_scale<normal>(complement(minimum_weight, over_fraction, packs.mean())); " << ssc << endl;
+// find_scale<normal>(complement(minimum_weight, over_fraction, packs.mean())); 0.0607957</pre>
+
+ 
+
+ 
+
+ Note that our guess of 0.06 was close to the accurate value of 0.060795683191176959.
+ 
+
+ 
+
+ We can again confirm our prediction thus:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+normal pack95c(mean, ssc);
+cout <<"Fraction of packs >= " << minimum_weight << " with a mean of " << mean
+ << " and standard deviation of " << pack95c.standard_deviation()
+ << " is " << cdf(complement(pack95c, minimum_weight)) << endl;
+// Fraction of packs >= 2.9 with a mean of 3 and standard deviation of 0.0607957 is 0.95</pre>
+
+ 
+
+ 
+
+ Notice that these two deceptively simple questions:
+ 
+
+ 
+<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>
+
+ 
+
+ and/or
+ 
+
+ 
+<div class="itemizedlist"><ul type="disc"><li>
+ Do we measure better?
+ </li></ul></div>
+
+ 
+
+ are actually extremely common.
+ 
+
+ 
+
+ 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...
+ 
+
+ 
+
+ The scale can be variation in dispensing or uncertainty in measurement.
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ See find_mean_and_sd_normal.cpp
+ for full source code & appended program output.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 
+
+ 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).
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/normal.hpp> // for normal_distribution
+ using boost::math::normal; // typedef provides default type is double.
+#include <boost/math/distributions/find_scale.hpp>
+ using boost::math::find_scale;
+ using boost::math::complement; // Needed if you want to use the complement version.
+ using boost::math::policies::policy; // Needed to specify the error handling policy.
+
+#include <iostream>
+ using std::cout; using std::endl;
+#include <iomanip>
+ using std::setw; using std::setprecision;
+#include <limits>
+ using std::numeric_limits;
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+normal N01; // Default 'standard' normal distribution with zero mean
+double sd = 1.; // and standard deviation is 1.</pre>
+
+ 
+
+ 
+
+ 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).
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double z = -2.; // z to give prob p
+double p = 0.001; // only 0.1% below z = -2
+
+cout << "Normal distribution with mean = " << N01.location() // aka N01.mean()
+ << ", standard deviation " << N01.scale() // aka N01.standard_deviation()
+ << ", has " << "fraction <= " << z
+ << ", p = " << cdf(N01, z) << endl;
+cout << "Normal distribution with mean = " << N01.location()
+ << ", standard deviation " << N01.scale()
+ << ", has " << "fraction > " << z
+ << ", p = " << cdf(complement(N01, z)) << endl; // Note: uses complement.</pre>
+
+ 
+
+
+
+<pre class="programlisting">Normal distribution with mean = 0 has fraction <= -2, p = 0.0227501
+Normal distribution with mean = 0 has fraction > -2, p = 0.97725
+</pre>
+
+ 
+
+ Noting that p = 0.02 instead of our target of 0.001, we can now use
+ <code class="computeroutput">find_scale</code> to give
+ a new standard deviation.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double l = N01.location();
+double s = find_scale<normal>(z, p, l);
+cout << "scale (standard deviation) = " << s << endl;</pre>
+
+ 
+
+ 
+
+ that outputs:
+ 
+
+
+
+<pre class="programlisting">scale (standard deviation) = 0.647201
+</pre>
+
+ 
+
+ showing that we need to reduce the standard deviation from 1. to
+ 0.65.
+ 
+
+ 
+
+ Then we can check that we have achieved our objective by constructing
+ a new distribution with the new standard deviation (but same zero
+ mean):
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+normal np001pc(N01.location(), s);</pre>
+
+ 
+
+ 
+
+ And re-calculating the fraction below (and above) our chosen limit.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Normal distribution with mean = " << l
+ << " has " << "fraction <= " << z
+ << ", p = " << cdf(np001pc, z) << endl;
+cout << "Normal distribution with mean = " << l
+ << " has " << "fraction > " << z
+ << ", p = " << cdf(complement(np001pc, z)) << endl;</pre>
+
+ 
+
+
+
+<pre class="programlisting">Normal distribution with mean = 0 has fraction <= -2, p = 0.001
+Normal distribution with mean = 0 has fraction > -2, p = 0.999
+</pre>
+
+ <a name="math_toolkit.dist.stat_tut.weg.find_eg.find_scale_eg.controlling_how_errors_from_find_scale_are_handled"></a>
+ 
+<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>
+
+ 
+
+ 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).
+ 
+
+ 
+
+ Unless we are using the boost::math namespace, we will need:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+using boost::math::policies::policy;
+using boost::math::policies::domain_error;
+using boost::math::policies::ignore_error;</pre>
+
+ 
+
+ 
+
+ Using a typedef is convenient, especially if it is re-used, although
+ it is not required, as the various examples below show.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+typedef policy<domain_error<ignore_error> > ignore_domain_policy;
+// find_scale with new policy, using typedef.
+l = find_scale<normal>(z, p, l, ignore_domain_policy());
+// Default policy policy<>, needs using boost::math::policies::policy;
+
+l = find_scale<normal>(z, p, l, policy<>());
+// Default policy, fully specified.
+l = find_scale<normal>(z, p, l, boost::math::policies::policy<>());
+// New policy, without typedef.
+l = find_scale<normal>(z, p, l, policy<domain_error<ignore_error> >());</pre>
+
+ 
+
+ 
+
+ If we want to express a probability, say 0.999, that is a complement,
+ <code class="computeroutput">1 -
+ p</code> we should not even think
+ of writing <code class="computeroutput">find_scale<normal>(z, 1 - p, l)</code>, but instead,
+ use the complements version.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+z = -2.;
+double q = 0.999; // = 1 - p; // complement of 0.001.
+sd = find_scale<normal>(complement(z, q, l));
+
+normal np95pc(l, sd); // Same standard_deviation (scale) but with mean(scale) shifted
+cout << "Normal distribution with mean = " << l << " has "
+ << "fraction <= " << z << " = " << cdf(np95pc, z) << endl;
+cout << "Normal distribution with mean = " << l << " has "
+ << "fraction > " << z << " = " << cdf(complement(np95pc, z)) << endl;</pre>
+
+ 
+
+ 
+
+ Sadly, it is all too easy to get probabilities the wrong way round,
+ when you may get a warning like this:
+ 
+
+
+
+<pre class="programlisting">Message from thrown exception was:
+ Error in function boost::math::find_scale<Dist, Policy>(complement(double, double, double, Policy)):
+ Computed scale (-0.48043523852179076) is <= 0! Was the complement intended?
+</pre>
+
+ 
+
+ 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. 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ See find_scale_example.cpp
+ for full source code: the program output looks like this:
+
+<pre class="programlisting">Example: Find scale (standard deviation).
+Normal distribution with mean = 0, standard deviation 1, has fraction <= -2, p = 0.0227501
+Normal distribution with mean = 0, standard deviation 1, has fraction > -2, p = 0.97725
+scale (standard deviation) = 0.647201
+Normal distribution with mean = 0 has fraction <= -2, p = 0.001
+Normal distribution with mean = 0 has fraction > -2, p = 0.999
+Normal distribution with mean = 0.946339 has fraction <= -2 = 0.001
+Normal distribution with mean = 0.946339 has fraction > -2 = 0.999
+</pre>
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ If so, you may find 'Distributions as Objects' unfamiliar, if not alien.
+ 
+
+ However, do not panic, both definition
+ and usage are not really very different.
+ 
+
+ 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).
+ 
+
+ The <a href="http://www.nag.co.uk/numeric/cl/manual/pdf/G01/g01bjc.pdf" target="_top">NAG
+ function specification</a> is
+ 
+<pre class="programlisting">
+void nag_binomial_dist(Integer n, double p, Integer k,
+double *plek, double *pgtk, double *peqk, NagError *fail)
+</pre>
+
+ and is called
+ 
+<pre class="programlisting">
+g01bjc(n, p, k, &plek, &pgtk, &peqk, NAGERR_DEFAULT);
+</pre>
+
+ The equivalent using this Boost C++ library is:
+ 
+<pre class="programlisting">
+using namespace boost::math; // Using declaration avoids very long names.
+binomial my_dist(4, 0.5); // c.f. NAG n = 4, p = 0.5
+</pre>
+
+ and values can be output thus:
+ 
+<pre class="programlisting">
+cout
+ << my_dist.trials() << " " // Echo the NAG input n = 4 trials.
+ << my_dist.success_fraction() << " " // Echo the NAG input p = 0.5
+ << cdf(my_dist, 2) << " " // NAG plek with k = 2
+ << cdf(complement(my_dist, 2)) << " " // NAG pgtk with k = 2
+ << pdf(my_dist, 2) << endl; // NAG peqk with k = 2
+</pre>
+
+ <code class="computeroutput">cdf(dist, k)</code>
+ is equivalent to NAG library <code class="computeroutput">plek</code>,
+ lower tail probability of <= k
+ 
+
+ <code class="computeroutput">cdf(complement(dist, k))</code>
+ is equivalent to NAG library <code class="computeroutput">pgtk</code>,
+ upper tail probability of > k
+ 
+
+ <code class="computeroutput">pdf(dist, k)</code>
+ is equivalent to NAG library <code class="computeroutput">peqk</code>,
+ point probability of == k
+ 
+
+ See binomial_example_nag.cpp
+ for details.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="neg_binom_eg/neg_binom_conf.html">
+ Calculating Confidence Limits on the Frequency of Occurrence for the
+ Negative Binomial Distribution</a></dt>
+<dt><a href="neg_binom_eg/neg_binom_size_eg.html">
+ Estimating Sample Sizes for the Negative Binomial.</a></dt>
+<dt><a href="neg_binom_eg/negative_binomial_example1.html">
+ Negative Binomial Sales Quota Example.</a></dt>
+<dt><a href="neg_binom_eg/negative_binomial_example2.html">
+ Negative Binomial Table Printing Example.</a></dt>
+</dl></div>
+
+ (See also the reference documentation for the <a href="../../dist_ref/dists/negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
+ Binomial Distribution</a>.)
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ If, by experiment, you want to measure the the best estimate of success
+ fraction is given simply by k / N,
+ for k successes out of N
+ 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">negative_binomial_distribution<>::find_lower_bound_on_p</code>
+ and <code class="computeroutput">negative_binomial_distribution<>::find_upper_bound_on_p</code>
+ allow you to calculate the confidence intervals for your estimate of
+ the success fraction.
+ 
+
+ The sample program neg_binom_confidence_limits.cpp
+ illustrates their use.
+ 
+
+ 
+
+ First we need some includes to access the negative binomial distribution
+ (and some basic std output of course).
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/negative_binomial.hpp>
+using boost::math::negative_binomial;
+
+#include <iostream>
+using std::cout; using std::endl;
+#include <iomanip>
+using std::setprecision;
+using std::setw; using std::left; using std::fixed; using std::right;</pre>
+
+ 
+
+ 
+
+ First define a table of significance levels: these are the probabilities
+ that the true occurrence frequency lies outside the calculated interval:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };</pre>
+
+ 
+
+ 
+
+ Confidence value as % is (1 - alpha) * 100, so alpha 0.05 == 95%
+ confidence that the true occurence frequency lies inside
+ the calculated interval.
+ 
+
+ 
+
+ We need a function to calculate and print confidence limits for an
+ observed frequency of occurrence that follows a negative binomial
+ distribution.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+void confidence_limits_on_frequency(unsigned trials, unsigned successes)
+{
+ // trials = Total number of trials.
+ // successes = Total number of observed successes.
+ // failures = trials - successes.
+ // success_fraction = successes /trials.
+ // Print out general info:
+ cout <<
+ "______________________________________________\n"
+ "2-Sided Confidence Limits For Success Fraction\n"
+ "______________________________________________\n\n";
+ cout << setprecision(7);
+ cout << setw(40) << left << "Number of trials" << " = " << trials << "\n";
+ cout << setw(40) << left << "Number of successes" << " = " << successes << "\n";
+ cout << setw(40) << left << "Number of failures" << " = " << trials - successes << "\n";
+ cout << setw(40) << left << "Observed frequency of occurrence" << " = " << double(successes) / trials << "\n";
+
+ // Print table header:
+ cout << "\n\n"
+ "___________________________________________\n"
+ "Confidence Lower Upper\n"
+ " Value (%) Limit Limit\n"
+ "___________________________________________\n";</pre>
+
+ 
+
+ 
+
+ And now for the important part - the bounds themselves. For each
+ value of alpha, we call <code class="computeroutput">find_lower_bound_on_p</code>
+ and <code class="computeroutput">find_upper_bound_on_p</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: "Calculate a lower bound so that we are P%
+ sure that the true occurrence frequency is greater than some value"
+ then we would not have divided by
+ two.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+ // Now print out the upper and lower limits for the alpha table values.
+ for(unsigned i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
+ {
+ // Confidence value:
+ cout << fixed << setprecision(3) << setw(10) << right << 100 * (1-alpha[i]);
+ // Calculate bounds:
+ double lower = negative_binomial::find_lower_bound_on_p(trials, successes, alpha[i]/2);
+ double upper = negative_binomial::find_upper_bound_on_p(trials, successes, alpha[i]/2);
+ // Print limits:
+ cout << fixed << setprecision(5) << setw(15) << right << lower;
+ cout << fixed << setprecision(5) << setw(15) << right << upper << endl;
+ }
+ cout << endl;
+} // void confidence_limits_on_frequency(unsigned trials, unsigned successes)</pre>
+
+ 
+
+ 
+
+ And then call confidence_limits_on_frequency with increasing numbers
+ of trials, but always the same success fraction 0.1, or 1 in 10.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+int main()
+{
+ confidence_limits_on_frequency(20, 2); // 20 trials, 2 successes, 2 in 20, = 1 in 10 = 0.1 success fraction.
+ confidence_limits_on_frequency(200, 20); // More trials, but same 0.1 success fraction.
+ confidence_limits_on_frequency(2000, 200); // Many more trials, but same 0.1 success fraction.
+
+ return 0;
+} // int main()
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ Let's see some sample output for a 1 in 10 success ratio, first for
+ a mere 20 trials:
+ 
+<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>
+
+ 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.
+ 
+
+ Compare that with the program output for a mass 2000 trials:
+ 
+<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>
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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">negative_binomial_distibution<>::find_minimum_number_of_trials</code>
+ can be used to estimate the minimum number of trials required to be
+ P% sure of observing the desired number of failures.
+ 
+
+ The example program neg_binomial_sample_sizes.cpp
+ demonstrates its usage.
+ 
+
+ 
+
+ It centres around a routine that prints out a table of minimum sample
+ sizes for various probability thresholds:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+void find_number_of_trials(double failures, double p);</pre>
+
+ 
+
+ 
+
+ First define a table of significance levels: these are the maximum
+ acceptable probability that failure or fewer
+ events will be observed.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };</pre>
+
+ 
+
+ 
+
+ Confidence value as % is (1 - alpha) * 100, so alpha 0.05 == 95%
+ confidence that the desired number of failures will be observed.
+ 
+
+ 
+
+ 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:
+ 
+
+
+
+<pre class="programlisting">
+(int)ceil(negative_binomial::find_minimum_number_of_trials(failures, p, alpha[i]);
+</pre>
+
+ 
+
+ find_minimum_number_of_trials returns a double, so ceil rounds this
+ up to ensure we have an integral minimum number of trials.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+
+void find_number_of_trials(double failures, double p)
+{
+ // trials = number of trials
+ // failures = number of failures before achieving required success(es).
+ // p = success fraction (0 <= p <= 1.).
+ //
+ // Calculate how many trials we need to ensure the
+ // required number of failures DOES exceed "failures".
+
+ cout << "\n""Target number of failures = " << failures;
+ cout << ", Success fraction = " << 100 * p << "%" << endl;
+ // Print table header:
+ cout << "\n\n"
+ "____________________________\n"
+ "Confidence Min Number\n"
+ " Value (%) Of Trials \n"
+ "____________________________\n";
+ // Now print out the data for the alpha table values.
+ for(unsigned i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
+ { // Confidence values %:
+ cout << fixed << setprecision(3) << setw(10) << right << 100 * (1-alpha[i]) << " "
+ // find_minimum_number_of_trials
+ << setw(6) << right
+ << (int)ceil(negative_binomial::find_minimum_number_of_trials(failures, p, alpha[i]))
+ << endl;
+ }
+ cout << endl;
+} // void find_number_of_trials(double failures, double p)</pre>
+
+ 
+
+ 
+
+ finally we can produce some tables of minimum trials for the chosen
+ confidence levels:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+int main()
+{
+ find_number_of_trials(5, 0.5);
+ find_number_of_trials(50, 0.5);
+ find_number_of_trials(500, 0.5);
+ find_number_of_trials(50, 0.1);
+ find_number_of_trials(500, 0.1);
+ find_number_of_trials(5, 0.9);
+
+ return 0;
+} // int main()
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">
+
+ Since we're calculating the minimum number of
+ trials required, we'll err on the safe side and take the ceiling
+ of the result. Had we been calculating the maximum
+ number of trials permitted to observe less than a certain number
+ of failures then we would have taken the floor
+ instead. We would also have called <code class="computeroutput">find_minimum_number_of_trials</code>
+ like this:
+
+<pre class="programlisting">
+floor(negative_binomial::find_minimum_number_of_trials(failures, p, alpha[i]))
+</pre>
+
+ which would give us the largest number of trials we could conduct
+ and still be P% sure of observing failures or less
+ failure events, when the probability of success is p.
+ 
+</td></tr>
+</table></div>
+
+ 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:
+ 
+<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>
+
+ So 18 trials or more would yield a 95% chance that at least our 5 required
+ failures would be observed.
+ 
+
+ Compare that to what happens if the success ratio is 90%:
+ 
+<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>
+
+ So now 103 trials are required to observe at least 5 failures with
+ 95% certainty.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ 
+
+ 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>.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ What is the probability mass (density) function (pdf) for selling
+ the last (fifth) candy bar at the nth house?
+ 
+
+ 
+
+ 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>.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#define BOOST_MATH_OVERFLOW_ERROR_POLICY ignore_error
+#define BOOST_MATH_DISCRETE_QUANTILE_POLICY real</pre>
+
+ 
+
+ 
+
+ After that we need some includes to provide easy access to the negative
+ binomial distribution,
+ 
+
+ 
+<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">
+ It is vital to #include distributions etc after
+ the above #defines
+ </td></tr>
+</table></div>
+
+ 
+
+ and we need some std library iostream, of course.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/negative_binomial.hpp>
+ // for negative_binomial_distribution
+ using boost::math::negative_binomial; // typedef provides default type is double.
+ using ::boost::math::pdf; // Probability mass function.
+ using ::boost::math::cdf; // Cumulative density function.
+ using ::boost::math::quantile;
+
+#include <iostream>
+ using std::cout; using std::endl;
+ using std::noshowpoint; using std::fixed; using std::right; using std::left;
+#include <iomanip>
+ using std::setprecision; using std::setw;
+
+#include <limits>
+ using std::numeric_limits;
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ It is always sensible to use try and catch blocks because defaults
+ policies are to throw an exception if anything goes wrong.
+ 
+
+ 
+
+ A simple catch block (see below) will ensure that you get a helpful
+ error message instead of an abrupt program abort.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+try
+{</pre>
+
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double sales_quota = 5; // Pat's sales quota - successes (r).</pre>
+
+ 
+
+ 
+
+ At each house, there is a 0.4 probability (40%) of selling one candy
+ bar and a 0.6 probability (60%) of selling nothing.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double success_fraction = 0.4; // success_fraction (p) - so failure_fraction is 0.6.</pre>
+
+ 
+
+ 
+
+ 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).
+ 
+
+ 
+
+ We therefore start by constructing a negative binomial distribution
+ with parameters sales_quota (required successes) and probability
+ of success.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+negative_binomial nb(sales_quota, success_fraction); // type double by default.</pre>
+
+ 
+
+ 
+
+ To confirm, display the success_fraction & successes parameters
+ of the distribution.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Pat has a sales per house success rate of " << success_fraction
+ << ".\nTherefore he would, on average, sell " << nb.success_fraction() * 100
+ << " bars after trying 100 houses." << endl;
+
+int all_houses = 30; // The number of houses on the estate.
+
+cout << "With a success rate of " << nb.success_fraction()
+ << ", he might expect, on average,\n"
+ "to need to visit about " << success_fraction * all_houses
+ << " houses in order to sell all " << nb.successes() << " bars. " << endl;</pre>
+
+ 
+
+
+
+<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>
+
+ 
+
+ 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.
+ 
+
+ 
+
+ We calculate this using the pdf function:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability that Pat finishes on the " << sales_quota << "th house is "
+ << pdf(nb, 5 - sales_quota) << endl; // == pdf(nb, 0)</pre>
+
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ 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 exactly ( == ) on any house is the Probability
+ Density Function (pdf).
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability that Pat finishes on the 6th house is "
+ << pdf(nb, 6 - sales_quota) << endl;
+cout << "Probability that Pat finishes on the 7th house is "
+ << pdf(nb, 7 - sales_quota) << endl;
+cout << "Probability that Pat finishes on the 8th house is "
+ << pdf(nb, 8 - sales_quota) << endl;</pre>
+
+ 
+
+
+
+<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>
+
+ 
+
+ The sum of the probabilities for these houses is the Cumulative Distribution
+ Function (cdf). We can calculate it by adding the individual probabilities.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability that Pat finishes on or before the 8th house is sum "
+ "\n" << "pdf(sales_quota) + pdf(6) + pdf(7) + pdf(8) = "
+ // Sum each of the mass/density probabilities for houses sales_quota = 5, 6, 7, & 8.
+ << pdf(nb, 5 - sales_quota) // 0 failures.
+ + pdf(nb, 6 - sales_quota) // 1 failure.
+ + pdf(nb, 7 - sales_quota) // 2 failures.
+ + pdf(nb, 8 - sales_quota) // 3 failures.
+ << endl;</pre>
+
+ 
+
+
+
+<pre class="programlisting">pdf(sales_quota) + pdf(6) + pdf(7) + pdf(8) = 0.17367
+</pre>
+
+ 
+
+ Or, usually better, by using the negative binomial cumulative
+ distribution function.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "\nProbability of selling his quota of " << sales_quota
+ << " bars\non or before the " << 8 << "th house is "
+ << cdf(nb, 8 - sales_quota) << endl;</pre>
+
+ 
+
+
+
+<pre class="programlisting">Probability of selling his quota of 5 bars on or before the 8th house is 0.17367
+</pre>
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "\nProbability that Pat finishes exactly on the 10th house is "
+ << pdf(nb, 10 - sales_quota) << endl;
+cout << "\nProbability of selling his quota of " << sales_quota
+ << " bars\non or before the " << 10 << "th house is "
+ << cdf(nb, 10 - sales_quota) << endl;</pre>
+
+ 
+
+
+
+<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>
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability that Pat finishes exactly on the 11th house is "
+ << pdf(nb, 11 - sales_quota) << endl;
+cout << "\nProbability of selling his quota of " << sales_quota
+ << " bars\non or before the " << 11 << "th house is "
+ << cdf(nb, 11 - sales_quota) << endl;</pre>
+
+ 
+
+
+
+<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>
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability that Pat finishes exactly on the 12th house is "
+ << pdf(nb, 12 - sales_quota) << endl;
+
+cout << "\nProbability of selling his quota of " << sales_quota
+ << " bars\non or before the " << 12 << "th house is "
+ << cdf(nb, 12 - sales_quota) << endl;</pre>
+
+ 
+
+
+
+<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>
+
+ 
+
+ Finally consider the risk of Pat not selling his quota of 5 bars
+ even after visiting all the houses. Calculate the probability that
+ he will sell on or before the last house: Calculate
+ the probability that he would sell all his quota on the very last
+ house.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability that Pat finishes on the " << all_houses
+ << " house is " << pdf(nb, all_houses - sales_quota) << endl;</pre>
+
+ 
+
+ 
+
+ Probability of selling his quota of 5 bars on the 30th house is
+ 
+
+
+
+<pre class="programlisting">Probability that Pat finishes on the 30 house is 0.00069145
+</pre>
+
+ 
+
+ when he'd be very unlucky indeed!
+ 
+
+ 
+
+ What is the probability that Pat exhausts all 30 houses in the neighborhood,
+ and still doesn't sell the required
+ 5 candy bars?
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "\nProbability of selling his quota of " << sales_quota
+ << " bars\non or before the " << all_houses << "th house is "
+ << cdf(nb, all_houses - sales_quota) << endl;</pre>
+
+ 
+
+
+
+<pre class="programlisting">Probability of selling his quota of 5 bars
+on or before the 30th house is 0.99849
+</pre>
+
+ 
+
+ /*<code class="computeroutput">So the
+ risk of
+ failing even
+ after visiting
+ all the
+ houses is
+ 1 -
+ this probability, </code><code class="computeroutput">1
+ - cdf(nb, all_houses
+ - sales_quota</code><code class="computeroutput">
+ But using
+ this expression
+ may cause
+ serious inaccuracy, so
+ it would
+ be much
+ better to
+ use the
+ complement of
+ the cdf: So
+ the risk
+ of failing
+ even at, or after,
+ the 31th (non-existent)
+ houses is
+ 1 -
+ this probability, </code><code class="computeroutput">1
+ - cdf(nb, all_houses
+ - sales_quota)</code>` But using this expression may cause
+ serious inaccuracy. So it would be much better to use the complement
+ of the cdf. Why complements?
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "\nProbability of failing to sell his quota of " << sales_quota
+ << " bars\neven after visiting all " << all_houses << " houses is "
+ << cdf(complement(nb, all_houses - sales_quota)) << endl;</pre>
+
+ 
+
+
+
+<pre class="programlisting">Probability of failing to sell his quota of 5 bars
+even after visiting all 30 houses is 0.0015101
+</pre>
+
+ 
+
+ 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:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double p = cdf(nb, (8 - sales_quota));
+cout << "Probability of meeting sales quota on or before 8th house is "<< p << endl;</pre>
+
+ 
+
+
+
+<pre class="programlisting">Probability of meeting sales quota on or before 8th house is 0.174
+</pre>
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "If the confidence of meeting sales quota is " << p
+ << ", then the finishing house is " << quantile(nb, p) + sales_quota << endl;
+
+cout<< " quantile(nb, p) = " << quantile(nb, p) << endl;</pre>
+
+ 
+
+
+
+<pre class="programlisting">If the confidence of meeting sales quota is 0.17367, then the finishing house is 8
+</pre>
+
+ 
+
+ 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 certain
+ of selling his quota).
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "If the confidence of meeting sales quota is " << 1.
+ << ", then the finishing house is " << quantile(nb, 1) + sales_quota << endl;
+// 1.#INF == infinity.</pre>
+
+ 
+
+
+
+<pre class="programlisting">If the confidence of meeting sales quota is 1, then the finishing house is 1.#INF
+</pre>
+
+ 
+
+ And similarly for a few other probabilities:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "If the confidence of meeting sales quota is " << 0.
+ << ", then the finishing house is " << quantile(nb, 0.) + sales_quota << endl;
+
+cout << "If the confidence of meeting sales quota is " << 0.5
+ << ", then the finishing house is " << quantile(nb, 0.5) + sales_quota << endl;
+
+cout << "If the confidence of meeting sales quota is " << 1 - 0.00151 // 30 th
+ << ", then the finishing house is " << quantile(nb, 1 - 0.00151) + sales_quota << endl;</pre>
+
+ 
+
+
+
+<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>
+
+ 
+
+ Notice that because we chose a discrete quantile policy of real,
+ the result can be an 'unreal' fractional house.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "If confidence of meeting quota is zero\n(we assume all houses are successful sales)"
+ ", then finishing house is " << sales_quota << endl;</pre>
+
+ 
+
+
+
+<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>
+
+ 
+
+ We can list quantiles for a few probabilities:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+ double ps[] = {0., 0.001, 0.01, 0.05, 0.1, 0.5, 0.9, 0.95, 0.99, 0.999, 1.};
+ // Confidence as fraction = 1-alpha, as percent = 100 * (1-alpha[i]) %
+ cout.precision(3);
+ for (int i = 0; i < sizeof(ps)/sizeof(ps[0]); i++)
+ {
+ cout << "If confidence of meeting quota is " << ps[i]
+ << ", then finishing house is " << quantile(nb, ps[i]) + sales_quota
+ << endl;
+}</pre>
+
+ 
+
+
+
+<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>
+
+ 
+
+ We could have applied a ceil function to obtain a 'worst case' integer
+ value for house.
+
+<pre class="programlisting">
+ceil(quantile(nb, ps[i]))</pre>
+
+ 
+
+ 
+
+ Or, if we had used the default discrete quantile policy, integer_outside,
+ by omitting
+
+<pre class="programlisting">
+#define BOOST_MATH_DISCRETE_QUANTILE_POLICY real</pre>
+
+ we would have achieved the same effect.
+ 
+
+ 
+
+ The real result gives some suggestion which house is most likely.
+ For example, compare the real and integer_outside for 95% confidence.
+ 
+
+
+
+<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>
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Finally, we can tabulate the probability for the last sale being
+ exactly on each house.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "\nHouse for " << sales_quota << "th (last) sale. Probability (%)" << endl;
+cout.precision(5);
+for (int i = (int)sales_quota; i < all_houses+1; i++)
+{
+ cout << left << setw(3) << i << " " << setw(8) << cdf(nb, i - sales_quota) << endl;</spa
n>
+}
+cout << endl;</pre>
+
+ 
+
+
+
+<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>
+
+ 
+
+ As noted above, using a catch block is always a good idea, even if
+ you do not expect to use it.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+}
+catch(const std::exception& e)
+{ // Since we have set an overflow policy of ignore_error,
+ // an overflow exception should never be thrown.
+ std::cout << "\nMessage from thrown exception was:\n " << e.what() << std::endl;</pre>
+
+ 
+
+ 
+
+ For example, without a ignore domain error policy, if we asked for
+
+
+<pre class="programlisting">
+pdf(nb, -1)</pre>
+
+ for example, we would get:
+ 
+
+
+
+<pre class="programlisting">Message from thrown exception was:
+ Error in function boost::math::pdf(const negative_binomial_distribution<double>&, double):
+ Number of failures argument is -1, but must be >= 0 !
+</pre>
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ Example program showing output of a table of values of cdf and pdf
+ for various k failures.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+// Print a table of values that can be used to plot
+// using Excel, or some other superior graphical display tool.
+
+cout.precision(17); // Use max_digits10 precision, the maximum available for a reference table.
+cout << showpoint << endl; // include trailing zeros.
+// This is a maximum possible precision for the type (here double) to suit a reference table.
+int maxk = static_cast<int>(2. * mynbdist.successes() / mynbdist.success_fraction());
+// This maxk shows most of the range of interest, probability about 0.0001 to 0.999.
+cout << "\n"" k pdf cdf""\n" << endl;
+for (int k = 0; k < maxk; k++)
+{
+ cout << right << setprecision(17) << showpoint
+ << right << setw(3) << k << ", "
+ << left << setw(25) << pdf(mynbdist, static_cast<double>(k))
+ << left << setw(25) << cdf(mynbdist, static_cast<double>(k))
+ << endl;
+}
+cout << endl;
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+k pdf cdf
+ 0, 1.5258789062500000e-005 1.5258789062500003e-005
+ 1, 9.1552734375000000e-005 0.00010681152343750000
+ 2, 0.00030899047851562522 0.00041580200195312500
+ 3, 0.00077247619628906272 0.0011882781982421875
+ 4, 0.0015932321548461918 0.0027815103530883789
+ 5, 0.0028678178787231476 0.0056493282318115234
+ 6, 0.0046602040529251142 0.010309532284736633
+ 7, 0.0069903060793876605 0.017299838364124298
+ 8, 0.0098301179241389001 0.027129956288263202
+ 9, 0.013106823898851871 0.040236780187115073
+10, 0.016711200471036140 0.056947980658151209
+11, 0.020509200578089786 0.077457181236241013
+12, 0.024354675686481652 0.10181185692272265
+13, 0.028101548869017230 0.12991340579173993
+14, 0.031614242477644432 0.16152764826938440
+15, 0.034775666725408917 0.19630331499479325
+16, 0.037492515688331451 0.23379583068312471
+17, 0.039697957787645101 0.27349378847076977
+18, 0.041352039362130305 0.31484582783290005
+19, 0.042440250924291580 0.35728607875719176
+20, 0.042970754060845245 0.40025683281803687
+21, 0.042970754060845225 0.44322758687888220
+22, 0.042482450037426581 0.48571003691630876
+23, 0.041558918514873783 0.52726895543118257
+24, 0.040260202311284021 0.56752915774246648
+25, 0.038649794218832620 0.60617895196129912
+26, 0.036791631035234917 0.64297058299653398
+27, 0.034747651533277427 0.67771823452981139
+28, 0.032575923312447595 0.71029415784225891
+29, 0.030329307911589130 0.74062346575384819
+30, 0.028054609818219924 0.76867807557206813
+31, 0.025792141284492545 0.79447021685656061
+32, 0.023575629142856460 0.81804584599941710
+33, 0.021432390129869489 0.83947823612928651
+34, 0.019383705779220189 0.85886194190850684
+35, 0.017445335201298231 0.87630727710980494
+36, 0.015628112784496322 0.89193538989430121
+37, 0.013938587078064250 0.90587397697236549
+38, 0.012379666154859701 0.91825364312722524
+39, 0.010951243136991251 0.92920488626421649
+40, 0.0096507830144735539 0.93885566927869002
+41, 0.0084738582566109364 0.94732952753530097
+42, 0.0074146259745345548 0.95474415350983555
+43, 0.0064662435824429246 0.96121039709227851
+44, 0.0056212231142827853 0.96683162020656122
+45, 0.0048717266990450708 0.97170334690560634
+46, 0.0042098073105878630 0.97591315421619418
+47, 0.0036275999165703964 0.97954075413276465
+48, 0.0031174686783026818 0.98265822281106729
+49, 0.0026721160099737302 0.98533033882104104
+50, 0.0022846591885275322 0.98761499800956853
+51, 0.0019486798960970148 0.98956367790566557
+52, 0.0016582516423517923 0.99122192954801736
+53, 0.0014079495076571762 0.99262987905567457
+54, 0.0011928461106539983 0.99382272516632852
+55, 0.0010084971662802015 0.99483122233260868
+56, 0.00085091948404891532 0.99568214181665760
+57, 0.00071656377604119542 0.99639870559269883
+58, 0.00060228420831048650 0.99700098980100937
+59, 0.00050530624256557675 0.99750629604357488
+60, 0.00042319397814867202 0.99792949002172360
+61, 0.00035381791615708398 0.99828330793788067
+62, 0.00029532382517950324 0.99857863176306016
+63, 0.00024610318764958566 0.99882473495070978
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="normal_example/normal_misc.html">
+ Some Miscellaneous Examples of the Normal (Gaussian) Distribution</a></dt></dl></div>
+
+ (See also the reference documentation for the <a href="../../dist_ref/dists/normal_dist.html" title="Normal (Gaussian) Distribution">Normal
+ Distribution</a>.)
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ The sample program normal_misc_examples.cpp
+ illustrates their use.
+ 
+<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>
+
+ 
+
+ First we need some includes to access the normal distribution (and
+ some std output of course).
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/normal.hpp> // for normal_distribution
+ using boost::math::normal; // typedef provides default type is double.
+
+#include <iostream>
+ using std::cout; using std::endl; using std::left; using std::showpoint; using std::noshowpoint;
+#include <iomanip>
+ using std::setw; using std::setprecision;
+#include <limits>
+ using std::numeric_limits;
+
+int main()
+{
+ cout << "Example: Normal distribution, Miscellaneous Applications.";
+
+ try
+ {
+ { // Traditional tables and values.</pre>
+
+ 
+
+ 
+
+ Let's start by printing some traditional tables.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double step = 1.; // in z
+double range = 4; // min and max z = -range to +range.
+int precision = 17; // traditional tables are only computed to much lower precision.
+
+// Construct a standard normal distribution s
+ normal s; // (default mean = zero, and standard deviation = unity)
+ cout << "Standard normal distribution, mean = "<< s.mean()
+ << ", standard deviation = " << s.standard_deviation() << endl;</pre>
+
+ 
+
+ 
+
+ First the probability distribution function (pdf).
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Probability distribution function values" << endl;
+cout << " z " " pdf " << endl;
+cout.precision(5);
+for (double z = -range; z < range + step; z += step)
+{
+ cout << left << setprecision(3) << setw(6) << z << " "
+ << setprecision(precision) << setw(12) << pdf(s, z) << endl;
+}
+cout.precision(6); // default</pre>
+
+ 
+
+ 
+
+ And the area under the normal curve from -∞ up to z, the cumulative
+ distribution function (cdf).
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+// For a standard normal distribution
+cout << "Standard normal mean = "<< s.mean()
+ << ", standard deviation = " << s.standard_deviation() << endl;
+cout << "Integral (area under the curve) from - infinity up to z " << endl;
+cout << " z " " cdf " << endl;
+for (double z = -range; z < range + step; z += step)
+{
+ cout << left << setprecision(3) << setw(6) << z << " "
+ << setprecision(precision) << setw(12) << cdf(s, z) << endl;
+}
+cout.precision(6); // default</pre>
+
+ 
+
+ 
+
+ And all this you can do with a nanoscopic amount of work compared
+ to the team of human computers 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>).
+ 
+
+ 
+
+ 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
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double z = 2.;
+cout << "Area for z = " << z << " is " << cdf(s, z) << endl; // to get the area for z.</pre>
+
+ 
+
+ 
+
+ 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
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+ cout << "95% of area has a z below " << quantile(s, 0.95) << endl;
+// 95% of area has a z below 1.64485</pre>
+
+ 
+
+ 
+
+ and a two-sided test (a comparison between two levels, rather than
+ a one-sided test)
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+ cout << "95% of area has a z between " << quantile(s, 0.975)
+ << " and " << -quantile(s, 0.975) << endl;
+// 95% of area has a z between 1.95996 and -1.95996</pre>
+
+ 
+
+ 
+
+ First, define a table of significance levels: these are the probabilities
+ that the true occurrence frequency lies outside the calculated interval.
+ 
+
+ 
+
+ 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,
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double alpha1 = cdf(s, -1) * 2; // 0.3173105078629142
+cout << setprecision(17) << "Significance level for z == 1 is " << alpha1 << endl;</pre>
+
+ 
+
+ 
+
+ and place in our array of favorite alpha values.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double alpha[] = {0.3173105078629142, // z for 1 standard deviation.
+ 0.20, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };</pre>
+
+ 
+
+ 
+
+ Confidence value as % is (1 - alpha) * 100 (so alpha 0.05 == 95%
+ confidence) that the true occurrence frequency lies inside
+ the calculated interval.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "level of significance (alpha)" << setprecision(4) << endl;
+cout << "2-sided 1 -sided z(alpha) " << endl;
+for (int i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
+{
+ cout << setw(15) << alpha[i] << setw(15) << alpha[i] /2 << setw(10) << quantile(complement(s, alpha[i]/2)) << endl;
+ // Use quantile(complement(s, alpha[i]/2)) to avoid potential loss of accuracy from quantile(s, 1 - alpha[i]/2)
+}
+cout << endl;</pre>
+
+ 
+
+ 
+
+ Notice the distinction between one-sided (also called one-tailed)
+ where we are using a > or <
+ test (and not both) and considering the area of the tail (integral)
+ from z up to +∞, and a two-sided test where we are using two >
+ and < tests, and thus considering
+ two tails, from -∞ up to z low and z high up to +∞.
+ 
+
+ 
+
+ So the 2-sided values alpha[i] are calculated using alpha[i]/2.
+ 
+
+ 
+
+ If we consider a simple example of alpha = 0.05, then for a two-sided
+ test, the lower tail area from -∞ 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,
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+<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>
+
+ 
+
+ 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.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout.precision(3);
+cout << showpoint << "cdf(s, s.standard_deviation()) = "
+ << cdf(s, s.standard_deviation()) << endl; // from -infinity to 1 sd
+cout << "cdf(complement(s, s.standard_deviation())) = "
+ << cdf(complement(s, s.standard_deviation())) << endl;
+cout << "Fraction 1 standard deviation within either side of mean is "
+ << 1 - cdf(complement(s, s.standard_deviation())) * 2 << endl;
+cout << "Fraction 2 standard deviations within either side of mean is "
+ << 1 - cdf(complement(s, 2 * s.standard_deviation())) * 2 << endl;
+cout << "Fraction 3 standard deviations within either side of mean is "
+ << 1 - cdf(complement(s, 3 * s.standard_deviation())) * 2 << endl;</pre>
+
+ 
+
+ 
+
+ To a useful precision, the 1, 2 & 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>:
+ 
+
+
+
+<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>
+
+ 
+
+ 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);
+ 
+
+
+
+<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>
+
+ 
+
+ But before you get too excited about this impressive precision, don't
+ forget that the confidence intervals of the
+ standard deviation are surprisingly wide, especially if
+ you have estimated the standard deviation from only a few measurements.
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+<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>
+
+ 
+
+ Examples from K. Krishnamoorthy, Handbook of Statistical Distributions
+ with Applications, ISBN 1 58488 635 8, page 125... implemented using
+ the Math Toolkit library.
+ 
+
+ 
+
+ A few very simple examples are shown here:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+// K. Krishnamoorthy, Handbook of Statistical Distributions with Applications,
+ // ISBN 1 58488 635 8, page 125, example 10.3.5</pre>
+
+ 
+
+ 
+
+ 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
+ bulbs with these values:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double mean_life = 1100.;
+double life_standard_deviation = 100.;
+normal bulbs(mean_life, life_standard_deviation);
+double expected_life = 1000.;</pre>
+
+ 
+
+ 
+
+ The we can use the Cumulative distribution function to predict fractions
+ (or percentages, if * 100) that will last various lifetimes.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+cout << "Fraction of bulbs that will last at best (<=) " // P(X <= 1000)
+ << expected_life << " is "<< cdf(bulbs, expected_life) << endl;
+cout << "Fraction of bulbs that will last at least (>) " // P(X > 1000)
+ << expected_life << " is "<< cdf(complement(bulbs, expected_life)) << endl;
+double min_life = 900;
+double max_life = 1200;
+cout << "Fraction of bulbs that will last between "
+ << min_life << " and " << max_life << " is "
+ << cdf(bulbs, max_life) // P(X <= 1200)
+ - cdf(bulbs, min_life) << endl; // P(X <= 900)</pre>
+
+ 
+
+ 
+<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">
+ 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.
+ </td></tr>
+</table></div>
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+<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>
+
+ 
+
+ Weekly demand for 5 lb sacks of onions at a store is normally distributed
+ with mean 140 sacks and standard deviation 10.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double mean = 140.; // sacks per week.
+double standard_deviation = 10;
+normal sacks(mean, standard_deviation);
+
+double stock = 160.; // per week.
+cout << "Percentage of weeks overstocked "
+ << cdf(sacks, stock) * 100. << endl; // P(X <=160)
+// Percentage of weeks overstocked 97.7</pre>
+
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double stock_95 = quantile(sacks, 0.95);
+cout << "Store should stock " << int(stock_95) << " sacks to meet 95% of demands." << endl;</pre>
+
+ 
+
+ 
+
+ And it is easy to estimate how to meet 80% of demand, and waste even
+ less.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double stock_80 = quantile(sacks, 0.80);
+cout << "Store should stock " << int(stock_80) << " sacks to meet 8 out of 10 demands." << endl;
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+<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>
+
+ 
+
+ 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.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double mean = 3.; // kg
+double standard_deviation = 0.1; // kg
+normal packs(mean, standard_deviation);
+
+double max_weight = 3.1; // kg
+cout << "Percentage of packs > " << max_weight << " is "
+<< cdf(complement(packs, max_weight)) << endl; // P(X > 3.1)
+
+double under_weight = 2.9;
+cout <<"fraction of packs <= " << under_weight << " with a mean of " << mean
+ << " is " << cdf(complement(packs, under_weight)) << endl;
+// fraction of packs <= 2.9 with a mean of 3 is 0.841345
+// This is 0.84 - more than the target 0.95
+// Want 95% to be over this weight, so what should we set the mean weight to be?
+// KK StatCalc says:
+double over_mean = 3.0664;
+normal xpacks(over_mean, standard_deviation);
+cout << "fraction of packs >= " << under_weight
+<< " with a mean of " << xpacks.mean()
+ << " is " << cdf(complement(xpacks, under_weight)) << endl;
+// fraction of packs >= 2.9 with a mean of 3.06449 is 0.950005
+double under_fraction = 0.05; // so 95% are above the minimum weight mean - sd = 2.9
+double low_limit = standard_deviation;
+double offset = mean - low_limit - quantile(packs, under_fraction);
+double nominal_mean = mean + offset;
+
+normal nominal_packs(nominal_mean, standard_deviation);
+cout << "Setting the packer to " << nominal_mean << " will mean that "
+ << "fraction of packs >= " << under_weight
+ << " is " << cdf(complement(nominal_packs, under_weight)) << endl;</pre>
+
+ 
+
+ 
+
+ Setting the packer to 3.06449 will mean that fraction of packs >=
+ 2.9 is 0.95.
+ 
+
+ 
+
+ Setting the packer to 3.13263 will mean that fraction of packs >=
+ 2.9 is 0.99, but will more than double the mean loss from 0.0644
+ to 0.133.
+ 
+
+ 
+
+ Alternatively, we could invest in a better (more precise) packer
+ with a lower standard deviation.
+ 
+
+ 
+
+ 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
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+double p = 0.05; // wanted p th quantile.
+cout << "Quantile of " << p << " = " << quantile(packs, p)
+ << ", mean = " << packs.mean() << ", sd = " << packs.standard_deviation() << endl; //</pre>
+
+ 
+
+ 
+
+ Quantile of 0.05 = 2.83551, mean = 3, sd = 0.1
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Let's start by guessing that it (now 0.1) needs to be halved, to
+ a standard deviation of 0.05
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+normal pack05(mean, 0.05);
+cout << "Quantile of " << p << " = " << quantile(pack05, p)
+ << ", mean = " << pack05.mean() << ", sd = " << pack05.standard_deviation() << endl;
+
+cout <<"Fraction of packs >= " << under_weight << " with a mean of " << mean
+ << " and standard deviation of " << pack05.standard_deviation()
+ << " is " << cdf(complement(pack05, under_weight)) << endl;
+//</pre>
+
+ 
+
+ 
+
+ Fraction of packs >= 2.9 with a mean of 3 and standard deviation
+ of 0.05 is 0.9772
+ 
+
+ 
+
+ 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
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+normal pack06(mean, 0.06);
+cout << "Quantile of " << p << " = " << quantile(pack06, p)
+ << ", mean = " << pack06.mean() << ", sd = " << pack06.standard_deviation() << endl;
+
+cout <<"Fraction of packs >= " << under_weight << " with a mean of " << mean
+ << " and standard deviation of " << pack06.standard_deviation()
+ << " is " << cdf(complement(pack06, under_weight)) << endl;</pre>
+
+ 
+
+ 
+
+ Fraction of packs >= 2.9 with a mean of 3 and standard deviation
+ of 0.06 is 0.9522
+ 
+
+ 
+
+ 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>.
+ 
+
+ 
+
+ But in this normal distribution case, we could be even smarter and
+ make a direct calculation.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+normal s; // For standard normal distribution,
+double sd = 0.1;
+double x = 2.9; // Our required limit.
+// then probability p = N((x - mean) / sd)
+// So if we want to find the standard deviation that would be required to meet this limit,
+// so that the p th quantile is located at x,
+// in this case the 0.95 (95%) quantile at 2.9 kg pack weight, when the mean is 3 kg.
+
+double prob = pdf(s, (x - mean) / sd);
+double qp = quantile(s, 0.95);
+cout << "prob = " << prob << ", quantile(p) " << qp << endl; // p = 0.241971, quantile(p) 1.64485
+// Rearranging, we can directly calculate the required standard deviation:
+double sd95 = abs((x - mean)) / qp;
+
+cout << "If we want the "<< p << " th quantile to be located at "
+ << x << ", would need a standard deviation of " << sd95 << endl;
+
+normal pack95(mean, sd95); // Distribution of the 'ideal better' packer.
+cout <<"Fraction of packs >= " << under_weight << " with a mean of " << mean
+ << " and standard deviation of " << pack95.standard_deviation()
+ << " is " << cdf(complement(pack95, under_weight)) << endl;
+
+// Fraction of packs >= 2.9 with a mean of 3 and standard deviation of 0.0608 is 0.95</pre>
+
+ 
+
+ 
+
+ 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. 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+<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>
+
+ 
+
+ 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.
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+ normal bolts(3.95, 0.1);
+ double top = 4.1;
+ double bottom = 3.9;
+
+cout << "Fraction long enough [ P(X <= " << top << ") ] is " << cdf(bolts, top) << endl;
+cout << "Fraction too short [ P(X <= " << bottom << ") ] is " << cdf(bolts, bottom) << endl;
+cout << "Fraction OK -between " << bottom << " and " << top
+ << "[ P(X <= " << top << ") - P(X<= " << bottom << " ) ] is "
+ << cdf(bolts, top) - cdf(bolts, bottom) << endl;
+
+cout << "Fraction too long [ P(X > " << top << ") ] is "
+ << cdf(complement(bolts, top)) << endl;
+
+cout << "95% of bolts are shorter than " << quantile(bolts, 0.95) << endl;
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="st_eg/tut_mean_intervals.html">
+ Calculating confidence intervals on the mean with the Students-t distribution</a></dt>
+<dt><a href="st_eg/tut_mean_test.html">
+ Testing a sample mean for difference from a "true" mean</a></dt>
+<dt><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></dt>
+<dt><a href="st_eg/two_sample_students_t.html">
+ Comparing the means of two samples with the Students-t test</a></dt>
+<dt><a href="st_eg/paired_st.html">
+ Comparing two paired samples with the Student's t distribution</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ That means we can:
+ 
+<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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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>).
+ 
+
+ The formula for the interval can be expressed as:
+ 
+
+ <img src="../../../../../../equations/dist_tutorial4.png">
+ 
+
+ Where, Ys is the sample mean, s
+ is the sample standard deviation, N is the sample
+ size, [alpha] is the desired significance level
+ and t(α/2,N-1) is the upper critical value of the
+ Students-t distribution with N-1 degrees of freedom.
+ 
+<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">
+
+ The quantity α is the maximum acceptable risk of falsely rejecting
+ the null-hypothesis. The smaller the value of α the greater the strength
+ of the test.
+ 
+
+ The confidence level of the test is defined as 1 - α, 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.
+ 
+</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">
+ 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.
+ </td></tr>
+</table></div>
+
+ From the formula, it should be clear that:
+ 
+<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 confidence level increases
+ (0.5 towards 0.99999 - stronger).
+ </li>
+<li>
+ The width increases as the significance level decreases
+ (0.5 towards 0.00000...01 - stronger).
+ </li>
+</ul></div>
+
+ The following example code is taken from the example program students_t_single_sample.cpp.
+ 
+
+ We'll begin by defining a procedure to calculate intervals for various
+ confidence levels; the procedure will print these out as a table:
+ 
+<pre class="programlisting">
+// Needed includes:
+#include <boost/math/distributions/students_t.hpp>
+#include <iostream>
+#include <iomanip>
+// Bring everything into global namespace for ease of use:
+using namespace boost::math;
+using namespace std;
+
+void confidence_limits_on_mean(
+ double Sm, // Sm = Sample Mean.
+ double Sd, // Sd = Sample Standard Deviation.
+ unsigned Sn) // Sn = Sample Size.
+{
+ using namespace std;
+ using namespace boost::math;
+
+ // Print out general info:
+ cout <<
+ "__________________________________\n"
+ "2-Sided Confidence Limits For Mean\n"
+ "__________________________________\n\n";
+ cout << setprecision(7);
+ cout << setw(40) << left << "Number of Observations" << "= " << Sn << "\n";
+ cout << setw(40) << left << "Mean" << "= " << Sm << "\n";
+ cout << setw(40) << left << "Standard Deviation" << "= " << Sd << "\n";
+</pre>
+
+ We'll define a table of significance/risk levels for which we'll compute
+ intervals:
+ 
+<pre class="programlisting">
+double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };
+</pre>
+
+ Note that these are the complements of the confidence/probability levels:
+ 0.5, 0.75, 0.9 .. 0.99999).
+ 
+
+ Next we'll declare the distribution object we'll need, note that the
+ degrees of freedom parameter is the sample size
+ less one:
+ 
+<pre class="programlisting">
+students_t dist(Sn - 1);
+</pre>
+
+ 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 quantile 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 complement(...):
+ 
+<pre class="programlisting">
+double T = quantile(complement(dist, alpha[i] / 2));
+</pre>
+
+ 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.
+ 
+
+ 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:
+ 
+<pre class="programlisting">
+double w = T * Sd / sqrt(double(Sn));
+</pre>
+
+ The two-sided interval is then the sample mean plus and minus this
+ width.
+ 
+
+ And apart from some more pretty-printing that completes the procedure.
+ 
+
+ 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>.
+ 
+<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>
+
+ 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.
+ 
+
+ For comparison the next example data output is taken from P.K.Hou,
+ O. W. Lau & 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.
+ The values result from the determination of mercury by cold-vapour
+ atomic absorption.
+ 
+<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>
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ 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:
+ 
+<pre class="programlisting">
+// Needed includes:
+#include <boost/math/distributions/students_t.hpp>
+#include <iostream>
+#include <iomanip>
+// Bring everything into global namespace for ease of use:
+using namespace boost::math;
+using namespace std;
+
+void single_sample_find_df(
+ double M, // M = true mean.
+ double Sm, // Sm = Sample Mean.
+ double Sd) // Sd = Sample Standard Deviation.
+{
+</pre>
+
+ Next we define a table of significance levels:
+ 
+<pre class="programlisting">
+double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };
+</pre>
+
+ Printing out the table of sample sizes required for various confidence
+ levels begins with the table header:
+ 
+<pre class="programlisting">
+cout << "\n\n"
+ "_______________________________________________________________\n"
+ "Confidence Estimated Estimated\n"
+ " Value (%) Sample Size Sample Size\n"
+ " (one sided test) (two sided test)\n"
+ "_______________________________________________________________\n";
+</pre>
+
+ And now the important part: the sample sizes required. Class <code class="computeroutput">students_t_distribution</code> has a static
+ member function <code class="computeroutput">find_degrees_of_freedom</code>
+ that will calculate how large a sample size needs to be in order to
+ give a definitive result.
+ 
+
+ 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.
+ 
+
+ 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.
+ 
+
+ The final parameter of the function is the standard deviation of the
+ sample.
+ 
+
+ In this example, we assume that alpha and beta are the same, and call
+ <code class="computeroutput">find_degrees_of_freedom</code>
+ twice: once with alpha for a one-sided test, and once with alpha/2
+ for a two-sided test.
+ 
+<pre class="programlisting">
+ for(unsigned i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
+ {
+ // Confidence value:
+ cout << fixed << setprecision(3) << setw(10) << right << 100 * (1-alpha[i]);
+ // calculate df for single sided test:
+ double df = students_t::find_degrees_of_freedom(
+ fabs(M - Sm), alpha[i], alpha[i], Sd);
+ // convert to sample size:
+ double size = ceil(df) + 1;
+ // Print size:
+ cout << fixed << setprecision(0) << setw(16) << right << size;
+ // calculate df for two sided test:
+ df = students_t::find_degrees_of_freedom(
+ fabs(M - Sm), alpha[i]/2, alpha[i], Sd);
+ // convert to sample size:
+ size = ceil(df) + 1;
+ // Print size:
+ cout << fixed << setprecision(0) << setw(16) << right << size << endl;
+ }
+ cout << endl;
+}
+</pre>
+
+ Let's now look at some sample output using data taken from P.K.Hou,
+ O. W. Lau & 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.
+ The values result from the determination of mercury by cold-vapour
+ atomic absorption.
+ 
+
+ 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:
+ 
+<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>
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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>.
+ 
+
+ Of course, the assignment of "true" to one mean may be quite
+ arbitrary, often this is simply a "traditional" method of
+ measurement.
+ 
+
+ The following example code is taken from the example program students_t_single_sample.cpp.
+ 
+
+ We'll begin by defining a procedure to determine which of the possible
+ hypothesis are rejected or not-rejected at a given significance level:
+ 
+<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">
+ Non-statisticians might say 'not-rejected' means 'accepted', (often
+ of the null-hypothesis) implying, wrongly, that there really IS no difference, but statisticans eschew
+ this to avoid implying that there is positive evidence of 'no difference'.
+ 'Not-rejected' here means there is no evidence
+ 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>
+ </td></tr>
+</table></div>
+<pre class="programlisting">
+// Needed includes:
+#include <boost/math/distributions/students_t.hpp>
+#include <iostream>
+#include <iomanip>
+// Bring everything into global namespace for ease of use:
+using namespace boost::math;
+using namespace std;
+
+void single_sample_t_test(double M, double Sm, double Sd, unsigned Sn, double alpha)
+{
+ //
+ // M = true mean.
+ // Sm = Sample Mean.
+ // Sd = Sample Standard Deviation.
+ // Sn = Sample Size.
+ // alpha = Significance Level.
+</pre>
+
+ Most of the procedure is pretty-printing, so let's just focus on the
+ calculation, we begin by calculating the t-statistic:
+ 
+<pre class="programlisting">
+// Difference in means:
+double diff = Sm - M;
+// Degrees of freedom:
+unsigned v = Sn - 1;
+// t-statistic:
+double t_stat = diff * sqrt(double(Sn)) / Sd;
+</pre>
+
+ 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:
+ 
+<pre class="programlisting">
+students_t dist(v);
+double q = cdf(complement(dist, fabs(t_stat)));
+</pre>
+
+ The procedure then prints out the results of the various tests that
+ can be done, these can be summarised in the following table:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Hypothesis
+ 
+ </th>
+<th>
+ 
+ Test
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ The Null-hypothesis: there is no difference
+ in means
+ 
+ </td>
+<td>
+ 
+ Reject if complement of CDF for |t| < significance level
+ / 2:
+ 
+ 
+ <code class="computeroutput">cdf(complement(dist,
+ fabs(t)))
+ < alpha
+ / 2</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ The Alternative-hypothesis: there is
+ difference in means
+ 
+ </td>
+<td>
+ 
+ Reject if complement of CDF for |t| > significance level
+ / 2:
+ 
+ 
+ <code class="computeroutput">cdf(complement(dist,
+ fabs(t)))
+ > alpha
+ / 2</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ The Alternative-hypothesis: the sample mean is
+ less than the true mean.
+ 
+ </td>
+<td>
+ 
+ Reject if CDF of t > significance level:
+ 
+ 
+ <code class="computeroutput">cdf(dist,
+ t)
+ > alpha</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ The Alternative-hypothesis: the sample mean is
+ greater than the true mean.
+ 
+ </td>
+<td>
+ 
+ Reject if complement of CDF of t > significance level:
+ 
+ 
+ <code class="computeroutput">cdf(complement(dist,
+ t))
+ > alpha</code>
+ 
+ </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">
+ Notice that the comparisons are against <code class="computeroutput">alpha
+ / 2</code>
+ for a two-sided test and against <code class="computeroutput">alpha</code>
+ for a one-sided test
+ </td></tr>
+</table></div>
+
+ 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>.
+ 
+<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 < 5.000 REJECTED
+ Mean > 5.000 NOT REJECTED
+</pre>
+
+ 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.
+ 
+
+ For comparison the next example data output is taken from P.K.Hou,
+ O. W. Lau & 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.
+ The values result from the determination of mercury by cold-vapour
+ atomic absorption.
+ 
+<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 < 38.900 REJECTED
+ Mean > 38.900 REJECTED
+</pre>
+
+ 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:
+ 
+<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 < 38.900 NOT REJECTED
+Mean > 38.900 REJECTED
+</pre>
+
+ In this case, we really have a borderline result, and more data (and/or
+ more accurate data), is needed for a more convincing conclusion.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ 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.
+ 
+
+ The sample code is in students_t_two_samples.cpp.
+ 
+
+ 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.
+ 
+
+ We begin by defining a procedure that will conduct our test assuming
+ equal variances:
+ 
+<pre class="programlisting">
+// Needed headers:
+#include <boost/math/distributions/students_t.hpp>
+#include <iostream>
+#include <iomanip>
+// Simplify usage:
+using namespace boost::math;
+using namespace std;
+
+void two_samples_t_test_equal_sd(
+ double Sm1, // Sm1 = Sample 1 Mean.
+ double Sd1, // Sd1 = Sample 1 Standard Deviation.
+ unsigned Sn1, // Sn1 = Sample 1 Size.
+ double Sm2, // Sm2 = Sample 2 Mean.
+ double Sd2, // Sd2 = Sample 2 Standard Deviation.
+ unsigned Sn2, // Sn2 = Sample 2 Size.
+ double alpha) // alpha = Significance Level.
+{
+</pre>
+
+ Our procedure will begin by calculating the t-statistic, assuming equal
+ variances the needed formulae are:
+ 
+
+ <img src="../../../../../../equations/dist_tutorial1.png">
+ 
+
+ where Sp is the "pooled" standard deviation of the two samples,
+ and v is the number of degrees of freedom of the
+ two combined samples. We can now write the code to calculate the t-statistic:
+ 
+<pre class="programlisting">
+// Degrees of freedom:
+double v = Sn1 + Sn2 - 2;
+cout << setw(55) << left << "Degrees of Freedom" << "= " << v << "\n";
+// Pooled variance:
+double sp = sqrt(((Sn1-1) * Sd1 * Sd1 + (Sn2-1) * Sd2 * Sd2) / v);
+cout << setw(55) << left << "Pooled Standard Deviation" << "= " << v << "\n";
+// t-statistic:
+double t_stat = (Sm1 - Sm2) / (sp * sqrt(1.0 / Sn1 + 1.0 / Sn2));
+cout << setw(55) << left << "T Statistic" << "= " << t_stat << "\n";
+</pre>
+
+ The next step is to define our distribution object, and calculate the
+ complement of the probability:
+ 
+<pre class="programlisting">
+students_t dist(v);
+double q = cdf(complement(dist, fabs(t_stat)));
+cout << setw(55) << left << "Probability that difference is due to chance" << "= "
+ << setprecision(3) << scientific << 2 * q << "\n\n";
+</pre>
+
+ 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:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Hypothesis
+ 
+ </th>
+<th>
+ 
+ Test
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ The Null-hypothesis: there is no difference
+ in means
+ 
+ </td>
+<td>
+ 
+ Reject if complement of CDF for |t| < significance level
+ / 2:
+ 
+ 
+ <code class="computeroutput">cdf(complement(dist,
+ fabs(t)))
+ < alpha
+ / 2</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ The Alternative-hypothesis: there is a difference
+ in means
+ 
+ </td>
+<td>
+ 
+ Reject if complement of CDF for |t| > significance level
+ / 2:
+ 
+ 
+ <code class="computeroutput">cdf(complement(dist,
+ fabs(t)))
+ < alpha
+ / 2</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ The Alternative-hypothesis: Sample 1 Mean is less
+ than Sample 2 Mean.
+ 
+ </td>
+<td>
+ 
+ Reject if CDF of t > significance level:
+ 
+ 
+ <code class="computeroutput">cdf(dist,
+ t)
+ > alpha</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ The Alternative-hypothesis: Sample 1 Mean is greater
+ than Sample 2 Mean.
+ 
+ </td>
+<td>
+ 
+ Reject if complement of CDF of t > significance level:
+ 
+ 
+ <code class="computeroutput">cdf(complement(dist,
+ t))
+ > alpha</code>
+ 
+ </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">
+ For a two-sided test we must compare against alpha / 2 and not alpha.
+ </td></tr>
+</table></div>
+
+ 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>.
+ 
+<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 < Sample 2 Mean NOT REJECTED
+ Sample 1 Mean > Sample 2 Mean REJECTED
+</pre>
+
+ 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.
+ 
+
+ 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.
+ 
+
+ 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:
+ 
+
+ <img src="../../../../../../equations/dist_tutorial2.png">
+ 
+
+ And for the combined degrees of freedom we use the Welch-Satterthwaite
+ approximation:
+ 
+
+ <img src="../../../../../../equations/dist_tutorial3.png">
+ 
+
+ 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.
+ 
+<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">
+ 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.
+ </td></tr>
+</table></div>
+
+ Putting these formulae into code we get:
+ 
+<pre class="programlisting">
+// Degrees of freedom:
+double v = Sd1 * Sd1 / Sn1 + Sd2 * Sd2 / Sn2;
+v *= v;
+double t1 = Sd1 * Sd1 / Sn1;
+t1 *= t1;
+t1 /= (Sn1 - 1);
+double t2 = Sd2 * Sd2 / Sn2;
+t2 *= t2;
+t2 /= (Sn2 - 1);
+v /= (t1 + t2);
+cout << setw(55) << left << "Degrees of Freedom" << "= " << v << "\n";
+// t-statistic:
+double t_stat = (Sm1 - Sm2) / sqrt(Sd1 * Sd1 / Sn1 + Sd2 * Sd2 / Sn2);
+cout << setw(55) << left << "T Statistic" << "= " << t_stat << "\n";
+</pre>
+
+ 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:
+ 
+<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 < Sample 2 Mean NOT REJECTED
+ Sample 1 Mean > Sample 2 Mean REJECTED
+</pre>
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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> About the Math Toolkit</dt>
+<dt> Navigation</dt>
+<dt><a href="main_overview/directories.html"> Directory and
+ File Structure</a></dt>
+<dt> Namespaces</dt>
+<dt><a href="main_overview/result_type.html"> Calculation
+ of the Type of the Result</a></dt>
+<dt> Error Handling</dt>
+<dt><a href="main_overview/pol_overview.html"> Configuration
+ and Policies</a></dt>
+<dt> Thread Safety</dt>
+<dt> Performance</dt>
+<dt><a href="main_overview/history1.html"> History and What's
+ New</a></dt>
+<dt><a href="main_overview/contact.html"> Contact Info and
+ Support</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ The main support for this library is via the Boost mailing lists:
+ 
+<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>
+
+ You can also find JM at john - at - johnmaddock.co.uk and PAB at pbristow
+ - at - hetp.u-net.com.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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">
+
+<dl>
+<dt>/concepts/</dt>
+<dd>
+ Prototype defining the essential features
+ of a RealType class (see real_concept.hpp). Most applications will use
+ <code class="computeroutput">double</code> as the RealType (and
+ short <code class="computeroutput">typedef</code> names of distributions
+ are reserved for this type where possible), a few will use <code class="computeroutput">float</code> or <code class="computeroutput">long
+ double</code>, but it is also possible
+ to use higher precision types like NTL::RR
+ that conform to the requirements specified by real_concept.
+ </dd>
+<dt>/constants/</dt>
+<dd>
+ Templated definition of some highly accurate math constants (in constants.hpp).
+ </dd>
+<dt>/distributions/</dt>
+<dd>
+ Distributions used in mathematics and, especially, statistics: Gaussian,
+ Students-t, Fisher, Binomial etc
+ </dd>
+<dt>/policies/</dt>
+<dd>
+ Policy framework, for handling user requested behaviour modifications.
+ </dd>
+<dt>/special_functions/</dt>
+<dd>
+ 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).
+ </dd>
+<dt>/tools/</dt>
+<dd>
+ Tools used by functions, like evaluating polynomials, continued fractions,
+ root finding, precision and limits, and by tests. Some will find application
+ outside this package.
+ </dd>
+</dl>
+</div>
+<a name="math_toolkit.main_overview.directories.boost_libs"></a><h5>
+<a name="id436060"></a>
+ boost/libs
+ </h5>
+<div class="variablelist">
+
+<dl>
+<dt>/doc/</dt>
+<dd>
+ Documentation source files in Quickbook format processed into html and
+ pdf formats.
+ </dd>
+<dt>/examples/</dt>
+<dd>
+ Examples and demos of using math functions and distributions.
+ </dd>
+<dt>/performance/</dt>
+<dd>
+ Performance testing and tuning program.
+ </dd>
+<dt>/test/</dt>
+<dd>
+ 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).
+ </dd>
+<dt>/tools/</dt>
+<dd>
+ Programs used to generate test data. Also changes to the NTL
+ released package to provide a few additional (and vital) extra features.
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ Handling of errors by this library is split into two orthogonal parts:
+ 
+<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>
+
+ The kinds of errors that can be raised are:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>Domain Error</dt>
+<dd>
+ Occurs when one or more arguments to a function are out of range.
+ </dd>
+<dt>Pole Error</dt>
+<dd>
+ 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.
+ </dd>
+<dt>Overflow Error</dt>
+<dd>
+ Occurs when the result is either infinite, or too large to represent
+ in the numeric type being returned by the function.
+ </dd>
+<dt>Underflow Error</dt>
+<dd>
+ 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.
+ </dd>
+<dt>Denormalisation Error</dt>
+<dd>
+ Occurs when the returned result would be a denormalised value.
+ </dd>
+<dt>Evaluation Error</dt>
+<dd>
+ 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.
+ </dd>
+</dl>
+</div>
+
+ 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).
+ 
+
+ The available actions are:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>throw_on_error</dt>
+<dd>
+ Throws the exception most appropriate to the error condition.
+ </dd>
+<dt>errno_on_error</dt>
+<dd>
+ Sets ::errno to an appropriate value, and then returns the most appropriate
+ result
+ </dd>
+<dt>ignore_error</dt>
+<dd>
+ Ignores the error and simply the returns the most appropriate result.
+ </dd>
+<dt>user_error</dt>
+<dd>
+ Calls a <a href="../policy/pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">user-supplied
+ error handler</a>.
+ </dd>
+</dl>
+</div>
+
+ The following tables show all the permutations of errors and actions, with
+ the default action for each error shown in bold:
+ 
+<div class="table">
+<a name="id491270"></a>Table 1. Possible Actions for Domain Errors
+<div class="table-contents"><table class="table" summary="Possible Actions for Domain Errors">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Action
+ 
+ </th>
+<th>
+ 
+ Behaviour
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ throw_on_error
+ 
+ </td>
+<td>
+ 
+ Throws <code class="computeroutput">std::domain_error</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ errno_on_error
+ 
+ </td>
+<td>
+ 
+ Sets <code class="computeroutput">::errno</code>
+ to <code class="computeroutput">EDOM</code> and returns
+ <code class="computeroutput">std::numeric_limits<T>::quiet_NaN()</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ignore_error
+ 
+ </td>
+<td>
+ 
+ Returns <code class="computeroutput">std::numeric_limits<T>::quiet_NaN()</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ user_error
+ 
+ </td>
+<td>
+ 
+ Returns the result of <code class="computeroutput">boost::math::policies::user_domain_error</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>.
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id491586"></a>Table 2. Possible Actions for Pole Errors
+<div class="table-contents"><table class="table" summary="Possible Actions for Pole Errors">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Action
+ 
+ </th>
+<th>
+ 
+ Behaviour
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ throw_on_error
+ 
+ </td>
+<td>
+ 
+ Throws <code class="computeroutput">std::domain_error</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ errno_on_error
+ 
+ </td>
+<td>
+ 
+ Sets <code class="computeroutput">::errno</code>
+ to <code class="computeroutput">EDOM</code> and returns
+ <code class="computeroutput">std::numeric_limits<T>::quiet_NaN()</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ignore_error
+ 
+ </td>
+<td>
+ 
+ Returns <code class="computeroutput">std::numeric_limits<T>::quiet_NaN()</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ user_error
+ 
+ </td>
+<td>
+ 
+ Returns the result of <code class="computeroutput">boost::math::policies::user_pole_error</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>.
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id491900"></a>Table 3. Possible Actions for Overflow Errors
+<div class="table-contents"><table class="table" summary="Possible Actions for Overflow Errors">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Action
+ 
+ </th>
+<th>
+ 
+ Behaviour
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ throw_on_error
+ 
+ </td>
+<td>
+ 
+ Throws <code class="computeroutput">std::overflow_error</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ errno_on_error
+ 
+ </td>
+<td>
+ 
+ Sets <code class="computeroutput">::errno</code>
+ to <code class="computeroutput">ERANGE</code> and returns
+ <code class="computeroutput">std::numeric_limits<T>::infinity()</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ignore_error
+ 
+ </td>
+<td>
+ 
+ Returns <code class="computeroutput">std::numeric_limits<T>::infinity()</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ user_error
+ 
+ </td>
+<td>
+ 
+ Returns the result of <code class="computeroutput">boost::math::policies::user_overflow_error</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>.
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id492216"></a>Table 4. Possible Actions for Underflow Errors
+<div class="table-contents"><table class="table" summary="Possible Actions for Underflow Errors">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Action
+ 
+ </th>
+<th>
+ 
+ Behaviour
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ throw_on_error
+ 
+ </td>
+<td>
+ 
+ Throws <code class="computeroutput">std::underflow_error</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ errno_on_error
+ 
+ </td>
+<td>
+ 
+ Sets <code class="computeroutput">::errno</code>
+ to <code class="computeroutput">ERANGE</code> and returns
+ 0.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ignore_error
+ 
+ </td>
+<td>
+ 
+ Returns 0
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ user_error
+ 
+ </td>
+<td>
+ 
+ Returns the result of <code class="computeroutput">boost::math::policies::user_underflow_error</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>.
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id492440"></a>Table 5. Possible Actions for Denorm Errors
+<div class="table-contents"><table class="table" summary="Possible Actions for Denorm Errors">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Action
+ 
+ </th>
+<th>
+ 
+ Behaviour
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ throw_on_error
+ 
+ </td>
+<td>
+ 
+ Throws <code class="computeroutput">std::underflow_error</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ errno_on_error
+ 
+ </td>
+<td>
+ 
+ Sets <code class="computeroutput">::errno</code>
+ to <code class="computeroutput">ERANGE</code> and returns
+ the denormalised value.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ignore_error
+ 
+ </td>
+<td>
+ 
+ Returns the denormalised value.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ user_error
+ 
+ </td>
+<td>
+ 
+ Returns the result of <code class="computeroutput">boost::math::policies::user_denorm_error</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>.
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id492664"></a>Table 6. Possible Actions for Internal Evaluation
+ Errors
+<div class="table-contents"><table class="table" summary="Possible Actions for Internal Evaluation
+ Errors">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Action
+ 
+ </th>
+<th>
+ 
+ Behaviour
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ throw_on_error
+ 
+ </td>
+<td>
+ 
+ Throws <code class="computeroutput">boost::math::evaluation_error</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ errno_on_error
+ 
+ </td>
+<td>
+ 
+ Sets <code class="computeroutput">::errno</code>
+ to <code class="computeroutput">EDOM</code> and returns
+ <code class="computeroutput">std::numeric_limits<T>::infinity()</code>.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ignore_error
+ 
+ </td>
+<td>
+ 
+ Returns <code class="computeroutput">std::numeric_limits<T>::infinity()</code>.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ user_error
+ 
+ </td>
+<td>
+ 
+ Returns the result of <code class="computeroutput">boost::math::policies::user_evaluation_error</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>.
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <a name="math_toolkit.main_overview.error_handling.rationale"></a><h5>
+<a name="id493000"></a>
+ Rationale
+ </h5>
+
+ 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:
+ 
+<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>
+
+ 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>.
+ 
+
+ 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>.
+ 
+
+ 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>.
+ 
+
+ The various kind of errors are described in more detail below.
+ 
+<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>
+
+ 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:
+ 
+<pre class="programlisting">
+boost::math::policies::raise_domain_error<T>(FunctionName, Message, Val, Policy);
+</pre>
+
+ Where <code class="computeroutput">T</code> is the floating-point
+ type passed to the function, <code class="computeroutput">FunctionName</code>
+ is the name of the function, <code class="computeroutput">Message</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.
+ 
+
+ 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.
+ 
+
+ This behaviour is chosen to assist compatibility with the behaviour of ISO/IEC
+ 9899:1999 Programming languages - C 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>:
+ 
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ "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:
+ 
+
+ 
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ "the function description's Returns clause explicitly
+ specifies a domain, and those arguments fall outside the specified domain;
+ or
+ 
+
+ 
+
+ "the corresponding mathematical function value has a non-zero
+ imaginary component; or
+ 
+
+ 
+
+ "the corresponding mathematical function is not mathematically
+ defined.
+ 
+
+ 
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ "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."
+ 
+
+ 
+</blockquote></div>
+
+ Note that in order to support information-rich error messages when throwing
+ exceptions, <code class="computeroutput">Message</code> must
+ contain a Boost.Format
+ recognised format specifier: the argument <code class="computeroutput">Val</code>
+ is inserted into the error message according to the specifier used.
+ 
+
+ For example if <code class="computeroutput">Message</code> contains
+ a "%1%" then it is replaced by the value of <code class="computeroutput">Val</code>
+ to the full precision of T, where as "%.3g" would contain the value
+ of <code class="computeroutput">Val</code> to 3 digits. See the
+ Boost.Format documentation
+ for more details.
+ 
+<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>
+
+ 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:
+ 
+<pre class="programlisting">
+boost::math::policies::raise_pole_error<T>(FunctionName, Message, Val, Policy);
+</pre>
+
+ Where <code class="computeroutput">T</code> is the floating point
+ type passed to the function, <code class="computeroutput">FunctionName</code>
+ is the name of the function, <code class="computeroutput">Message</code>
+ is an error message describing the problem, <code class="computeroutput">Val</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.
+ 
+
+ 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">ignore_error</code> and return NaN.
+ 
+
+ Note that in order to support information-rich error messages when throwing
+ exceptions, <code class="computeroutput">Message</code> must
+ contain a Boost.Format
+ recognised format specifier: the argument <code class="computeroutput">val</code>
+ is inserted into the error message according to the specifier used.
+ 
+
+ For example if <code class="computeroutput">Message</code> contains
+ a "%1%" then it is replaced by the value of <code class="computeroutput">val</code>
+ to the full precision of T, where as "%.3g" would contain the value
+ of <code class="computeroutput">val</code> to 3 digits. See the
+ Boost.Format documentation
+ for more details.
+ 
+<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>
+
+ 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:
+ 
+<pre class="programlisting">
+boost::math::policies::raise_overflow_error<T>(FunctionName, Message, Policy);
+</pre>
+
+ Where <code class="computeroutput">T</code> is the floating-point
+ type passed to the function, <code class="computeroutput">FunctionName</code>
+ is the name of the function, <code class="computeroutput">Message</code>
+ is an error message describing the problem, and Policy
+ is the current policy in use for the function that was called.
+ 
+
+ The default policy for this function is that <code class="computeroutput">std::overflow_error</code>
+ C++ exception is thrown. But if, for example, an <code class="computeroutput">ignore_error</code>
+ policy is used, then returns <code class="computeroutput">std::numeric_limits<T>::infinity()</code>.
+ In this situation if the type <code class="computeroutput">T</code>
+ doesn't support infinities, the maximum value for the type is returned.
+ 
+<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>
+
+ 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:
+ 
+<pre class="programlisting">
+boost::math::policies::raise_underflow_error<T>(FunctionName, Message, Policy);
+</pre>
+
+ Where <code class="computeroutput">T</code> is the floating point
+ type passed to the function, <code class="computeroutput">FunctionName</code>
+ is the name of the function, <code class="computeroutput">Message</code>
+ is an error message describing the problem, and Policy
+ is the current policy in use for the called function.
+ 
+
+ The default version of this function returns zero. But with another policy,
+ like <code class="computeroutput">throw_on_error</code>, throws
+ an <code class="computeroutput">std::underflow_error</code> C++ exception.
+ 
+<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>
+
+ If the result of a special function is a denormalised value z
+ then the function returns the result of:
+ 
+<pre class="programlisting">
+boost::math::policies::raise_denorm_error<T>(z, FunctionName, Message, Policy);
+</pre>
+
+ Where <code class="computeroutput">T</code> is the floating point
+ type passed to the function, <code class="computeroutput">FunctionName</code>
+ is the name of the function, <code class="computeroutput">Message</code>
+ is an error message describing the problem, and Policy
+ is the current policy in use for the called function.
+ 
+
+ The default version of this function returns z. But
+ with another policy, like <code class="computeroutput">throw_on_error</code>
+ throws an <code class="computeroutput">std::underflow_error</code> C++ exception.
+ 
+<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>
+
+ When a special function calculates a result that is known to be erroneous,
+ or where the result is incalculable then it calls:
+ 
+<pre class="programlisting">
+boost::math::policies::raise_evaluation_error<T>(FunctionName, Message, Val, Policy);
+</pre>
+
+ Where <code class="computeroutput">T</code> is the floating point
+ type passed to the function, <code class="computeroutput">FunctionName</code>
+ is the name of the function, <code class="computeroutput">Message</code>
+ is an error message describing the problem, <code class="computeroutput">Val</code>
+ is the erroneous value, and Policy
+ is the current policy in use for the called function.
+ 
+
+ The default behaviour of this function is to throw a <code class="computeroutput">boost::math::evaluation_error</code>.
+ 
+
+ Note that in order to support information rich error messages when throwing
+ exceptions, <code class="computeroutput">Message</code> must
+ contain a Boost.Format
+ recognised format specifier: the argument <code class="computeroutput">val</code>
+ is inserted into the error message according to the specifier used.
+ 
+
+ For example if <code class="computeroutput">Message</code> contains
+ a "%1%" then it is replaced by the value of <code class="computeroutput">val</code>
+ to the full precision of T, where as "%.3g" would contain the value
+ of <code class="computeroutput">val</code> to 3 digits. See the
+ Boost.Format documentation
+ for more details.
+ 
+<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>
+
+ 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:
+ 
+<pre class="programlisting">
+template <class T, class Policy, class U>
+T checked_narrowing_cast(U const& val, const char* function);
+</pre>
+
+ Is used to perform these conversions, and will call the error handlers listed
+ above on overflow, underflow
+ or denormalisation.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ <a name="math_toolkit.main_overview.history1.milestone_5__post_review_first_official_release"></a>
+ 
+<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>
+
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Added Policy based framework that allows fine grained control over function
+ behaviour.
+ </li>
+<li>
+Breaking change: 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>
+Breaking change: Changed exception thrown
+ when an internal evaluation error occurs to boost::math::evaluation_error.
+ </li>
+<li>
+Breaking change: 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>
+
+ <a name="math_toolkit.main_overview.history1.milestone_4__second_review_candidate__1st_march_2007_"></a>
+ 
+<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>
+
+ 
+<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>
+
+ <a name="math_toolkit.main_overview.history1.milestone_3__first_review_candidate__31st_dec_2006_"></a>
+ 
+<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>
+
+ 
+<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>
+
+ <a name="math_toolkit.main_overview.history1.milestone_2__released_september_10th_2006"></a>
+ 
+<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>
+
+ 
+<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>
+
+ <a name="math_toolkit.main_overview.history1.milestone_1__released_march_31st_2006"></a>
+ 
+<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>
+
+ 
+<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>
+
+ 
+
+ SVN Revisions:
+ 
+
+ 
+
+ Sandbox revision merged to trunk: 39833. Trunk revision: 39833.
+ 
+
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ This library is divided into three interconnected parts:
+ 
+<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>
+
+ 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.
+ 
+
+ The initial focus is on the central <a href="http://en.wikipedia.org/wiki/Univariate" target="_top">univariate
+ </a> distributions.
+ Both continuous
+ (like normal
+ & Fisher)
+ and discrete
+ (like binomial
+ & Poisson)
+ distributions are provided.
+ 
+
+ 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.
+ 
+<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>
+
+ 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>.
+ 
+
+ The function families currently implemented are the gamma, beta & erf
+ functions along with the incomplete gamma and beta functions (four variants
+ of each) and all the possible inverses of these, plus digamma, various factorial
+ functions, Bessel functions, elliptic integrals, sinus cardinals (along with
+ their hyperbolic variants), inverse hyperbolic functions, Legrendre/Laguerre/Hermite
+ polynomials and various special power and logarithmic functions.
+ 
+
+ All the implementations are fully generic and support the use of arbitrary
+ "real-number" types, although they are optimised for use with types
+ with known-about <a href="http://en.wikipedia.org/wiki/Significand" target="_top">significand
+ (or mantissa)</a> sizes: typically <code class="computeroutput">float</code>,
+ <code class="computeroutput">double</code> or <code class="computeroutput">long
+ double</code>.
+ 
+<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>
+
+ 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.
+ 
+
+ 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>.
+ 
+
+ 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.
+ 
+
+ 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.
+ 
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ All math functions and distributions are in <code class="computeroutput">namespace
+ boost::math</code>
+ 
+
+ So, for example, the Students-t distribution template in <code class="computeroutput">namespace
+ boost::math</code> is
+ 
+<pre class="programlisting">
+template <class RealType> class students_t_distribution
+</pre>
+
+ and can be instantiated with the help of the reserved name <code class="computeroutput">students_t</code>(for <code class="computeroutput">RealType
+ double</code>)
+ 
+<pre class="programlisting">
+typedef students_t_distribution<double> students_t;
+
+student_t mydist(10);
+</pre>
+
+ Functions not intended for use by applications are in <code class="computeroutput">boost::math::detail</code>.
+ 
+
+ Functions that may have more general use, like <code class="computeroutput">digits</code>
+ (significand), <code class="computeroutput">max_value</code>,
+ <code class="computeroutput">min_value</code> and <code class="computeroutput">epsilon</code> are in <code class="computeroutput">boost::math::tools</code>.
+ 
+
+ Policy and configuration information
+ is in namespace <code class="computeroutput">boost::math::policies</code>.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ Used in combination with the configured browser key, the following keys act
+ as handy shortcuts for common navigation tasks.
+ 
+<a name="math_toolkit.main_overview.navigation.shortcuts"></a><h6>
+<a name="id440191"></a>
+ Shortcuts
+ </h6>
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ <code class="literal">p</code> - Previous page
+ 
+
+ 
+
+ <code class="literal">n</code> - Next page
+ 
+
+ 
+
+ <code class="literal">h</code> - home
+ 
+
+ 
+
+ <code class="literal">u</code> - Up
+ 
+
+ 
+</blockquote></div>
+
+ The following table shows how to access these from common browsers:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Browser
+ 
+ </th>
+<th>
+ 
+ Access Method
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Internet Explorer
+ 
+ </td>
+<td>
+ 
+ Alt+Key highlights the link only, so for example to move to the next
+ topic you would need "Alt+n" followed by "Enter".
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Firefox 2.0 and later
+ 
+ </td>
+<td>
+ 
+ Alt+Shift+Key follows the link, so for example "Alt+Shift+n"
+ will take you to the next topic.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Opera
+ 
+ </td>
+<td>
+ 
+ Press Shift+Esc followed by the access key.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Konqueror
+ 
+ </td>
+<td>
+ 
+ Press and release the Ctrl key, followed by the access key
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 
+
+ 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 not speed.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ The two most important things you can do to ensure the best performance
+ from this library are:
+ 
+
+ 
+<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>
+
+ 
+
+ 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.
+ 
+
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 
+
+ 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>.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Policies are a compile-time mechanism that allow you to change error-handling
+ or calculation precision either program wide, or at the call site.
+ 
+
+ 
+
+ Although the policy mechanism itself is rather complicated, in practice
+ it is easy to use, and very flexible.
+ 
+
+ 
+
+ Using policies you can control:
+ 
+
+ 
+<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>
+
+ 
+
+ You can control policies:
+ 
+
+ 
+<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>
+
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ The functions in this library are all overloaded to accept mixed floating
+ point (or mixed integer and floating point type) arguments. So for example:
+ 
+<pre class="programlisting">
+foo(1.0, 2.0);
+foo(1.0f, 2);
+foo(1.0, 2L);
+</pre>
+
+ etc, are all valid calls, as long as "foo" is a function taking
+ two floating-point arguments. But that leaves the question:
+ 
+<div class="sidebar">
+
+
+ "Given a special function with N arguments of types T1, T2,
+ T3 ... TN, then what type is the result?"
+ 
+</div>
+
+ If all the arguments are of the same (floating point)
+ type then the result is the same type as the arguments.
+ 
+
+ Otherwise, the type of the result is computed using the following logic:
+ 
+<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">long
+ double</code>, then the result is of type
+ <code class="computeroutput">long double</code>.
+ </li>
+<li>
+ If any of the arguments is of type <code class="computeroutput">double</code>,
+ then the result is of type <code class="computeroutput">double</code>.
+ </li>
+<li>
+ Otherwise the result is of type <code class="computeroutput">float</code>.
+ </li>
+</ol></div>
+
+ For example:
+ 
+<pre class="programlisting">
+cyl_bessel(2, 3.0);
+</pre>
+
+ Returns a <code class="computeroutput">double</code> result, as
+ does:
+ 
+<pre class="programlisting">
+cyl_bessel(2, 3.0f);
+</pre>
+
+ as in this case the integer first argument is treated as a <code class="computeroutput">double</code> and takes precedence over the <code class="computeroutput">float</code> second argument. To get a <code class="computeroutput">float</code> result we would need all the arguments
+ to be of type float:
+ 
+<pre class="programlisting">
+cyl_bessel_j(2.0f, 3.0f);
+</pre>
+
+ When one or more of the arguments is not a template argument then it doesn't
+ effect the return type at all, for example:
+ 
+<pre class="programlisting">
+sph_bessel(2, 3.0f);
+</pre>
+
+ returns a <code class="computeroutput">float</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">float</code>.
+ 
+
+ And for user defined types, all of the following return an NTL::RR result:
+ 
+<pre class="programlisting">
+cyl_bessel_j(0, NTL::RR(2));
+
+cyl_bessel_j(NTL::RR(2), 3);
+
+cyl_bessel_j(NTL::quad_float(2), NTL::RR(3));
+</pre>
+
+ 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.
+ 
+
+ These rules are chosen to be compatible with the behaviour of ISO/IEC
+ 9899:1999 Programming languages - C 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>.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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">float</code>,
+ <code class="computeroutput">double</code> and <code class="computeroutput">long
+ double</code>.
+ 
+
+ However, the library is not thread safe
+ when used with user-defined (i.e. class type) numeric types.
+ 
+
+ The reason for the latter limitation is the need to initialise symbolic constants
+ using constructs such as:
+ 
+<pre class="programlisting">
+static const T coefficient_array = { ... list of values ... };
+</pre>
+
+ 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.
+ 
+
+ This limitation may be addressed in a future release.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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> Performance Overview</dt>
+<dt> Interpretting these Results</dt>
+<dt><a href="perf/getting_best.html"> Getting the Best Performance
+ from this Library</a></dt>
+<dt> Comparing Compilers</dt>
+<dt> Performance Tuning Macros</dt>
+<dt><a href="perf/comparisons.html"> Comparisons to Other
+ Open Source Libraries</a></dt>
+<dt><a href="perf/perf_test_app.html"> The Performance Test
+ Application</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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).
+ 
+<div class="table">
+<a name="id776819"></a>Table 38. Performance Comparison of Various Windows Compilers
+<div class="table-contents"><table class="table" summary="Performance Comparison of Various Windows Compilers">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Intel C++ 10.0
+ 
+ 
+ ( /Ox /Qipo /QxN )
+ 
+ </th>
+<th>
+ 
+ Microsoft Visual C++ 8.0
+ 
+ 
+ ( /Ox /arch:SSE2 )
+ 
+ </th>
+<th>
+ 
+ Cygwin G++ 3.4
+ 
+ 
+ ( /O3 )
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ erf
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(4.118e-008s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.50
+ 
+(6.173e-008s)
+
+ 
+ </td>
+<td>
+ 
+ 
+3.24
+ 
+(1.336e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ erf_inv
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(4.439e-008s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.42
+ 
+(6.302e-008s)
+
+ 
+ </td>
+<td>
+ 
+ 
+7.88
+ 
+(3.500e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ibeta
+ and ibetac
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.631e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.14
+ 
+(1.852e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+3.05
+ 
+(4.975e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ibeta_inv
+ and ibetac_inv
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(6.133e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.19
+ 
+(7.311e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+2.60
+ 
+(1.597e-005s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ibeta_inva,
+ ibetac_inva,
+ ibeta_invb
+ and ibetac_invb
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(2.453e-005s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.16
+ 
+(2.847e-005s)
+
+ 
+ </td>
+<td>
+ 
+ 
+2.83
+ 
+(6.947e-005s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ gamma_p
+ and gamma_q
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(6.735e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.41
+ 
+(9.504e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+2.78
+ 
+(1.872e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ gamma_p_inv
+ and gamma_q_inv
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(2.637e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.38
+ 
+(3.631e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+3.31
+ 
+(8.736e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ gamma_p_inva
+ and gamma_q_inva
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(7.716e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.29
+ 
+(9.982e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+2.56
+ 
+(1.974e-005s)
+
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+<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">
+ 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 our 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.
+ </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>
+
+ 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">/Ox
+ /arch:SSE2</code> options.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Boost
+ 
+ </th>
+<th>
+ 
+ GSL-1.9
+ 
+ </th>
+<th>
+ 
+ Cephes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ tgamma
+ 
+ </td>
+<td>
+ 
+ 
+1.50
+ 
+(2.566e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.54
+ 
+(2.627e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.709e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ lgamma
+ 
+ </td>
+<td>
+ 
+ 
+1.73
+ 
+(2.688e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+3.61
+ 
+(5.621e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.556e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ gamma_p
+ and gamma_q
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(9.504e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+2.15
+ 
+(2.042e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+2.57
+ 
+(2.439e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ gamma_p_inv
+ and gamma_q_inv
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(3.631e-006s)
+
+ 
+ </td>
+<td>
+ 
+ N/A
+ 
+ </td>
+<td>
+ 
+ +INF
+ [<a name="id779653" href="#ftn.id779653">1</a>]
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ibeta
+ and ibetac
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.852e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.07
+ 
+(1.974e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.07
+ 
+(1.974e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ibeta_inv
+ and ibetac_inv
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(7.311e-006s)
+
+ 
+ </td>
+<td>
+ 
+ N/A
+ 
+ </td>
+<td>
+ 
+ 
+2.24
+ 
+(1.637e-005s)
+
+ 
+ </td>
+</tr>
+</tbody>
+<tbody class="footnotes"><tr><td colspan="4"><div class="footnote">[<a name="ftn.id779653" href="#id779653">1</a>] 
+ Cephes gets stuck in an infinite loop while trying to execute
+ our test cases.
+ </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>
+
+ 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++).
+ 
+<div class="table">
+<a name="id779850"></a>Table 41. A Comparison to the R Statistical Library on Windows
+ XP
+<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>
+ 
+ Statistical Function
+ 
+ </th>
+<th>
+ 
+ Boost
+ 
+ </th>
+<th>
+ 
+ R
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Beta Distribution
+ CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.20
+ 
+(1.916e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.597e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Beta Distribution
+ Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(6.570e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+74.66
+ [<a name="id779990" href="#ftn.id779990">1</a>]
+ 
+ 
+(4.905e-004s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/binomial_dist.html" title="Binomial Distribution">Binomial
+ Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(5.276e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+2.45
+ 
+(1.293e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/binomial_dist.html" title="Binomial Distribution">Binomial
+ Distribution</a> Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(4.013e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.32
+ 
+(5.280e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/cauchy_dist.html" title="Cauchy-Lorentz Distribution">Cauchy
+ Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.231e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.28
+ 
+(1.576e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/cauchy_dist.html" title="Cauchy-Lorentz Distribution">Cauchy
+ Distribution</a> Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.498e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.498e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/chi_squared_dist.html" title="Chi Squared Distribution">Chi
+ Squared Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(7.889e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+2.48
+ 
+(1.955e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/chi_squared_dist.html" title="Chi Squared Distribution">Chi
+ Squared Distribution</a> Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(4.303e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.61
+ 
+(6.925e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/exp_dist.html" title="Exponential Distribution">Exponential
+ Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.955e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.97
+ 
+(3.844e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/exp_dist.html" title="Exponential Distribution">Exponential
+ Distribution</a> Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.07
+ 
+(1.206e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.126e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Fisher F Distribution
+ CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.309e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+2.12
+ 
+(2.780e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Fisher F Distribution
+ Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(7.204e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.78
+ 
+(1.280e-005s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Gamma Distribution
+ CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.076e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+2.07
+ 
+(2.227e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Gamma Distribution
+ Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(5.189e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.14
+ 
+(5.937e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/lognormal_dist.html" title="Log Normal Distribution">Log-normal
+ Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(2.078e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.41
+ 
+(2.930e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/lognormal_dist.html" title="Log Normal Distribution">Log-normal
+ Distribution</a> Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(6.692e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.63
+ 
+(1.090e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
+ Binomial Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(9.005e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+2.42
+ 
+(2.178e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
+ Binomial Distribution</a> Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(9.601e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+53.59
+ [<a name="id780839" href="#ftn.id780839">2</a>]
+ 
+ 
+(5.145e-004s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/normal_dist.html" title="Normal (Gaussian) Distribution">Normal
+ Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(5.926e-008s)
+
+ 
+ </td>
+<td>
+ 
+ 
+3.01
+ 
+(1.785e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/normal_dist.html" title="Normal (Gaussian) Distribution">Normal
+ Distribution</a> Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.248e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.05
+ 
+(1.311e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/poisson_dist.html" title="Poisson Distribution">Poisson
+ Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(8.999e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+2.42
+ 
+(2.175e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/poisson_dist.html" title="Poisson Distribution">Poisson
+ Distribution</a>
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.853e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+2.17
+ 
+(4.014e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/students_t_dist.html" title="Students t Distribution">Students
+ t Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.223e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.13
+ 
+(1.376e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/students_t_dist.html" title="Students t Distribution">Students
+ t Distribution</a> Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(2.570e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.04
+ 
+(2.668e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Weibull Distribution
+ CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(4.741e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.46
+ 
+(6.943e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Weibull Distribution
+ Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(7.926e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.08
+ 
+(8.542e-007s)
+
+ 
+ </td>
+</tr>
+</tbody>
+<tbody class="footnotes"><tr><td colspan="3">
+<div class="footnote">[<a name="ftn.id779990" href="#id779990">1</a>] 
+ 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.
+ </div>
+<div class="footnote">[<a name="ftn.id780839" href="#id780839">2</a>] 
+ 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
+ </div>
+</td></tr></tbody>
+</table></div>
+</div>
+ <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>
+
+ 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.
+ 
+<div class="table">
+<a name="id781314"></a>Table 42. A Comparison to the R Statistical Library on Linux
+<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>
+ 
+ Statistical Function
+ 
+ </th>
+<th>
+ 
+ Boost
+ 
+ </th>
+<th>
+ 
+ R
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Beta Distribution
+ CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.71
+ 
+(3.508e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(2.050e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Beta Distribution
+ Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.294e-005s)
+
+ 
+ </td>
+<td>
+ 
+ 
+44.06
+ [<a name="id781453" href="#ftn.id781453">1</a>]
+ 
+ 
+(5.701e-004s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/binomial_dist.html" title="Binomial Distribution">Binomial
+ Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.22
+ 
+(1.342e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.104e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/binomial_dist.html" title="Binomial Distribution">Binomial
+ Distribution</a> Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.36
+ 
+(7.083e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(5.194e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/cauchy_dist.html" title="Cauchy-Lorentz Distribution">Cauchy
+ Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.372e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.47
+ 
+(2.017e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/cauchy_dist.html" title="Cauchy-Lorentz Distribution">Cauchy
+ Distribution</a> Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.542e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.14
+ 
+(1.752e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/chi_squared_dist.html" title="Chi Squared Distribution">Chi
+ Squared Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.04
+ 
+(1.820e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.753e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/chi_squared_dist.html" title="Chi Squared Distribution">Chi
+ Squared Distribution</a> Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.39
+ 
+(9.345e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(6.728e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/exp_dist.html" title="Exponential Distribution">Exponential
+ Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(2.195e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.17
+ 
+(2.561e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/exp_dist.html" title="Exponential Distribution">Exponential
+ Distribution</a> Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.123e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.03
+ 
+(1.155e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Fisher F Distribution
+ CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(2.744e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.08
+ 
+(2.970e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Fisher F Distribution
+ Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.14
+ 
+(1.550e-005s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.359e-005s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Gamma Distribution
+ CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.29
+ 
+(2.578e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.992e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Gamma Distribution
+ Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.77
+ 
+(1.020e-005s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(5.757e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/lognormal_dist.html" title="Log Normal Distribution">Log-normal
+ Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.782e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+2.00
+ 
+(3.564e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/lognormal_dist.html" title="Log Normal Distribution">Log-normal
+ Distribution</a> Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(7.093e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.07
+ 
+(7.607e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
+ Binomial Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.03
+ 
+(2.209e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(2.141e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/negative_binomial_dist.html" title="Negative Binomial Distribution">Negative
+ Binomial Distribution</a> Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.826e-005s)
+
+ 
+ </td>
+<td>
+ 
+ 
+30.07
+ [<a name="id782298" href="#ftn.id782298">2</a>]
+ 
+ 
+(5.490e-004s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/normal_dist.html" title="Normal (Gaussian) Distribution">Normal
+ Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(8.542e-008s)
+
+ 
+ </td>
+<td>
+ 
+ 
+2.09
+ 
+(1.782e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/normal_dist.html" title="Normal (Gaussian) Distribution">Normal
+ Distribution</a> Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.362e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.26
+ 
+(1.722e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/poisson_dist.html" title="Poisson Distribution">Poisson
+ Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.10
+ 
+(1.953e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.775e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/poisson_dist.html" title="Poisson Distribution">Poisson
+ Distribution</a>
+ 
+ </td>
+<td>
+ 
+ 
+1.12
+ 
+(4.214e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(3.752e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/students_t_dist.html" title="Students t Distribution">Students
+ t Distribution</a> CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.55
+ 
+(2.441e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.576e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <a href="../dist/dist_ref/dists/students_t_dist.html" title="Students t Distribution">Students
+ t Distribution</a> Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.33
+ 
+(3.972e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(2.990e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Weibull Distribution
+ CDF
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(6.640e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.06
+ 
+(7.031e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Weibull Distribution
+ Quantile
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(7.504e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.03
+ 
+(7.710e-007s)
+
+ 
+ </td>
+</tr>
+</tbody>
+<tbody class="footnotes"><tr><td colspan="3">
+<div class="footnote">[<a name="ftn.id781453" href="#id781453">1</a>] 
+ 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.
+ </div>
+<div class="footnote">[<a name="ftn.id782298" href="#id782298">2</a>] 
+ 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
+ </div>
+</td></tr></tbody>
+</table></div>
+</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+<div class="table">
+<a name="id776256"></a>Table 37. Performance Comparison of Release and Debug Settings
+<div class="table-contents"><table class="table" summary="Performance Comparison of Release and Debug Settings">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ Microsoft Visual C++ 8.0
+ 
+ 
+ Debug Settings: /Od /ZI
+ 
+ </th>
+<th>
+ 
+ Microsoft Visual C++ 8.0
+ 
+ 
+ Release settings: /Ox /arch:SSE2
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ erf
+ 
+ </td>
+<td>
+ 
+ 
+16.65
+ 
+(1.028e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(6.173e-008s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ erf_inv
+ 
+ </td>
+<td>
+ 
+ 
+19.28
+ 
+(1.215e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(6.302e-008s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ibeta
+ and ibetac
+ 
+ </td>
+<td>
+ 
+ 
+8.32
+ 
+(1.540e-005s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.852e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ibeta_inv
+ and ibetac_inv
+ 
+ </td>
+<td>
+ 
+ 
+10.25
+ 
+(7.492e-005s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(7.311e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ibeta_inva,
+ ibetac_inva,
+ ibeta_invb
+ and ibetac_invb
+ 
+ </td>
+<td>
+ 
+ 
+8.57
+ 
+(2.441e-004s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(2.847e-005s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ gamma_p
+ and gamma_q
+ 
+ </td>
+<td>
+ 
+ 
+10.98
+ 
+(1.044e-005s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(9.504e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ gamma_p_inv
+ and gamma_q_inv
+ 
+ </td>
+<td>
+ 
+ 
+10.25
+ 
+(3.721e-005s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(3.631e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ gamma_p_inva
+ and gamma_q_inva
+ 
+ </td>
+<td>
+ 
+ 
+11.26
+ 
+(1.124e-004s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(9.982e-006s)
+
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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 "twice as slow as the best performing
+ result". Actual timings in seconds per function call are
+ also shown in parenthesis.
+ 
+
+ 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.
+ 
+<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">
+ 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!
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 
+
+ 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 not speed.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ The two most important things you can do to ensure the best performance
+ from this library are:
+ 
+
+ 
+<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>
+
+ 
+
+ 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.
+ 
+
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ Under boost-path/libs/math/performance you will find
+ a (fairly rudimentary) performance test application for this library.
+ 
+
+ To run this application yourself, build the all the .cpp files in boost-path/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>.
+ 
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Macro
+ 
+ </th>
+<th>
+ 
+ Meaning
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ BOOST_MATH_POLY_METHOD
+ 
+ </td>
+<td>
+ 
+ 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.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ BOOST_MATH_RATIONAL_METHOD
+ 
+ </td>
+<td>
+ 
+ Determines how symmetrical rational functions are evaluated: mostly
+ this only effects how the Lanczos approximation is evaluated, and
+ how the <code class="computeroutput">evaluate_rational</code>
+ function behaves. Define to one of the values 0, 1, 2 or 3: see below
+ for the meaning of these values.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ BOOST_MATH_MAX_POLY_ORDER
+ 
+ </td>
+<td>
+ 
+ The maximum order of polynomial or rational function that will be
+ evaluated by a method other than 0 (a simple "for" loop).
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ BOOST_MATH_INT_TABLE_TYPE(RT, IT)
+ 
+ </td>
+<td>
+ 
+ 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:
+ 
+ 
+ #define BOOST_MATH_INT_TABLE_TYPE(RT, IT) RT
+ 
+ 
+ to boost/math/tools/user.hpp, otherwise the default of:
+ 
+ 
+ #define BOOST_MATH_INT_TABLE_TYPE(RT, IT) IT
+ 
+ 
+ Set in boost/math/config.hpp is fine, and may well result in smaller
+ code.
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+
+ The values to which <code class="computeroutput">BOOST_MATH_POLY_METHOD</code>
+ and <code class="computeroutput">BOOST_MATH_RATIONAL_METHOD</code>
+ may be set are as follows:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Value
+ 
+ </th>
+<th>
+ 
+ Effect
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 0
+ 
+ </td>
+<td>
+ 
+ The polynomial or rational function is evaluated using Horner's method,
+ and a simple for-loop.
+ 
+ 
+ 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">BOOST_MATH_MAX_POLY_ORDER</code>, then
+ this method is always used, irrespective of the value of <code class="computeroutput">BOOST_MATH_POLY_METHOD</code> or <code class="computeroutput">BOOST_MATH_RATIONAL_METHOD</code>.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 1
+ 
+ </td>
+<td>
+ 
+ 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">BOOST_MATH_MAX_POLY_ORDER</code>.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 2
+ 
+ </td>
+<td>
+ 
+ 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">BOOST_MATH_MAX_POLY_ORDER</code>.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 3
+ 
+ </td>
+<td>
+ 
+ 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">BOOST_MATH_MAX_POLY_ORDER</code>.
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+
+ 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.
+ 
+
+ 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.
+ 
+<div class="table">
+<a name="id777935"></a>Table 39. A Comparison of Polynomial Evaluation Methods
+<div class="table-contents"><table class="table" summary="A Comparison of Polynomial Evaluation Methods">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Compiler/platform
+ 
+ </th>
+<th>
+ 
+ Method 0
+ 
+ </th>
+<th>
+ 
+ Method 1
+ 
+ </th>
+<th>
+ 
+ Method 2
+ 
+ </th>
+<th>
+ 
+ Method 3
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Microsoft C++ 8.0, Polynomial evaluation
+ 
+ </td>
+<td>
+ 
+ 
+1.34
+ 
+(1.161e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.13
+ 
+(9.777e-008s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.07
+ 
+(9.289e-008s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(8.678e-008s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Microsoft C++ 8.0, Rational evaluation
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.443e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.03
+ 
+(1.492e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.20
+ 
+(1.736e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.07
+ 
+(1.540e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Intel C++ 10.0 (Windows), Polynomial evaluation
+ 
+ </td>
+<td>
+ 
+ 
+1.03
+ 
+(7.702e-008s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.03
+ 
+(7.702e-008s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(7.446e-008s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.03
+ 
+(7.690e-008s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Intel C++ 10.0 (Windows), Rational evaluation
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.245e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.245e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.18
+ 
+(1.465e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.06
+ 
+(1.318e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ GNU G++ 4.2 (Linux), Polynomial evaluation
+ 
+ </td>
+<td>
+ 
+ 
+1.61
+ 
+(1.220e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.68
+ 
+(1.269e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.23
+ 
+(9.275e-008s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(7.566e-008s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ GNU G++ 4.2 (Linux), Rational evaluation
+ 
+ </td>
+<td>
+ 
+ 
+1.26
+ 
+(1.660e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.33
+ 
+(1.758e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.318e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.15
+ 
+(1.513e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Intel C++ 10.0 (Linux), Polynomial evaluation
+ 
+ </td>
+<td>
+ 
+ 
+1.15
+ 
+(9.154e-008s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.15
+ 
+(9.154e-008s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(7.934e-008s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(7.934e-008s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Intel C++ 10.0 (Linux), Rational evaluation
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.245e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.245e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.35
+ 
+(1.684e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.04
+ 
+(1.294e-007s)
+
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ 
+ There is one final performance tuning option that is available as a compile
+ time policy. Normally when evaluating
+ functions at <code class="computeroutput">double</code> precision,
+ these are actually evaluated at <code class="computeroutput">long
+ double</code> precision internally: this
+ helps to ensure that as close to full <code class="computeroutput">double</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">BOOST_MATH_PROMOTE_DOUBLE_POLICY</code></a>
+ to <code class="computeroutput">false</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>.
+ 
+<div class="table">
+<a name="id778690"></a>Table 40. Performance Comparison with and Without Internal
+ Promotion to long double
+<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>
+ 
+ Function
+ 
+ </th>
+<th>
+ 
+ GCC 4.2 , Linux
+ 
+ 
+ (with internal promotion of double to long double).
+ 
+ </th>
+<th>
+ 
+ GCC 4.2, Linux
+ 
+ 
+ (without promotion of double).
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ erf
+ 
+ </td>
+<td>
+ 
+ 
+1.48
+ 
+(1.387e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(9.377e-008s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ erf_inv
+ 
+ </td>
+<td>
+ 
+ 
+1.11
+ 
+(4.009e-007s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(3.598e-007s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ibeta
+ and ibetac
+ 
+ </td>
+<td>
+ 
+ 
+1.29
+ 
+(5.354e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(4.137e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ibeta_inv
+ and ibetac_inv
+ 
+ </td>
+<td>
+ 
+ 
+1.44
+ 
+(2.220e-005s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(1.538e-005s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ ibeta_inva,
+ ibetac_inva,
+ ibeta_invb
+ and ibetac_invb
+ 
+ </td>
+<td>
+ 
+ 
+1.25
+ 
+(7.009e-005s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(5.607e-005s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ gamma_p
+ and gamma_q
+ 
+ </td>
+<td>
+ 
+ 
+1.26
+ 
+(3.116e-006s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(2.464e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ gamma_p_inv
+ and gamma_q_inv
+ 
+ </td>
+<td>
+ 
+ 
+1.27
+ 
+(1.178e-005s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(9.291e-006s)
+
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ gamma_p_inva
+ and gamma_q_inva
+ 
+ </td>
+<td>
+ 
+ 
+1.20
+ 
+(2.765e-005s)
+
+ 
+ </td>
+<td>
+ 
+ 
+1.00
+ 
+(2.311e-005s)
+
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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> Policy Overview</dt>
+<dt> Policy Tutorial</dt>
+<dd><dl>
+<dt><a href="policy/pol_tutorial/what_is_a_policy.html">
+ So Just What is a Policy Anyway?</a></dt>
+<dt><a href="policy/pol_tutorial/policy_tut_defaults.html">
+ Policies Have Sensible Defaults</a></dt>
+<dt><a href="policy/pol_tutorial/policy_usage.html"> So
+ How are Policies Used Anyway?</a></dt>
+<dt><a href="policy/pol_tutorial/changing_policy_defaults.html">
+ Changing the Policy Defaults</a></dt>
+<dt><a href="policy/pol_tutorial/ad_hoc_dist_policies.html">
+ Setting Policies for Distributions on an Ad Hoc Basis</a></dt>
+<dt><a href="policy/pol_tutorial/ad_hoc_sf_policies.html">
+ Changing the Policy on an Ad Hoc Basis for the Special Functions</a></dt>
+<dt><a href="policy/pol_tutorial/namespace_policies.html">
+ Setting Policies at Namespace or Translation Unit Scope</a></dt>
+<dt><a href="policy/pol_tutorial/user_def_err_pol.html">
+ Calling User Defined Error Handlers</a></dt>
+<dt><a href="policy/pol_tutorial/understand_dis_quant.html">
+ Understanding Quantiles of Discrete Distributions</a></dt>
+</dl></dd>
+<dt> Policy Reference</dt>
+<dd><dl>
+<dt><a href="policy/pol_ref/error_handling_policies.html">
+ Error Handling Policies</a></dt>
+<dt><a href="policy/pol_ref/internal_promotion.html"> Internal
+ Promotion Policies</a></dt>
+<dt><a href="policy/pol_ref/assert_undefined.html"> Mathematically
+ Undefined Function Policies</a></dt>
+<dt><a href="policy/pol_ref/discrete_quant_ref.html"> Discrete
+ Quantile Policies</a></dt>
+<dt><a href="policy/pol_ref/precision_pol.html"> Precision
+ Policies</a></dt>
+<dt><a href="policy/pol_ref/iteration_pol.html"> Iteration
+ Limits Policies</a></dt>
+<dt><a href="policy/pol_ref/policy_defaults.html"> Using
+ macros to Change the Policy Defaults</a></dt>
+<dt><a href="policy/pol_ref/namespace_pol.html"> Setting
+ Polices at Namespace Scope</a></dt>
+<dt><a href="policy/pol_ref/pol_ref_ref.html"> Policy Class
+ Reference</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 
+
+ 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>.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Policies are a compile-time mechanism that allow you to change error-handling
+ or calculation precision either program wide, or at the call site.
+ 
+
+ 
+
+ Although the policy mechanism itself is rather complicated, in practice
+ it is easy to use, and very flexible.
+ 
+
+ 
+
+ Using policies you can control:
+ 
+
+ 
+<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>
+
+ 
+
+ You can control policies:
+ 
+
+ 
+<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>
+
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="pol_ref/error_handling_policies.html">
+ Error Handling Policies</a></dt>
+<dt><a href="pol_ref/internal_promotion.html"> Internal
+ Promotion Policies</a></dt>
+<dt><a href="pol_ref/assert_undefined.html"> Mathematically
+ Undefined Function Policies</a></dt>
+<dt><a href="pol_ref/discrete_quant_ref.html"> Discrete
+ Quantile Policies</a></dt>
+<dt><a href="pol_ref/precision_pol.html"> Precision
+ Policies</a></dt>
+<dt><a href="pol_ref/iteration_pol.html"> Iteration
+ Limits Policies</a></dt>
+<dt><a href="pol_ref/policy_defaults.html"> Using
+ macros to Change the Policy Defaults</a></dt>
+<dt><a href="pol_ref/namespace_pol.html"> Setting
+ Polices at Namespace Scope</a></dt>
+<dt><a href="pol_ref/pol_ref_ref.html"> Policy Class
+ Reference</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ For example, the Cauchy distribution does not have a mean, so what should
+ 
+<pre class="programlisting">
+mean(cauchy<>());
+</pre>
+
+ return, and should such an expression even compile at all?
+ 
+
+ 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).
+ 
+
+ This behaviour is controlled by the <code class="computeroutput">assert_undefined<></code> policy:
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{ namespace policies {
+
+template <bool b>
+class assert_undefined;
+
+}}} //namespaces
+</pre>
+
+ For example:
+ 
+<pre class="programlisting">
+#include <boost/math/distributions/cauchy.hpp>
+
+using namespace boost::math::policies;
+using namespace boost::math;
+
+// This will not compile, cauchy has no mean!
+double m1 = mean(cauchy());
+
+// This will compile, but raises a domain error!
+double m2 = mean(cauchy_distribution<double, policy<assert_undefined<false> > >());
+</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ If a statistical distribution is discrete 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">discrete_quantile</code> policy defines how
+ discrete quantiles work, and how integer results are rounded:
+ 
+<pre class="programlisting">
+enum discrete_quantile_policy_type
+{
+ real,
+ integer_round_outwards, // default
+ integer_round_inwards,
+ integer_round_down,
+ integer_round_up,
+ integer_round_nearest
+};
+
+template <discrete_quantile_policy_type>
+struct discrete_quantile;
+</pre>
+
+ The values that <code class="computeroutput">discrete_quantile</code>
+ can take have the following meanings:
+ 
+<a name="math_toolkit.policy.pol_ref.discrete_quant_ref.real"></a><h6>
+<a name="id766478"></a>
+ real
+ </h6>
+
+ Ignores the discreteness of the distribution, and returns a real-valued
+ result. For example:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/negative_binomial.hpp>
+
+using namespace boost::math;
+using namespace boost::math::policies;
+
+typedef negative_binomial_distribution<
+ double,
+ policy<discrete_quantile<integer_round_inwards> >
+ > dist_type;
+
+// Lower quantile:
+double x = quantile(dist_type(20, 0.3), 0.05);
+// Upper quantile:
+double y = quantile(complement(dist_type(20, 0.3), 0.05));
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ Results in <code class="computeroutput">x =
+ 27.3898</code> and <code class="computeroutput">y
+ = 68.1584</code>.
+ 
+<a name="math_toolkit.policy.pol_ref.discrete_quant_ref.integer_round_outwards"></a><h6>
+<a name="id766971"></a>
+ integer_round_outwards
+ </h6>
+
+ This is the default policy: an integer value is returned so that:
+ 
+<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>
+
+ This is normally the safest rounding policy, since it ensures that both
+ one and two sided intervals are guaranteed to have at least
+ the requested coverage. For example:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/negative_binomial.hpp>
+
+using namespace boost::math;
+
+// Lower quantile rounded down:
+double x = quantile(negative_binomial(20, 0.3), 0.05);
+// Upper quantile rounded up:
+double y = quantile(complement(negative_binomial(20, 0.3), 0.05));
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ Results in <code class="computeroutput">x =
+ 27</code> (rounded down from 27.3898) and
+ <code class="computeroutput">y =
+ 69</code> (rounded up from 68.1584).
+ 
+
+ The variables x and y are now defined so that:
+ 
+<pre class="programlisting">
+cdf(negative_binomial(20), x) <= 0.05
+cdf(negative_binomial(20), y) >= 0.95
+</pre>
+
+ In other words we guarantee at least 90% coverage in the central
+ region overall, and also no more than 5% coverage
+ in each tail.
+ 
+<a name="math_toolkit.policy.pol_ref.discrete_quant_ref.integer_round_inwards"></a><h6>
+<a name="id767498"></a>
+ integer_round_inwards
+ </h6>
+
+ This is the opposite of integer_round_outwards: an
+ integer value is returned so that:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Lower quantiles (where the probability is less than 0.5) are rounded
+ up.
+ </li>
+<li>
+ Upper quantiles (where the probability is greater than 0.5) are rounded
+ down.
+ </li>
+</ul></div>
+
+ For example:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/negative_binomial.hpp>
+
+using namespace boost::math;
+using namespace boost::math::policies;
+
+typedef negative_binomial_distribution<
+ double,
+ policy<discrete_quantile<integer_round_inwards> >
+ > dist_type;
+
+// Lower quantile rounded up:
+double x = quantile(dist_type(20, 0.3), 0.05);
+// Upper quantile rounded down:
+double y = quantile(complement(dist_type(20, 0.3), 0.05));
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ Results in <code class="computeroutput">x =
+ 28</code> (rounded up from 27.3898) and
+ <code class="computeroutput">y =
+ 68</code> (rounded down from 68.1584).
+ 
+
+ The variables x and y are now defined so that:
+ 
+<pre class="programlisting">
+cdf(negative_binomial(20), x) >= 0.05
+cdf(negative_binomial(20), y) <= 0.95
+</pre>
+
+ In other words we guarantee at no more than 90% coverage in the
+ central region overall, and also at least 5% coverage
+ in each tail.
+ 
+<a name="math_toolkit.policy.pol_ref.discrete_quant_ref.integer_round_down"></a><h6>
+<a name="id768161"></a>
+ integer_round_down
+ </h6>
+
+ Always rounds down to an integer value, no matter whether it's an upper
+ or a lower quantile.
+ 
+<a name="math_toolkit.policy.pol_ref.discrete_quant_ref.integer_round_up"></a><h6>
+<a name="id768192"></a>
+ integer_round_up
+ </h6>
+
+ Always rounds up to an integer value, no matter whether it's an upper or
+ a lower quantile.
+ 
+<a name="math_toolkit.policy.pol_ref.discrete_quant_ref.integer_round_nearest"></a><h6>
+<a name="id768224"></a>
+ integer_round_nearest
+ </h6>
+
+ Always rounds to the nearest integer value, no matter whether it's an upper
+ or a lower quantile. This will produce the requested coverage in
+ the average case, but for any specific example may results in
+ either significantly more or less coverage than the requested amount. For
+ example:
+ 
+
+ For example:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/negative_binomial.hpp>
+
+using namespace boost::math;
+using namespace boost::math::policies;
+
+typedef negative_binomial_distribution<
+ double,
+ policy<discrete_quantile<integer_round_nearest> >
+ > dist_type;
+
+// Lower quantile rounded up:
+double x = quantile(dist_type(20, 0.3), 0.05);
+// Upper quantile rounded down:
+double y = quantile(complement(dist_type(20, 0.3), 0.05));
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ Results in <code class="computeroutput">x =
+ 27</code> (rounded from 27.3898) and <code class="computeroutput">y = 68</code> (rounded from 68.1584).
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ There are two orthogonal aspects to error handling:
+ 
+<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>
+
+ What to do with the error is encapsulated by an enumerated type:
+ 
+<pre class="programlisting">
+namespace boost { namespace math { namespace policies {
+
+enum error_policy_type
+{
+ throw_on_error = 0, // throw an exception.
+ errno_on_error = 1, // set ::errno & return 0, NaN, infinity or best guess.
+ ignore_error = 2, // return 0, NaN, infinity or best guess.
+ user_error = 3 // call a user-defined error handler.
+};
+
+}}} // namespaces
+</pre>
+
+ The various enumerated values have the following meanings:
+ 
+<a name="math_toolkit.policy.pol_ref.error_handling_policies.throw_on_error"></a><h6>
+<a name="id761268"></a>
+ throw_on_error
+ </h6>
+
+ Will throw one of the following exceptions, depending upon the type of
+ the error:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Error Type
+ 
+ </th>
+<th>
+ 
+ Exception
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Domain Error
+ 
+ </td>
+<td>
+ 
+ std::domain_error
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Pole Error
+ 
+ </td>
+<td>
+ 
+ std::domain_error
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Overflow Error
+ 
+ </td>
+<td>
+ 
+ std::overflow_error
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Underflow Error
+ 
+ </td>
+<td>
+ 
+ std::underflow_error
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Denorm Error
+ 
+ </td>
+<td>
+ 
+ std::underflow_error
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Evaluation Error
+ 
+ </td>
+<td>
+ 
+ boost::math::evaluation_error
+ 
+ </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>
+
+ Will set global <code class="computeroutput">::errno</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:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Error Type
+ 
+ </th>
+<th>
+ 
+ errno value
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Domain Error
+ 
+ </td>
+<td>
+ 
+ EDOM
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Pole Error
+ 
+ </td>
+<td>
+ 
+ EDOM
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Overflow Error
+ 
+ </td>
+<td>
+ 
+ ERANGE
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Underflow Error
+ 
+ </td>
+<td>
+ 
+ ERANGE
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Denorm Error
+ 
+ </td>
+<td>
+ 
+ ERANGE
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Evaluation Error
+ 
+ </td>
+<td>
+ 
+ EDOM
+ 
+ </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>
+
+ Will return a one of the values below depending on the error type (<code class="computeroutput">::errno</code>
+ is NOT changed)::
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Error Type
+ 
+ </th>
+<th>
+ 
+ Returned Value
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Domain Error
+ 
+ </td>
+<td>
+ 
+ std::numeric_limits<T>::quiet_NaN()
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Pole Error
+ 
+ </td>
+<td>
+ 
+ std::numeric_limits<T>::quiet_NaN()
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Overflow Error
+ 
+ </td>
+<td>
+ 
+ std::numeric_limits<T>::infinity()
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Underflow Error
+ 
+ </td>
+<td>
+ 
+ 0
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Denorm Error
+ 
+ </td>
+<td>
+ 
+ The denormalised value.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Evaluation Error
+ 
+ </td>
+<td>
+ 
+ The best guess as to the result: which may be significantly in
+ error.
+ 
+ </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>
+
+ 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:
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{ namespace policies{
+
+template <class T>
+T user_domain_error(const char* function, const char* message, const T& val);
+
+template <class T>
+T user_pole_error(const char* function, const char* message, const T& val);
+
+template <class T>
+T user_overflow_error(const char* function, const char* message, const T& val);
+
+template <class T>
+T user_underflow_error(const char* function, const char* message, const T& val);
+
+template <class T>
+T user_denorm_error(const char* function, const char* message, const T& val);
+
+template <class T>
+T user_evaluation_error(const char* function, const char* message, const T& val);
+
+}}} // namespaces
+</pre>
+
+ Note that the strings function and message
+ 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 function string, and if
+ there is a %1% specifier in the message string then
+ it should be replaced with the value of val.
+ 
+
+ 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>.
+ 
+<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>
+
+ There are five kinds of error reported by this library, which are summarised
+ in the following table:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Error Type
+ 
+ </th>
+<th>
+ 
+ Policy Class
+ 
+ </th>
+<th>
+ 
+ Description
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Domain Error
+ 
+ </td>
+<td>
+ 
+ boost::math::policies::domain_error<action>
+ 
+ </td>
+<td>
+ 
+ Raised when more or more arguments are outside the defined range
+ of the function.
+ 
+ 
+ Defaults to <code class="computeroutput">boost::math::policies::domain_error<throw_on_error></code>
+ 
+ 
+ When the action is set to throw_on_error then
+ throws <code class="computeroutput">std::domain_error</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Pole Error
+ 
+ </td>
+<td>
+ 
+ boost::math::policies::pole_error<action>
+ 
+ </td>
+<td>
+ 
+ Raised when more or more arguments would cause the function to
+ be evaluated at a pole.
+ 
+ 
+ Defaults to <code class="computeroutput">boost::math::policies::pole_error<throw_on_error></code>
+ 
+ 
+ When the action is throw_on_error then throw
+ a <code class="computeroutput">std::domain_error</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Overflow Error
+ 
+ </td>
+<td>
+ 
+ boost::math::policies::overflow_error<action>
+ 
+ </td>
+<td>
+ 
+ Raised when the result of the function is outside the representable
+ range of the floating point type used.
+ 
+ 
+ Defaults to <code class="computeroutput">boost::math::policies::overflow_error<throw_on_error></code>.
+ 
+ 
+ When the action is throw_on_error then throws
+ a <code class="computeroutput">std::overflow_error</code>.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Underflow Error
+ 
+ </td>
+<td>
+ 
+ boost::math::policies::underflow_error<action>
+ 
+ </td>
+<td>
+ 
+ Raised when the result of the function is too small to be represented
+ in the floating point type used.
+ 
+ 
+ Defaults to <code class="computeroutput">boost::math::policies::underflow_error<ignore_error></code>
+ 
+ 
+ When the specified action is throw_on_error
+ then throws a <code class="computeroutput">std::underflow_error</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Denorm Error
+ 
+ </td>
+<td>
+ 
+ boost::math::policies::denorm_error<action>
+ 
+ </td>
+<td>
+ 
+ Raised when the result of the function is a denormalised value.
+ 
+ 
+ Defaults to <code class="computeroutput">boost::math::policies::denorm_error<ignore_error></code>
+ 
+ 
+ When the action is throw_on_error then throws
+ a <code class="computeroutput">std::underflow_error</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Evaluation Error
+ 
+ </td>
+<td>
+ 
+ boost::math::policies::evaluation_error<action>
+ 
+ </td>
+<td>
+ 
+ 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!
+ 
+ 
+ Defaults to <code class="computeroutput">boost::math::policies::evaluation_error<throw_on_error></code>
+ 
+ 
+ When the action is throw_on_error then throws
+ <code class="computeroutput">boost::math::evaluation_error</code>
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.policy.pol_ref.error_handling_policies.examples"></a><h5>
+<a name="id763630"></a>
+ Examples
+ </h5>
+
+ Suppose we want a call to <code class="computeroutput">tgamma</code>
+ to behave in a C-compatible way and set global <code class="computeroutput">::errno</code> rather than throw an exception,
+ we can achieve this at the call site using:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/gamma.hpp>
+
+using namespace boost::math::policies;
+using namespace boost::math;
+
+// Define a policy:
+typedef policy<
+ domain_error<errno_on_error>,
+ pole_error<errno_on_error>,
+ overflow_error<errno_on_error>,
+ policies::evaluation_error<errno_on_error>
+ > my_policy;
+
+// call the function:
+double t1 = tgamma(some_value, my_policy());
+
+// Alternatively we could use make_policy and define everything at the call site:
+double t2 = tgamma(some_value, make_policy(
+ domain_error<errno_on_error>(),
+ pole_error<errno_on_error>(),
+ overflow_error<errno_on_error>(),
+ policies::evaluation_error<errno_on_error>()
+ ));
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ Suppose we want a statistical distribution to return infinities, rather
+ than throw exceptions, then we can use:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/normal.hpp>
+
+using namespace boost::math::policies;
+using namespace boost::math;
+
+// Define a policy:
+typedef policy<
+ overflow_error<ignore_error>
+ > my_policy;
+
+// Define the distribution:
+typedef normal_distribution<double, my_policy> my_norm;
+
+// Get a quantile:
+double q = quantile(my_norm(), 0.05);
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ Normally when evaluating a function at say <code class="computeroutput">float</code>
+ precision, maximal accuracy is assured by conducting the calculation at
+ <code class="computeroutput">double</code> precision internally,
+ and then rounding the result. There are two policies that effect whether
+ internal promotion takes place or not:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Policy
+ 
+ </th>
+<th>
+ 
+ Meaning
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ <code class="computeroutput">boost::math::policies::promote_float<B></code>
+ 
+ </td>
+<td>
+ 
+ Indicates whether <code class="computeroutput">float</code>
+ arguments should be promoted to <code class="computeroutput">double</code>
+ precision internally: defaults to <code class="computeroutput">boost::math::policies::promote_float<true></code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">boost::math::policies::promote_double<B></code>
+ 
+ </td>
+<td>
+ 
+ Indicates whether <code class="computeroutput">double</code>
+ arguments should be promoted to <code class="computeroutput">long
+ double</code> precision internally:
+ defaults to <code class="computeroutput">boost::math::policies::promote_double<true></code>
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.policy.pol_ref.internal_promotion.examples"></a><h5>
+<a name="id764959"></a>
+ Examples
+ </h5>
+
+ Suppose we want <code class="computeroutput">tgamma</code>
+ to be evaluated without internal promotion to <code class="computeroutput">long
+ double</code>, then we could use:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/gamma.hpp>
+
+using namespace boost::math::policies;
+using namespace boost::math;
+
+// Define a policy:
+typedef policy<
+ promote_double<false>
+ > my_policy;
+
+// Call the function:
+double t1 = tgamma(some_value, my_policy());
+
+// Alternatively we could use make_policy and define everything at the call site:
+double t2 = tgamma(some_value, make_policy(promote_double<false>()));
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ Alternatively, suppose we want a distribution to perform calculations without
+ promoting <code class="computeroutput">float</code> to <code class="computeroutput">double</code>, then we could use:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/normal.hpp>
+
+using namespace boost::math::policies;
+using namespace boost::math;
+
+// Define a policy:
+typedef policy<
+ promote_float<false>
+ > my_policy;
+
+// Define the distribution:
+typedef normal_distribution<float, my_policy> my_norm;
+
+// Get a quantile:
+float q = quantile(my_norm(), 0.05f);
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ There are two policies that effect the iterative algorithms used to implement
+ the special functions in this library:
+ 
+<pre class="programlisting">
+template <unsigned long limit = BOOST_MATH_MAX_SERIES_ITERATION_POLICY>
+class max_series_iterations;
+
+template <unsigned long limit = BOOST_MATH_MAX_ROOT_ITERATION_POLICY>
+class max_root_iterations;
+</pre>
+
+ The class <code class="computeroutput">max_series_iterations</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.
+ 
+
+ The class <code class="computeroutput">max_root_iterations</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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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:
+ 
+<pre class="programlisting">
+BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS(Policy)
+</pre>
+
+ and:
+ 
+<pre class="programlisting">
+BOOST_MATH_DECLARE_DISTRIBUTIONS(Type, Policy)
+</pre>
+
+ You can use either of these macros after including any special function
+ or distribution header. For example:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/gamma.hpp>
+
+namespace myspace{
+
+using namespace boost::math::policies;
+
+// Define a policy that does not throw on overflow:
+typedef policy<overflow_error<errno_on_error> > my_policy;
+
+// Define the special functions in this scope to use the policy:
+BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS(my_policy)
+
+}
+
+//
+// Now we can use myspace::tgamma etc.
+// They will automatically use "my_policy":
+//
+double t = myspace::tgamma(30.0); // will not throw on overflow
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ In this example, using BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS results in
+ a set of thin inline forwarding functions being defined:
+ 
+<pre class="programlisting">
+template <class T>
+inline T tgamma(T a){ return ::boost::math::tgamma(a, mypolicy()); }
+
+template <class T>
+inline T lgamma(T a) ( return ::boost::math::lgamma(a, mypolicy()); }
+</pre>
+
+ 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.
+ 
+
+ We can do the same thing with the distributions, but this time we need
+ to specify the floating-point type to use:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/cauchy.hpp>
+
+namespace myspace{
+
+using namespace boost::math::policies;
+
+// Define a policy to use, in this case we want all the distribution
+// accessor functions to compile, even if they are mathematically
+// undefined:
+typedef policy<assert_undefined<false> > my_policy;
+
+BOOST_MATH_DECLARE_DISTRIBUTIONS(double, my_policy)
+
+}
+
+// Now we can use myspace::cauchy etc, which will use policy
+// myspace::mypolicy:
+//
+// This compiles but raises a domain error at runtime:
+//
+void test_cauchy()
+{
+ try
+ {
+ double d = mean(myspace::cauchy());
+ }
+ catch(const std::domain_error& e)
+ {
+ std::cout << e.what() << std::endl;
+ }
+}
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ In this example the result of BOOST_MATH_DECLARE_DISTRIBUTIONS is to declare
+ a typedef for each distribution like this:
+ 
+<pre class="programlisting">
+typedef boost::math::cauchy_distribution<double, my_policy> cauchy;
+tyepdef boost::math::gamma_distribution<double, my_policy> gamma;
+</pre>
+
+ and so on. The name given to each typedef is the name of the distribution
+ with the "_distribution" suffix removed.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ There's very little to say here, the <code class="computeroutput">policy</code>
+ class is just a rag-bag compile-time container for a collection of policies:
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/policies/policy.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{
+namespace math{
+namespace policies
+
+template <class A1 = default_policy,
+ class A2 = default_policy,
+ class A3 = default_policy,
+ class A4 = default_policy,
+ class A5 = default_policy,
+ class A6 = default_policy,
+ class A7 = default_policy,
+ class A8 = default_policy,
+ class A9 = default_policy,
+ class A10 = default_policy,
+ class A11 = default_policy>
+struct policy
+{
+public:
+ typedef computed-from-template-arguments domain_error_type;
+ typedef computed-from-template-arguments pole_error_type;
+ typedef computed-from-template-arguments overflow_error_type;
+ typedef computed-from-template-arguments underflow_error_type;
+ typedef computed-from-template-arguments denorm_error_type;
+ typedef computed-from-template-arguments evaluation_error_type;
+ typedef computed-from-template-arguments precision_type;
+ typedef computed-from-template-arguments promote_float_type;
+ typedef computed-from-template-arguments promote_double_type;
+ typedef computed-from-template-arguments discrete_quantile_type;
+ typedef computed-from-template-arguments assert_undefined_type;
+};
+
+template <...argument list...>
+typename normalise<policy<>, A1>::type make_policy(...argument list..);
+
+template <class Policy,
+ class A1 = default_policy,
+ class A2 = default_policy,
+ class A3 = default_policy,
+ class A4 = default_policy,
+ class A5 = default_policy,
+ class A6 = default_policy,
+ class A7 = default_policy,
+ class A8 = default_policy,
+ class A9 = default_policy,
+ class A10 = default_policy,
+ class A11 = default_policy>
+struct normalise
+{
+ typedef computed-from-template-arguments type;
+};
+</pre>
+
+ The member typedefs of class <code class="computeroutput">policy</code>
+ are intended for internal use but are documented briefly here for the sake
+ of completeness.
+ 
+<pre class="programlisting">
+policy<...>::domain_error_type
+</pre>
+
+ Specifies how domain errors are handled, will be an instance of <code class="computeroutput">boost::math::policies::domain_error<></code>
+ with the template argument to <code class="computeroutput">domain_error</code>
+ one of the <code class="computeroutput">error_policy_type</code>
+ enumerated values.
+ 
+<pre class="programlisting">
+policy<...>::pole_error_type
+</pre>
+
+ Specifies how pole-errors are handled, will be an instance of <code class="computeroutput">boost::math::policies::pole_error<></code>
+ with the template argument to <code class="computeroutput">pole_error</code>
+ one of the <code class="computeroutput">error_policy_type</code>
+ enumerated values.
+ 
+<pre class="programlisting">
+policy<...>::overflow_error_type
+</pre>
+
+ Specifies how overflow errors are handled, will be an instance of <code class="computeroutput">boost::math::policies::overflow_error<></code>
+ with the template argument to <code class="computeroutput">overflow_error</code>
+ one of the <code class="computeroutput">error_policy_type</code>
+ enumerated values.
+ 
+<pre class="programlisting">
+policy<...>::underflow_error_type
+</pre>
+
+ Specifies how underflow errors are handled, will be an instance of <code class="computeroutput">boost::math::policies::underflow_error<></code>
+ with the template argument to <code class="computeroutput">underflow_error</code>
+ one of the <code class="computeroutput">error_policy_type</code>
+ enumerated values.
+ 
+<pre class="programlisting">
+policy<...>::denorm_error_type
+</pre>
+
+ Specifies how denorm errors are handled, will be an instance of <code class="computeroutput">boost::math::policies::denorm_error<></code>
+ with the template argument to <code class="computeroutput">denorm_error</code>
+ one of the <code class="computeroutput">error_policy_type</code>
+ enumerated values.
+ 
+<pre class="programlisting">
+policy<...>::evaluation_error_type
+</pre>
+
+ Specifies how evaluation errors are handled, will be an instance of <code class="computeroutput">boost::math::policies::evaluation_error<></code>
+ with the template argument to <code class="computeroutput">evaluation_error</code>
+ one of the <code class="computeroutput">error_policy_type</code>
+ enumerated values.
+ 
+<pre class="programlisting">
+policy<...>::precision_type
+</pre>
+
+ 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">boost::math::policies::digits2<N></code>
+ which in turn inherits from <code class="computeroutput">boost::mpl::int_<N></code>.
+ 
+<pre class="programlisting">
+policy<...>::promote_float_type
+</pre>
+
+ Specifies whether or not to promote <code class="computeroutput">float</code>
+ arguments to <code class="computeroutput">double</code> precision
+ internally. Will be an instance of <code class="computeroutput">boost::math::policies::promote_float<B></code> which in turn inherits from <code class="computeroutput">boost::mpl::bool_<B></code>.
+ 
+<pre class="programlisting">
+policy<...>::promote_double_type
+</pre>
+
+ Specifies whether or not to promote <code class="computeroutput">double</code>
+ arguments to <code class="computeroutput">long double</code>
+ precision internally. Will be an instance of <code class="computeroutput">boost::math::policies::promote_float<B></code> which in turn inherits from <code class="computeroutput">boost::mpl::bool_<B></code>.
+ 
+<pre class="programlisting">
+policy<...>::discrete_quantile_type
+</pre>
+
+ Specifies how discrete quantiles are evaluated, will be an instance of
+ <code class="computeroutput">boost::math::policies::discrete_quantile<></code>
+ instantiated with one of the <code class="computeroutput">discrete_quantile_policy_type</code>
+ enumerated type.
+ 
+<pre class="programlisting">
+policy<...>::assert_undefined_type
+</pre>
+
+ 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">boost::math::policies::assert_undefined<B></code>
+ which in turn inherits from <code class="computeroutput">boost::math::mpl::bool_<B></code>.
+ 
+<pre class="programlisting">
+template <...argument list...>
+typename normalise<policy<>, A1>::type make_policy(...argument list..);
+</pre>
+
+ <code class="computeroutput">make_policy</code> is a helper
+ function that converts a list of policies into a normalised <code class="computeroutput">policy</code> class.
+ 
+<pre class="programlisting">
+template <class Policy,
+ class A1 = default_policy,
+ class A2 = default_policy,
+ class A3 = default_policy,
+ class A4 = default_policy,
+ class A5 = default_policy,
+ class A6 = default_policy,
+ class A7 = default_policy,
+ class A8 = default_policy,
+ class A9 = default_policy,
+ class A10 = default_policy,
+ class A11 = default_policy>
+struct normalise
+{
+ typedef computed-from-template-arguments type;
+};
+</pre>
+
+ The <code class="computeroutput">normalise</code> class template
+ converts one instantiation of the <code class="computeroutput">policy</code>
+ class into a normalised form. This is used internally to reduce code bloat:
+ so that instantiating a special function on <code class="computeroutput">policy<A,B></code>
+ or <code class="computeroutput">policy<B,A></code> actually both generate the same code
+ internally.
+ 
+
+ Further more, <code class="computeroutput">normalise</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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ You can use the various macros below to change any (or all) of the policies.
+ 
+
+ You can make a local change by placing a macro definition before
+ a function or distribution #include.
+ 
+<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">
+ 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
+ every translation unit.
+ </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">
+ 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!
+ </td></tr>
+</table></div>
+
+ If you want to alter the defaults for any or all of the policies for all functions and distributions, installation-wide,
+ then you can do so by defining various macros in boost/math/tools/user.hpp.
+ 
+<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>
+
+ Defines what happens when a domain error occurs, if not defined then defaults
+ to <code class="computeroutput">throw_on_error</code>, but
+ can be set to any of the enumerated actions for error handing: <code class="computeroutput">throw_on_error</code>, <code class="computeroutput">errno_on_error</code>,
+ <code class="computeroutput">ignore_error</code> or <code class="computeroutput">user_error</code>.
+ 
+<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>
+
+ Defines what happens when a pole error occurs, if not defined then defaults
+ to <code class="computeroutput">throw_on_error</code>, but
+ can be set to any of the enumerated actions for error handing: <code class="computeroutput">throw_on_error</code>, <code class="computeroutput">errno_on_error</code>,
+ <code class="computeroutput">ignore_error</code> or <code class="computeroutput">user_error</code>.
+ 
+<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>
+
+ Defines what happens when an overflow error occurs, if not defined then
+ defaults to <code class="computeroutput">throw_on_error</code>,
+ but can be set to any of the enumerated actions for error handing: <code class="computeroutput">throw_on_error</code>, <code class="computeroutput">errno_on_error</code>,
+ <code class="computeroutput">ignore_error</code> or <code class="computeroutput">user_error</code>.
+ 
+<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>
+
+ Defines what happens when an internal evaluation error occurs, if not defined
+ then defaults to <code class="computeroutput">throw_on_error</code>,
+ but can be set to any of the enumerated actions for error handing: <code class="computeroutput">throw_on_error</code>, <code class="computeroutput">errno_on_error</code>,
+ <code class="computeroutput">ignore_error</code> or <code class="computeroutput">user_error</code>.
+ 
+<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>
+
+ Defines what happens when an overflow error occurs, if not defined then
+ defaults to <code class="computeroutput">ignore_error</code>,
+ but can be set to any of the enumerated actions for error handing: <code class="computeroutput">throw_on_error</code>, <code class="computeroutput">errno_on_error</code>,
+ <code class="computeroutput">ignore_error</code> or <code class="computeroutput">user_error</code>.
+ 
+<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>
+
+ Defines what happens when a denormalisation error occurs, if not defined
+ then defaults to <code class="computeroutput">ignore_error</code>,
+ but can be set to any of the enumerated actions for error handing: <code class="computeroutput">throw_on_error</code>, <code class="computeroutput">errno_on_error</code>,
+ <code class="computeroutput">ignore_error</code> or <code class="computeroutput">user_error</code>.
+ 
+<a name="math_toolkit.policy.pol_ref.policy_defaults.boost_math_digits10_policy"></a><h6>
+<a name="id770613"></a>
+ BOOST_MATH_DIGITS10_POLICY
+ </h6>
+
+ Defines how many decimal digits to use in internal computations: defaults
+ to <code class="computeroutput">0</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.
+ 
+<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>
+
+ Determines whether <code class="computeroutput">float</code> types
+ get promoted to <code class="computeroutput">double</code> internally
+ to ensure maximum precision in the result, defaults to <code class="computeroutput">true</code>,
+ but can be set to <code class="computeroutput">false</code> to
+ turn promotion of <code class="computeroutput">float</code>'s
+ off.
+ 
+<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>
+
+ Determines whether <code class="computeroutput">double</code>
+ types get promoted to <code class="computeroutput">long double</code> internally to ensure maximum precision
+ in the result, defaults to <code class="computeroutput">true</code>,
+ but can be set to <code class="computeroutput">false</code> to
+ turn promotion of <code class="computeroutput">double</code>'s
+ off.
+ 
+<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>
+
+ 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">real</code>, <code class="computeroutput">integer_round_outwards</code>,
+ <code class="computeroutput">integer_round_inwards</code>,
+ <code class="computeroutput">integer_round_down</code>, <code class="computeroutput">integer_round_up</code>, <code class="computeroutput">integer_round_nearest</code>.
+ Defaults to <code class="computeroutput">integer_round_outwards</code>.
+ 
+<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>
+
+ 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">true</code>: meaning that any
+ mathematically undefined function will not compile. When set to <code class="computeroutput">false</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.
+ 
+<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>
+
+ Determines how many series iterations a special function is permitted to
+ perform before it gives up and returns an evaluation_error:
+ Defaults to 1000000.
+ 
+<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>
+
+ 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.
+ 
+<a name="math_toolkit.policy.pol_ref.policy_defaults.example"></a><h6>
+<a name="id771118"></a>
+ Example
+ </h6>
+
+ Suppose we want overflow errors to set <code class="computeroutput">::errno</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:
+ 
+<pre class="programlisting">
+#define BOOST_MATH_OVERFLOW_ERROR_POLICY errno_on_error
+#define BOOST_MATH_DISCRETE_QUANTILE_POLICY real
+#define BOOST_MATH_ASSERT_UNDEFINED_POLICY false
+</pre>
+
+ or we could place these definitions before
+ 
+<pre class="programlisting">
+#include <boost/math/distributions/normal.hpp>
+ using boost::math::normal_distribution;
+</pre>
+
+ in a source .cpp file.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ There are two equivalent policies that effect the working precision
+ 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.
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{ namespace policies{
+
+template <int N>
+digits10;
+
+template <int N>
+digits2;
+
+}}} // namespaces
+</pre>
+
+ As you would expect, digits10 specifies the number
+ of decimal digits to use, and digits2 the number of
+ binary digits. Internally, whichever is used, the precision is always converted
+ to binary digits.
+ 
+
+ 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.
+ 
+
+ For example we could calculate <code class="computeroutput">tgamma</code>
+ to approximately 5 decimal digits using:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/gamma.hpp>
+
+using namespace boost::math;
+using namespace boost::math::policies;
+
+typedef policy<digits10<5> > pol;
+
+double t = tgamma(12, pol());
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ Or again using make_policy:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/gamma.hpp>
+
+using namespace boost::math;
+using namespace boost::math::policies;
+
+double t = tgamma(12, policy<digits10<5> >());
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ And for a quantile of a distribution to approximately 25-bit precision:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/normal.hpp>
+
+using namespace boost::math;
+using namespace boost::math::policies;
+
+double q = quantile(
+ normal_distribution<double, policy<digits2<25> > >(),
+ 0.05);
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="pol_tutorial/what_is_a_policy.html">
+ So Just What is a Policy Anyway?</a></dt>
+<dt><a href="pol_tutorial/policy_tut_defaults.html">
+ Policies Have Sensible Defaults</a></dt>
+<dt><a href="pol_tutorial/policy_usage.html"> So
+ How are Policies Used Anyway?</a></dt>
+<dt><a href="pol_tutorial/changing_policy_defaults.html">
+ Changing the Policy Defaults</a></dt>
+<dt><a href="pol_tutorial/ad_hoc_dist_policies.html">
+ Setting Policies for Distributions on an Ad Hoc Basis</a></dt>
+<dt><a href="pol_tutorial/ad_hoc_sf_policies.html">
+ Changing the Policy on an Ad Hoc Basis for the Special Functions</a></dt>
+<dt><a href="pol_tutorial/namespace_policies.html">
+ Setting Policies at Namespace or Translation Unit Scope</a></dt>
+<dt><a href="pol_tutorial/user_def_err_pol.html">
+ Calling User Defined Error Handlers</a></dt>
+<dt><a href="pol_tutorial/understand_dis_quant.html">
+ Understanding Quantiles of Discrete Distributions</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ All of the statistical distributions in this library are class templates
+ that accept two template parameters, both with sensible defaults, for example:
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class RealType = double, class Policy = policies::policy<> >
+class fisher_f_distribution;
+
+typedef fisher_f_distribution<> fisher_f;
+
+}}
+</pre>
+
+ 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">double</code> precision arithmetic and all the
+ default policies.
+ 
+
+ 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 nearest integer,
+ then here's how it can be done:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions/binomial.hpp>
+
+//
+// Begin by defining a policy type, that gives the
+// behaviour we want:
+//
+using namespace boost::math::policies;
+typedef policy<
+ promote_float<false>,
+ discrete_quantile<integer_round_nearest>
+> mypolicy;
+//
+// Then define a distribution that uses it:
+//
+typedef boost::math::binomial_distribution<float, mypolicy> mybinom;
+//
+// And now use it to get the quantile:
+//
+int main()
+{
+ std::cout << "quantile is: " <<
+ quantile(mybinom(200, 0.25), 0.05) << std::endl;
+}
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ Which outputs:
+ 
+<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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ All of the special functions in this library come in two overloaded forms,
+ one with a final "policy" parameter, and one without. For example:
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class RealType, class Policy>
+RealType tgamma(RealType, const Policy&);
+
+template <class RealType>
+RealType tgamma(RealType);
+
+}} // namespaces
+</pre>
+
+ Normally, the second version is just a forwarding wrapper to the first
+ like this:
+ 
+<pre class="programlisting">
+template <class RealType>
+inline RealType tgamma(RealType x)
+{
+ return tgamma(x, policies::policy<>());
+}
+</pre>
+
+ 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">tgamma</code>
+ to behave in a C-compatible fashion and set <code class="computeroutput">::errno</code> when an error occurs, and never
+ throw an exception:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/gamma.hpp>
+//
+// Define the policy to use:
+//
+using namespace boost::math::policies;
+typedef policy<
+ domain_error<errno_on_error>,
+ pole_error<errno_on_error>,
+ overflow_error<errno_on_error>,
+ evaluation_error<errno_on_error>
+> c_policy;
+//
+// Now use the policy when calling tgamma:
+//
+int main()
+{
+ errno = 0;
+ std::cout << "Result of tgamma(30000) is: "
+ << boost::math::tgamma(30000, c_policy()) << std::endl;
+ std::cout << "errno = " << errno << std::endl;
+ std::cout << "Result of tgamma(-10) is: "
+ << boost::math::tgamma(-10, c_policy()) << std::endl;
+ std::cout << "errno = " << errno << std::endl;
+}
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ which outputs:
+ 
+<pre class="programlisting">Result of tgamma(30000) is: 1.#INF
+errno = 34
+Result of tgamma(-10) is: 1.#QNAN
+errno = 33
+</pre>
+
+ Alternatively, for ad hoc use, we can use the <code class="computeroutput">make_policy</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:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/gamma.hpp>
+
+int main()
+{
+ using namespace boost::math::policies;
+ errno = 0;
+ std::cout << "Result of tgamma(30000) is: "
+ << boost::math::tgamma(
+ 30000,
+ make_policy(
+ domain_error<errno_on_error>(),
+ pole_error<errno_on_error>(),
+ overflow_error<errno_on_error>(),
+ evaluation_error<errno_on_error>()
+ )
+ ) << std::endl;
+ // Check errno was set:
+ std::cout << "errno = " << errno << std::endl;
+ // and again with evaluation at a pole:
+ std::cout << "Result of tgamma(-10) is: "
+ << boost::math::tgamma(
+ -10,
+ make_policy(
+ domain_error<errno_on_error>(),
+ pole_error<errno_on_error>(),
+ overflow_error<errno_on_error>(),
+ evaluation_error<errno_on_error>()
+ )
+ ) << std::endl;
+ // Check errno was set:
+ std::cout << "errno = " << errno << std::endl;
+}
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ The default policies used by the library are changed by the usual configuration
+ macro method.
+ 
+
+ For example, passing <code class="computeroutput">-DBOOST_MATH_DOMAIN_ERROR_POLICY=errno_on_error</code>
+ to your compiler will cause domain errors to set <code class="computeroutput">::errno</code> and return a NaN rather than the
+ usual default behaviour of throwing a <code class="computeroutput">std::domain_error</code>
+ exception.
+ 
+<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">
+
+ For Microsoft Visual Studio,you can add to the Project Property Page,
+ C/C++, Preprocessor, Preprocessor definitions like:
+ 
+
+
+
+<pre class="programlisting">
+BOOST_MATH_ASSERT_UNDEFINED_POLICY=0
+BOOST_MATH_OVERFLOW_ERROR_POLICY=errno_on_error</pre>
+
+ 
+
+ This may be helpful to avoid complications with pre-compiled headers
+ that may mean that the equivalent definitions in source code:
+ 
+
+
+
+<pre class="programlisting">
+#define BOOST_MATH_ASSERT_UNDEFINED_POLICY false
+#define BOOST_MATH_OVERFLOW_ERROR_POLICY errno_on_error</pre>
+
+ 
+
+ may be ignored.
+ 
+
+ The compiler command line shows:
+ 
+
+
+
+<pre class="programlisting">
+/D "BOOST_MATH_ASSERT_UNDEFINED_POLICY=0"
+/D "BOOST_MATH_OVERFLOW_ERROR_POLICY=errno_on_error"</pre>
+
+ 
+</td></tr>
+</table></div>
+
+ There is however a very important caveat to this:
+ 
+<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">
+
+ Default policies changed by setting configuration
+ macros must be changed uniformly in every translation unit in the program.
+ 
+
+ Failure to follow this rule may result in violations of the "One
+ Definition Rule (ODR)" and result in unpredictable program behaviour.
+ 
+</td></tr>
+</table></div>
+
+ That means there are only two safe ways to use these macros:
+ 
+<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>
+
+ What you should not do is:
+ 
+<div class="itemizedlist"><ul type="disc"><li>
+ Set the defines in the source file using <code class="computeroutput">#define</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>
+
+ 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: don't say that you weren't warned!
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Since we know that this is a single file program we could just add:
+ 
+
+
+
+<pre class="programlisting">
+#define BOOST_MATH_DOMAIN_ERROR_POLICY ignore_error
+</pre>
+
+ 
+
+ 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:
+ 
+
+
+
+<pre class="programlisting">
+#define BOOST_MATH_DOMAIN_ERROR_POLICY errno_on_error
+</pre>
+
+ 
+
+ To ensure the <code class="computeroutput">::errno</code>
+ is set when a domain error occurs as well as returning a NaN.
+ 
+
+ 
+
+ This is safe provided the program consists of a single translation unit
+ and we place the define before
+ any #includes. Note that should we add the define after the includes
+ then it will have no effect! A warning such as:
+ 
+
+
+
+<pre class="programlisting">warning C4005: 'BOOST_MATH_OVERFLOW_ERROR_POLICY' : macro redefinition</pre>
+
+ 
+
+ is a certain sign that it will not have the desired
+ effect.
+ 
+
+ 
+
+ We'll begin our sample program with the needed includes:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+// Boost
+#include <boost/math/distributions/students_t.hpp>
+ using boost::math::students_t; // Probability of students_t(df, t).
+
+// std
+#include <iostream>
+ using std::cout;
+ using std::endl;
+
+#include <stdexcept>
+ using std::exception;</pre>
+
+ 
+
+ 
+
+ 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:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+int main()
+{
+ cout << "Example error handling using Student's t function. " << endl;
+ cout << "BOOST_MATH_DOMAIN_ERROR_POLICY is set to: "
+ << BOOST_STRINGIZE(BOOST_MATH_DOMAIN_ERROR_POLICY) << endl;
+
+ double degrees_of_freedom = -1; // A bad argument!
+ double t = 10;
+
+ try
+ {
+ errno = 0;
+ students_t dist(degrees_of_freedom); // exception is thrown here if enabled
+ double p = cdf(dist, t);
+ // test for error reported by other means:
+ if((boost::math::isnan)(p))
+ {
+ cout << "cdf returned a NaN!" << endl;
+ cout << "errno is set to: " << errno << endl;
+ }
+ else
+ cout << "Probability of Student's t is " << p << endl;
+ }
+ catch(const std::exception& e)
+ {
+ std::cout <<
+ "\n""Message from thrown exception was:\n " << e.what() << std::endl;
+ }
+
+ return 0;
+} // int main()</pre>
+
+ 
+
+ 
+
+ Here's what the program output looks like with a default build (one that
+ does throw exceptions):
+ 
+
+
+
+<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<double>::students_t_distribution:
+ Degrees of freedom argument is -1, but must be > 0 !
+</pre>
+
+ 
+
+ Alternatively let's build with:
+ 
+
+
+
+<pre class="programlisting">
+#define BOOST_MATH_DOMAIN_ERROR_POLICY ignore_error
+</pre>
+
+ 
+
+ Now the program output is:
+ 
+
+
+
+<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>
+
+ 
+
+ And finally let's build with:
+ 
+
+
+
+<pre class="programlisting">
+#define BOOST_MATH_DOMAIN_ERROR_POLICY errno_on_error
+</pre>
+
+ 
+
+ Which gives the output:
+ 
+
+
+
+<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>
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ 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(Policy).
+ 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.
+ 
+
+ 
+
+ Suppose we want <code class="computeroutput">C::foo()</code>
+ to behave in a C-compatible way and set <code class="computeroutput">::errno</code> on error rather than throwing
+ any exceptions.
+ 
+
+ 
+
+ We'll begin by including the needed header:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions.hpp></pre>
+
+ 
+
+ 
+
+ 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:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+namespace C{
+
+using namespace boost::math::policies;
+
+typedef policy<
+ domain_error<errno_on_error>,
+ pole_error<errno_on_error>,
+ overflow_error<errno_on_error>,
+ evaluation_error<errno_on_error>
+> c_policy;</pre>
+
+ 
+
+ 
+
+ All we need do now is invoke the BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS
+ macro passing our policy type as the single argument:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS(c_policy)
+
+} // close namespace C</pre>
+
+ 
+
+ 
+
+ We now have a set of forwarding functions defined in namespace C that
+ all look something like this:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+template <class RealType>
+inline typename boost::math::tools::promote_args<RT>::type
+ tgamma(RT z)
+{
+ return boost::math::tgamma(z, c_policy());
+}
+</pre>
+
+ 
+
+ 
+
+ So that when we call <code class="computeroutput">C::tgamma(z)</code> we really end up calling <code class="computeroutput">boost::math::tgamma(z, C::c_policy())</code>:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+int main()
+{
+ errno = 0;
+ std::cout << "Result of tgamma(30000) is: "
+ << C::tgamma(30000) << std::endl;
+ std::cout << "errno = " << errno << std::endl;
+ std::cout << "Result of tgamma(-10) is: "
+ << C::tgamma(-10) << std::endl;
+ std::cout << "errno = " << errno << std::endl;
+}</pre>
+
+ 
+
+ 
+
+ Which outputs:
+ 
+
+
+
+<pre class="programlisting">Result of C::tgamma(30000) is: 1.#INF
+errno = 34
+Result of C::tgamma(-10) is: 1.#QNAN
+errno = 33
+</pre>
+
+ 
+
+ 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.
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ 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:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions.hpp>
+
+namespace {
+
+using namespace boost::math::policies;
+
+typedef policy<
+ domain_error<errno_on_error>,
+ pole_error<errno_on_error>,
+ overflow_error<errno_on_error>,
+ evaluation_error<errno_on_error>
+> c_policy;
+
+BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS(c_policy)
+
+} // close unnamed namespace
+
+int main()
+{
+ errno = 0;
+ std::cout << "Result of tgamma(30000) is: "
+ << tgamma(30000) << std::endl;
+ std::cout << "errno = " << errno << std::endl;
+ std::cout << "Result of tgamma(-10) is: "
+ << tgamma(-10) << std::endl;
+ std::cout << "errno = " << errno << std::endl;
+}
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ 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:
+ 
+<pre class="programlisting">
+BOOST_MATH_DECLARE_DISTRIBUTIONS(double, mypolicy)
+</pre>
+
+ Results a set of typedefs being defined like this:
+ 
+<pre class="programlisting">
+typedef boost::math::normal_distribution<double, mypolicy> normal;
+</pre>
+
+ The name of each typedef is the same as the name of the distribution class
+ template, but without the "_distribution" suffix.
+ 
+
+ 
+
+ Suppose we want a set of distributions to behave as follows:
+ 
+
+ 
+<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>
+
+ 
+
+ We'll begin by including the needed header:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions.hpp></pre>
+
+ 
+
+ 
+
+ 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:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+namespace my_distributions{
+
+using namespace boost::math::policies;
+
+typedef policy<
+ // return infinity and set errno rather than throw:
+ overflow_error<errno_on_error>,
+ // Don't promote double -> long double internally:
+ promote_double<false>,
+ // Return the closest integer result for discrete quantiles:
+ discrete_quantile<integer_round_nearest>
+> my_policy;</pre>
+
+ 
+
+ 
+
+ All we need do now is invoke the BOOST_MATH_DECLARE_DISTRIBUTIONS macro
+ passing the floating point and policy types as arguments:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+BOOST_MATH_DECLARE_DISTRIBUTIONS(double, my_policy)
+
+} // close namespace my_namespace</pre>
+
+ 
+
+ 
+
+ We now have a set of typedefs defined in namespace my_namespace that
+ all look something like this:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+typedef boost::math::normal_distribution<double, my_policy> normal;
+typedef boost::math::cauchy_distribution<double, my_policy> cauchy;
+typedef boost::math::gamma_distribution<double, my_policy> gamma;
+// etc
+</pre>
+
+ 
+
+ 
+
+ So that when we use my_namespace::normal we really end up using <code class="computeroutput">boost::math::normal_distribution<double, my_policy></code>:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+int main()
+{
+ //
+ // Start with something we know will overflow:
+ //
+ my_distributions::normal norm(10, 2);
+ errno = 0;
+ std::cout << "Result of quantile(norm, 0) is: "
+ << quantile(norm, 0) << std::endl;
+ std::cout << "errno = " << errno << std::endl;
+ errno = 0;
+ std::cout << "Result of quantile(norm, 1) is: "
+ << quantile(norm, 1) << std::endl;
+ std::cout << "errno = " << errno << std::endl;
+ //
+ // Now try a discrete distribution:
+ //
+ my_distributions::binomial binom(20, 0.25);
+ std::cout << "Result of quantile(binom, 0.05) is: "
+ << quantile(binom, 0.05) << std::endl;
+ std::cout << "Result of quantile(complement(binom, 0.05)) is: "
+ << quantile(complement(binom, 0.05)) << std::endl;
+}</pre>
+
+ 
+
+ 
+
+ Which outputs:
+ 
+
+
+
+<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>
+
+ 
+
+ 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.
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">
+ There is an important limitation to note: you can not use the macros
+ BOOST_MATH_DECLARE_DISTRIBUTIONS and BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS
+ in the same namespace, as doing so creates ambiguities
+ between functions and distributions of the same name.
+ </td></tr>
+</table></div>
+
+ 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:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/distributions.hpp>
+
+namespace {
+
+using namespace boost::math::policies;
+
+typedef policy<
+ // return infinity and set errno rather than throw:
+ overflow_error<errno_on_error>,
+ // Don't promote double -> long double internally:
+ promote_double<false>,
+ // Return the closest integer result for discrete quantiles:
+ discrete_quantile<integer_round_nearest>
+> my_policy;
+
+BOOST_MATH_DECLARE_DISTRIBUTIONS(double, my_policy)
+
+} // close namespace my_namespace
+
+int main()
+{
+ //
+ // Start with something we know will overflow:
+ //
+ normal norm(10, 2);
+ errno = 0;
+ std::cout << "Result of quantile(norm, 0) is: "
+ << quantile(norm, 0) << std::endl;
+ std::cout << "errno = " << errno << std::endl;
+ errno = 0;
+ std::cout << "Result of quantile(norm, 1) is: "
+ << quantile(norm, 1) << std::endl;
+ std::cout << "errno = " << errno << std::endl;
+ //
+ // Now try a discrete distribution:
+ //
+ binomial binom(20, 0.25);
+ std::cout << "Result of quantile(binom, 0.05) is: "
+ << quantile(binom, 0.05) << std::endl;
+ std::cout << "Result of quantile(complement(binom, 0.05)) is: "
+ << quantile(complement(binom, 0.05)) << std::endl;
+}
+
+</pre>
+
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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!
+ 
+<div class="variablelist">
+
+<dl>
+<dt>Domain Error</dt>
+<dd>
+ Throws a <code class="computeroutput">std::domain_error</code> exception.
+ </dd>
+<dt>Pole Error</dt>
+<dd>
+ Occurs when a function is evaluated at a pole: throws a <code class="computeroutput">std::domain_error</code> exception.
+ </dd>
+<dt>Overflow Error</dt>
+<dd>
+ Throws a <code class="computeroutput">std::overflow_error</code> exception.
+ </dd>
+<dt>Underflow</dt>
+<dd>
+ Ignores the underflow, and returns zero.
+ </dd>
+<dt>Denormalised Result</dt>
+<dd>
+ Ignores the fact that the result is denormalised, and returns it.
+ </dd>
+<dt>Internal Evaluation Error</dt>
+<dd>
+ Throws a <code class="computeroutput">boost::math::evaluation_error</code> exception.
+ </dd>
+<dt>Promotion of float to double</dt>
+<dd>
+ Does occur by default - gives full float precision results.
+ </dd>
+<dt>Promotion of double to long double</dt>
+<dd>
+ Does occur by default if long double offers more precision than double.
+ </dd>
+<dt>Precision of Approximation Used</dt>
+<dd>
+ By default uses an approximation that will result in the lowest level
+ of error for the type of the result.
+ </dd>
+<dt>Behaviour of Discrete Quantiles</dt>
+<dd>
+
+ The quantile function will by default return an integer result that
+ has been rounded outwards. That is to say lower
+ quantiles (where the probability is less than 0.5) are rounded downward,
+ and upper quantiles (where the probability is greater than 0.5) are
+ rounded upwards. This behaviour ensures that if an X% quantile is requested,
+ then at least the requested coverage will be present
+ in the central region, and no more than the requested
+ coverage will be present in the tails.
+ 
+
+ This behaviour can be changed so that the quantile functions are rounded
+ differently, or even return a real-valued result using 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.
+ 
+</dd>
+</dl>
+</div>
+
+ What's more, if you define your own policy type, then it automatically
+ inherits the defaults for any policies not explicitly set, so given:
+ 
+<pre class="programlisting">
+using namespace boost::math::policies;
+//
+// Define a policy that sets ::errno on overflow, and does
+// not promote double to long double internally:
+//
+typedef policy<domain_error<errno_on_error>, promote_double<false> > mypolicy;
+</pre>
+
+ then <code class="computeroutput">mypolicy</code> defines a
+ policy where only the overflow error handling and <code class="computeroutput">double</code>-promotion
+ policies differ from the defaults.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ The details follow later, but basically policies can be set by either:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Defining some macros that change the default behaviour: this
+ is the recommended method for setting installation-wide policies.
+ </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: this
+ is the recommended method for setting policies on a project- or translation-unit-wide
+ basis.
+ </li>
+</ul></div>
+
+ The following sections introduce these methods in more detail.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ 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:
+ 
+
+ <img src="../../../../graphs/binomial_pdf.png" alt="binomial_pdf">
+ 
+
+ 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:
+ 
+
+ <img src="../../../../graphs/binomial_quantile_1.png" alt="binomial_quantile_1">
+ 
+
+ 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:
+ 
+<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>
+
+ 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).
+ 
+
+ By using policies we can offer any of the above as options, but that still
+ leaves the question: What is actually the right thing to do?
+ 
+
+ And in particular: What policy should we use by default?
+ 
+
+ In coming to an answer we should realise that:
+ 
+<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: "If the random variable is less than N then
+ we can reject our null-hypothesis with 90% confidence."
+</li>
+</ul></div>
+
+ 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 at
+ least 95% of the probability to the right of the value chosen,
+ and no more than 5% of the probability
+ to the left of the value chosen.
+ 
+
+ In the above binomial example we would therefore round the result down
+ to 18.
+ 
+
+ The converse applies to upper-quantiles: If the probability is greater
+ than 0.5 we would want to round the quantile up, so that at least the requested probability is to the left
+ of the value returned, and no more than
+ 1 - the requested probability is to the right of the value returned.
+ 
+
+ Likewise for two-sided intervals, we would round lower quantiles down,
+ and upper quantiles up. This ensures that we have at least the
+ requested probability in the central region and no
+ more than 1 minus the requested probability in the tail areas.
+ 
+
+ 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 rounded
+ outwards so that at least 90% of the probability
+ is in the central area:
+ 
+
+ <img src="../../../../graphs/binomial_pdf_3.png" alt="binomial_pdf_3">
+ 
+
+ So far so good, but there is in fact a trap waiting for the unwary here:
+ 
+<pre class="programlisting">
+quantile(binomial(50, 0.5), 0.05);
+</pre>
+
+ 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:
+ 
+<pre class="programlisting">
+cdf(binomial(50, 0.5), x) <= 0.05;
+</pre>
+
+ However:
+ 
+<pre class="programlisting">
+quantile(binomial(50, 0.5), 0.95);
+</pre>
+
+ returns 31, and indeed while there is no x less than 31 for which:
+ 
+<pre class="programlisting">
+cdf(binomial(50, 0.5), x) >= 0.95;
+</pre>
+
+ 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 inclusive of the random variable.
+ So while the left tail area includes the quantile
+ returned, the right tail area always excludes an upper quantile value:
+ since that "belongs" to the central area.
+ 
+
+ 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 <= 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 > 31 is in the
+ right tail.
+ 
+
+ 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:
+ 
+<pre class="programlisting">
+X <= L || X > U
+</pre>
+
+ And the a variable X is inside the central region if:
+ 
+<pre class="programlisting">
+L < X <= U
+</pre>
+
+ The moral here is to always be very careful with your comparisons
+ when dealing with a discrete distribution, and if in doubt,
+ base your comparisons on CDF's instead.
+ 
+<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>
+
+ As you would expect from a section on policies, you won't be surprised
+ to know that other rounding options are available:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>integer_round_outwards</dt>
+<dd>
+
+ This is the default policy as described above: lower quantiles are
+ rounded down (probability < 0.5), and upper quantiles (probability
+ > 0.5) are rounded up.
+ 
+
+ This gives no more than the requested probability
+ in the tails, and at least the requested probability
+ in the central area.
+ 
+</dd>
+<dt>integer_round_inwards</dt>
+<dd>
+
+ This is the exact opposite of the default policy: lower quantiles are
+ rounded up (probability < 0.5), and upper quantiles (probability
+ > 0.5) are rounded down.
+ 
+
+ This gives at least the requested probability
+ in the tails, and no more than the requested probability
+ in the central area.
+ 
+</dd>
+<dt>integer_round_down</dt>
+<dd>
+ This policy will always round the result down no matter whether it
+ is an upper or lower quantile
+ </dd>
+<dt>integer_round_up</dt>
+<dd>
+ This policy will always round the result up no matter whether it is
+ an upper or lower quantile
+ </dd>
+<dt>integer_round_nearest</dt>
+<dd>
+ This policy will always round the result to the nearest integer no
+ matter whether it is an upper or lower quantile
+ </dd>
+<dt>real</dt>
+<dd>
+ 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.
+ </dd>
+</dl>
+</div>
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Begin by including the needed headers:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <iostream>
+#include <boost/math/distributions/binomial.hpp></pre>
+
+ 
+
+ 
+
+ Next we'll bring the needed declarations into scope, and define distribution
+ types for all the available rounding policies:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+using namespace boost::math::policies;
+using namespace boost::math;
+
+typedef binomial_distribution<
+ double,
+ policy<discrete_quantile<integer_round_outwards> > >
+ binom_round_outwards;
+
+typedef binomial_distribution<
+ double,
+ policy<discrete_quantile<integer_round_inwards> > >
+ binom_round_inwards;
+
+typedef binomial_distribution<
+ double,
+ policy<discrete_quantile<integer_round_down> > >
+ binom_round_down;
+
+typedef binomial_distribution<
+ double,
+ policy<discrete_quantile<integer_round_up> > >
+ binom_round_up;
+
+typedef binomial_distribution<
+ double,
+ policy<discrete_quantile<integer_round_nearest> > >
+ binom_round_nearest;
+
+typedef binomial_distribution<
+ double,
+ policy<discrete_quantile<real> > >
+ binom_real_quantile;</pre>
+
+ 
+
+ 
+
+ Now let's set to work calling those quantiles:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+int main()
+{
+ std::cout <<
+ "Testing rounding policies for a 50 sample binomial distribution,\n"
+ "with a success fraction of 0.5.\n\n"
+ "Lower quantiles are calculated at p = 0.05\n\n"
+ "Upper quantiles at p = 0.95.\n\n";
+
+ std::cout << std::setw(25) << std::right
+ << "Policy"<< std::setw(18) << std::right
+ << "Lower Quantile" << std::setw(18) << std::right
+ << "Upper Quantile" << std::endl;
+
+ // Test integer_round_outwards:
+ std::cout << std::setw(25) << std::right
+ << "integer_round_outwards"
+ << std::setw(18) << std::right
+ << quantile(binom_round_outwards(50, 0.5), 0.05)
+ << std::setw(18) << std::right
+ << quantile(binom_round_outwards(50, 0.5), 0.95)
+ << std::endl;
+
+ // Test integer_round_inwards:
+ std::cout << std::setw(25) << std::right
+ << "integer_round_inwards"
+ << std::setw(18) << std::right
+ << quantile(binom_round_inwards(50, 0.5), 0.05)
+ << std::setw(18) << std::right
+ << quantile(binom_round_inwards(50, 0.5), 0.95)
+ << std::endl;
+
+ // Test integer_round_down:
+ std::cout << std::setw(25) << std::right
+ << "integer_round_down"
+ << std::setw(18) << std::right
+ << quantile(binom_round_down(50, 0.5), 0.05)
+ << std::setw(18) << std::right
+ << quantile(binom_round_down(50, 0.5), 0.95)
+ << std::endl;
+
+ // Test integer_round_up:
+ std::cout << std::setw(25) << std::right
+ << "integer_round_up"
+ << std::setw(18) << std::right
+ << quantile(binom_round_up(50, 0.5), 0.05)
+ << std::setw(18) << std::right
+ << quantile(binom_round_up(50, 0.5), 0.95)
+ << std::endl;
+
+ // Test integer_round_nearest:
+ std::cout << std::setw(25) << std::right
+ << "integer_round_nearest"
+ << std::setw(18) << std::right
+ << quantile(binom_round_nearest(50, 0.5), 0.05)
+ << std::setw(18) << std::right
+ << quantile(binom_round_nearest(50, 0.5), 0.95)
+ << std::endl;
+
+ // Test real:
+ std::cout << std::setw(25) << std::right
+ << "real"
+ << std::setw(18) << std::right
+ << quantile(binom_real_quantile(50, 0.5), 0.05)
+ << std::setw(18) << std::right
+ << quantile(binom_real_quantile(50, 0.5), 0.95)
+ << std::endl;
+}</pre>
+
+ 
+
+ 
+
+ Which produces the program output:
+ 
+
+
+
+<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>
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 
+
+ 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">user_error</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:
+ 
+
+
+
+<pre class="programlisting">
+namespace boost{ namespace math{ namespace policy{
+
+template <class T>
+T user_domain_error(const char* function, const char* message, const T& val);
+template <class T>
+T user_pole_error(const char* function, const char* message, const T& val);
+template <class T>
+T user_overflow_error(const char* function, const char* message, const T& val);
+template <class T>
+T user_underflow_error(const char* function, const char* message, const T& val);
+template <class T>
+T user_denorm_error(const char* function, const char* message, const T& val);
+template <class T>
+T user_evaluation_error(const char* function, const char* message, const T& val);
+
+}}} // namespaces
+</pre>
+
+ 
+
+ 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:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <iostream>
+#include <boost/math/special_functions.hpp>
+
+namespace boost{ namespace math{ namespace policies{
+
+template <class T>
+T user_domain_error(const char* function, const char* message, const T& val)
+{
+ std::cerr << "Domain Error." << std::endl;
+ return std::numeric_limits<T>::quiet_NaN();
+}
+
+template <class T>
+T user_pole_error(const char* function, const char* message, const T& val)
+{
+ std::cerr << "Pole Error." << std::endl;
+ return std::numeric_limits<T>::quiet_NaN();
+}
+
+
+}}} // namespaces</pre>
+
+ 
+
+ 
+
+ 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:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+namespace{
+
+using namespace boost::math::policies;
+
+typedef policy<
+ domain_error<user_error>,
+ pole_error<user_error>
+> user_error_policy;
+
+BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS(user_error_policy)
+
+} // close unnamed namespace</pre>
+
+ 
+
+ 
+
+ We now have a set of forwarding functions defined in an unnamed namespace
+ that all look something like this:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+template <class RealType>
+inline typename boost::math::tools::promote_args<RT>::type
+ tgamma(RT z)
+{
+ return boost::math::tgamma(z, user_error_policy());
+}
+</pre>
+
+ 
+
+ 
+
+ So that when we call <code class="computeroutput">tgamma(z)</code> we really end up calling <code class="computeroutput">boost::math::tgamma(z, user_error_policy())</code>,
+ and any errors will get directed to our own error handlers:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+int main()
+{
+ std::cout << "Result of erf_inv(-10) is: "
+ << erf_inv(-10) << std::endl;
+ std::cout << "Result of tgamma(-10) is: "
+ << tgamma(-10) << std::endl;
+}</pre>
+
+ 
+
+ 
+
+ Which outputs:
+ 
+
+
+
+<pre class="programlisting">Domain Error.
+Result of erf_inv(-10) is: 1.#QNAN
+Pole Error.
+Result of tgamma(-10) is: 1.#QNAN
+</pre>
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></table></div>
+
+ 
+
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Each error handler has the general form:
+ 
+
+
+
+<pre class="programlisting">
+template <class T>
+T user_error_type(
+ const char* function,
+ const char* message,
+ const T& val);
+</pre>
+
+ 
+
+ and accepts three arguments:
+ 
+
+ 
+<div class="variablelist">
+
+<dl>
+<dt>const char* function</dt>
+<dd>
+ 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.
+ </dd>
+<dt>const char* message</dt>
+<dd>
+ A message associated with the error, normally this contains a %1%
+ format specifier that should be replaced with the value of value:
+ however note that overflow and underflow messages do not contain
+ this %1% specifier (since the value of value
+ is immaterial in these cases).
+ </dd>
+<dt>const T& value</dt>
+<dd>
+ 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.
+ </dd>
+</dl>
+</div>
+
+ 
+
+ As before we'll include the headers we need first:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+#include <iostream>
+#include <boost/math/special_functions.hpp></pre>
+
+ 
+
+ 
+
+ Next we'll implement the error handlers for each type of error, starting
+ with domain errors:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+namespace boost{ namespace math{ namespace policies{
+
+template <class T>
+T user_domain_error(const char* function, const char* message, const T& val)
+{</pre>
+
+ 
+
+ 
+
+ We'll begin with a bit of defensive programming:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+if(function == 0)
+ function = "Unknown function with arguments of type %1%";
+if(message == 0)
+ message = "Cause unknown with bad argument %1%";</pre>
+
+ 
+
+ 
+
+ Next we'll format the name of the function with the name of type T:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+std::string msg("Error in function ");
+msg += (boost::format(function) % typeid(T).name()).str();</pre>
+
+ 
+
+ 
+
+ Then likewise format the error message with the value of parameter val,
+ making sure we output all the digits of val:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+msg += ": \n";
+int prec = 2 + (std::numeric_limits<T>::digits * 30103UL) / 100000UL;
+msg += (boost::format(message) % boost::io::group(std::setprecision(prec), val)).str();</pre>
+
+ 
+
+ 
+
+ 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:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+std::cerr << msg << std::endl;</pre>
+
+ 
+
+ 
+
+ Finally the only sensible value we can return from a domain error is
+ a NaN:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+ return std::numeric_limits<T>::quiet_NaN();
+}</pre>
+
+ 
+
+ 
+
+ Pole errors are essentially a special case of domain errors, so in this
+ example we'll just return the result of a domain error:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+template <class T>
+T user_pole_error(const char* function, const char* message, const T& val)
+{
+ return user_domain_error(function, message, val);
+}</pre>
+
+ 
+
+ 
+
+ Overflow errors are very similar to domain errors, except that there's
+ no %1% format specifier in the message parameter:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+template <class T>
+T user_overflow_error(const char* function, const char* message, const T& val)
+{
+ if(function == 0)
+ function = "Unknown function with arguments of type %1%";
+ if(message == 0)
+ message = "Result of function is too large to represent";
+
+ std::string msg("Error in function ");
+ msg += (boost::format(function) % typeid(T).name()).str();
+
+ msg += ": \n";
+ msg += message;
+
+ std::cerr << msg << std::endl;
+
+ // Value passed to the function is an infinity, just return it:
+ return val;
+}</pre>
+
+ 
+
+ 
+
+ Underflow errors are much the same as overflow:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+template <class T>
+T user_underflow_error(const char* function, const char* message, const T& val)
+{
+ if(function == 0)
+ function = "Unknown function with arguments of type %1%";
+ if(message == 0)
+ message = "Result of function is too small to represent";
+
+ std::string msg("Error in function ");
+ msg += (boost::format(function) % typeid(T).name()).str();
+
+ msg += ": \n";
+ msg += message;
+
+ std::cerr << msg << std::endl;
+
+ // Value passed to the function is zero, just return it:
+ return val;
+}</pre>
+
+ 
+
+ 
+
+ Denormalised results are much the same as underflow:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+template <class T>
+T user_denorm_error(const char* function, const char* message, const T& val)
+{
+ if(function == 0)
+ function = "Unknown function with arguments of type %1%";
+ if(message == 0)
+ message = "Result of function is denormalised";
+
+ std::string msg("Error in function ");
+ msg += (boost::format(function) % typeid(T).name()).str();
+
+ msg += ": \n";
+ msg += message;
+
+ std::cerr << msg << std::endl;
+
+ // Value passed to the function is denormalised, just return it:
+ return val;
+}</pre>
+
+ 
+
+ 
+
+ Which leaves us with evaluation errors, these occur when an internal
+ error occurs that prevents the function being fully evaluated. The parameter
+ val contains the closest approximation to the result
+ found so far:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+template <class T>
+T user_evaluation_error(const char* function, const char* message, const T& val)
+{
+ if(function == 0)
+ function = "Unknown function with arguments of type %1%";
+ if(message == 0)
+ message = "An internal evaluation error occured with "
+ "the best value calculated so far of %1%";
+
+ std::string msg("Error in function ");
+ msg += (boost::format(function) % typeid(T).name()).str();
+
+ msg += ": \n";
+ int prec = 2 + (std::numeric_limits<T>::digits * 30103UL) / 100000UL;
+ msg += (boost::format(message) % boost::io::group(std::setprecision(prec), val)).str();
+
+ std::cerr << msg << std::endl;
+
+ // What do we return here? This is generally a fatal error,
+ // that should never occur, just return a NaN for the purposes
+ // of the example:
+ return std::numeric_limits<T>::quiet_NaN();
+}
+
+}}} // namespaces</pre>
+
+ 
+
+ 
+
+ 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:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+namespace{
+
+using namespace boost::math::policies;
+
+typedef policy<
+ domain_error<user_error>,
+ pole_error<user_error>,
+ overflow_error<user_error>,
+ underflow_error<user_error>,
+ denorm_error<user_error>,
+ evaluation_error<user_error>
+> user_error_policy;
+
+BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS(user_error_policy)
+
+} // close unnamed namespace</pre>
+
+ 
+
+ 
+
+ We now have a set of forwarding functions defined in an unnamed namespace
+ that all look something like this:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+template <class RealType>
+inline typename boost::math::tools::promote_args<RT>::type
+ tgamma(RT z)
+{
+ return boost::math::tgamma(z, user_error_policy());
+}
+</pre>
+
+ 
+
+ 
+
+ So that when we call <code class="computeroutput">tgamma(z)</code> we really end up calling <code class="computeroutput">boost::math::tgamma(z, user_error_policy())</code>,
+ and any errors will get directed to our own error handlers:
+ 
+
+ 
+
+
+
+<pre class="programlisting">
+int main()
+{
+ // Raise a domain error:
+ std::cout << "Result of erf_inv(-10) is: "
+ << erf_inv(-10) << std::endl << std::endl;
+ // Raise a pole error:
+ std::cout << "Result of tgamma(-10) is: "
+ << tgamma(-10) << std::endl << std::endl;
+ // Raise an overflow error:
+ std::cout << "Result of tgamma(3000) is: "
+ << tgamma(3000) << std::endl << std::endl;
+ // Raise an underflow error:
+ std::cout << "Result of tgamma(-190.5) is: "
+ << tgamma(-190.5) << std::endl << std::endl;
+ // Unfortunately we can't predicably raise a denormalised
+ // result, nor can we raise an evaluation error in this example
+ // since these should never really occur!
+}</pre>
+
+ 
+
+ 
+
+ Which outputs:
+ 
+
+
+
+<pre class="programlisting">Error in function boost::math::erf_inv<double>(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<long double>(long double):
+Evaluation of tgamma at a negative integer -10.
+Result of tgamma(-10) is: 1.#QNAN
+
+Error in function boost::math::tgamma<long double>(long double):
+Result of tgamma is too large to represent.
+Error in function boost::math::tgamma<double>(double):
+Result of function is too large to represent
+Result of tgamma(3000) is: 1.#INF
+
+Error in function boost::math::tgamma<long double>(long double):
+Result of tgamma is too large to represent.
+Error in function boost::math::tgamma<long double>(long double):
+Result of tgamma is too small to represent.
+Result of tgamma(-190.5) is: 0
+</pre>
+
+ 
+
+ 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">tgamma(-190.5)</code>
+ is implemented in terms of <code class="computeroutput">tgamma(190.5)</code> - which overflows - the reflection formula
+ for <code class="computeroutput">tgamma</code> then notices
+ that it's dividing by infinity and underflows.
+ 
+
+ 
+
+ 
+<div class="calloutlist"><table border="0" summary="Callout list"></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ A policy is a compile-time mechanism for customising the behaviour of a
+ special function, or a statistical distribution. With Policies you can
+ control:
+ 
+<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">float</code>
+ to <code class="computeroutput">double</code> and <code class="computeroutput">double</code> to <code class="computeroutput">long
+ double</code> in order to improve precision.
+ </li>
+<li>
+ What precision to use when calculating the result.
+ </li>
+</ul></div>
+
+ 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.
+ 
+
+ For this reason a Policy is a type: in fact it's an
+ instance of the class template <code class="computeroutput">boost::math::policies::policy<></code>. This class is just a compile-time-container
+ of user-selected policies (sometimes called a type-list):
+ 
+<pre class="programlisting">
+using namespace boost::math::policies;
+//
+// Define a policy that sets ::errno on overflow, and does
+// not promote double to long double internally:
+//
+typedef policy<domain_error<errno_on_error>, promote_double<false> > mypolicy;
+</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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> Gamma Functions</dt>
+<dd><dl>
+<dt> Gamma</dt>
+<dt> Log Gamma</dt>
+<dt> Digamma</dt>
+<dt><a href="special/sf_gamma/gamma_ratios.html"> Ratios
+ of Gamma Functions</a></dt>
+<dt><a href="special/sf_gamma/igamma.html"> Incomplete Gamma
+ Functions</a></dt>
+<dt><a href="special/sf_gamma/igamma_inv.html"> Incomplete
+ Gamma Function Inverses</a></dt>
+<dt><a href="special/sf_gamma/gamma_derivatives.html"> Derivative
+ of the Incomplete Gamma Function</a></dt>
+</dl></dd>
+<dt><a href="special/factorials.html"> Factorials and Binomial
+ Coefficients</a></dt>
+<dd><dl>
+<dt> Factorial</dt>
+<dt><a href="special/factorials/sf_double_factorial.html">
+ Double Factorial</a></dt>
+<dt><a href="special/factorials/sf_rising_factorial.html">
+ Rising Factorial</a></dt>
+<dt><a href="special/factorials/sf_falling_factorial.html">
+ Falling Factorial</a></dt>
+<dt><a href="special/factorials/sf_binomial.html"> Binomial
+ Coefficients</a></dt>
+</dl></dd>
+<dt> Beta Functions</dt>
+<dd><dl>
+<dt> Beta</dt>
+<dt><a href="special/sf_beta/ibeta_function.html"> Incomplete
+ Beta Functions</a></dt>
+<dt><a href="special/sf_beta/ibeta_inv_function.html"> The
+ Incomplete Beta Function Inverses</a></dt>
+<dt><a href="special/sf_beta/beta_derivative.html"> Derivative
+ of the Incomplete Beta Function</a></dt>
+</dl></dd>
+<dt> Error Functions</dt>
+<dd><dl>
+<dt><a href="special/sf_erf/error_function.html"> Error
+ Functions</a></dt>
+<dt><a href="special/sf_erf/error_inv.html"> Error Function
+ Inverses</a></dt>
+</dl></dd>
+<dt> Polynomials</dt>
+<dd><dl>
+<dt><a href="special/sf_poly/legendre.html"> Legendre (and
+ Associated) Polynomials</a></dt>
+<dt><a href="special/sf_poly/laguerre.html"> Laguerre (and
+ Associated) Polynomials</a></dt>
+<dt> Hermite Polynomials</dt>
+<dt> Spherical Harmonics</dt>
+</dl></dd>
+<dt> Bessel Functions</dt>
+<dd><dl>
+<dt><a href="special/bessel/bessel_over.html"> Bessel Function
+ Overview</a></dt>
+<dt><a href="special/bessel/bessel.html"> Bessel Functions
+ of the First and Second Kinds</a></dt>
+<dt><a href="special/bessel/mbessel.html"> Modified Bessel
+ Functions of the First and Second Kinds</a></dt>
+<dt><a href="special/bessel/sph_bessel.html"> Spherical
+ Bessel Functions of the First and Second Kinds</a></dt>
+</dl></dd>
+<dt> Elliptic Integrals</dt>
+<dd><dl>
+<dt><a href="special/ellint/ellint_intro.html"> Elliptic
+ Integral Overview</a></dt>
+<dt><a href="special/ellint/ellint_carlson.html"> Elliptic
+ Integrals - Carlson Form</a></dt>
+<dt><a href="special/ellint/ellint_1.html"> Elliptic Integrals
+ of the First Kind - Legendre Form</a></dt>
+<dt><a href="special/ellint/ellint_2.html"> Elliptic Integrals
+ of the Second Kind - Legendre Form</a></dt>
+<dt><a href="special/ellint/ellint_3.html"> Elliptic Integrals
+ of the Third Kind - Legendre Form</a></dt>
+</dl></dd>
+<dt><a href="special/powers.html"> Logs, Powers, Roots and
+ Exponentials</a></dt>
+<dd><dl>
+<dt> log1p</dt>
+<dt> expm1</dt>
+<dt> cbrt</dt>
+<dt> sqrt1pm1</dt>
+<dt> powm1</dt>
+<dt> hypot</dt>
+</dl></dd>
+<dt><a href="special/sinc.html"> Sinus Cardinal and Hyperbolic
+ Sinus Cardinal Functions</a></dt>
+<dd><dl>
+<dt><a href="special/sinc/sinc_overview.html"> Sinus Cardinal
+ and Hyperbolic Sinus Cardinal Functions Overview</a></dt>
+<dt>sinc_pi</dt>
+<dt>sinhc_pi</dt>
+</dl></dd>
+<dt> Inverse Hyperbolic Functions</dt>
+<dd><dl>
+<dt><a href="special/inv_hyper/inv_hyper_over.html"> Inverse
+ Hyperbolic Functions Overview</a></dt>
+<dt> acosh</dt>
+<dt> asinh</dt>
+<dt> atanh</dt>
+</dl></dd>
+<dt><a href="special/fpclass.html"> Floating Point Classification:
+ Infinities and NaN's</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="bessel/bessel_over.html"> Bessel Function
+ Overview</a></dt>
+<dt><a href="bessel/bessel.html"> Bessel Functions
+ of the First and Second Kinds</a></dt>
+<dt><a href="bessel/mbessel.html"> Modified Bessel
+ Functions of the First and Second Kinds</a></dt>
+<dt><a href="bessel/sph_bessel.html"> Spherical
+ Bessel Functions of the First and Second Kinds</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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">
+template <class T1, class T2>
+calculated-result-type cyl_bessel_j(T1 v, T2 x);
+
+template <class T1, class T2, class Policy>
+calculated-result-type cyl_bessel_j(T1 v, T2 x, const Policy&);
+
+template <class T1, class T2>
+calculated-result-type cyl_neumann(T1 v, T2 x);
+
+template <class T1, class T2, class Policy>
+calculated-result-type cyl_neumann(T1 v, T2 x, const Policy&);
+</pre>
+<a name="math_toolkit.special.bessel.bessel.description"></a><h5>
+<a name="id669800"></a>
+ Description
+ </h5>
+
+ The functions cyl_bessel_j
+ and cyl_neumann
+ return the result of the Bessel functions of the first and second kinds
+ respectively:
+ 
+
+ cyl_bessel_j(v, x) = Jv(x)
+ 
+
+ cyl_neumann(v, x) = Yv(x) = Nv(x)
+ 
+
+ where:
+ 
+
+ <img src="../../../../equations/bessel2.png">
+ 
+
+ <img src="../../../../equations/bessel3.png">
+ 
+
+ 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">result
+ type calculation rules</a> when T1 and T2 are different types.
+ The functions are also optimised for the relatively common case that T1
+ is an integer.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ 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">x <
+ 0</code> and v is not an integer, or when
+ <code class="computeroutput">x ==
+ 0</code> and <code class="computeroutput">v
+ != 0</code>.
+ For cyl_neumann
+ this occurs when <code class="computeroutput">x <=
+ 0</code>.
+ 
+
+ The following graph illustrates the cyclic nature of Jv:
+ 
+
+ <img src="../../../../graphs/bessel_jn.png" alt="bessel_jn">
+ 
+
+ The following graph shows the behaviour of Yv: this is also cyclic for
+ large x, but tends to -∞ for small x:
+ 
+
+ <img src="../../../../graphs/bessel_yv.png" alt="bessel_yv">
+ 
+<a name="math_toolkit.special.bessel.bessel.testing"></a><h5>
+<a name="id670172"></a>
+ Testing
+ </h5>
+
+ 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).
+ 
+<a name="math_toolkit.special.bessel.bessel.accuracy"></a><h5>
+<a name="id670211"></a>
+ Accuracy
+ </h5>
+
+ 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 relative 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.
+ 
+<div class="table">
+<a name="id670268"></a>Table 29. Errors Rates in cyl_bessel_j
+<div class="table-contents"><table class="table" summary="Errors Rates in cyl_bessel_j">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ J0 and J1
+ 
+ </th>
+<th>
+ 
+ Jv
+ 
+ </th>
+<th>
+ 
+ Jv (large values of x > 1000)
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32 / Visual C++ 8.0
+ 
+ </td>
+<td>
+ 
+ Peak=2.5 Mean=1.1
+ 
+ 
+ GSL Peak=6.6
+ 
+ 
+ Cephes Peak=2.5
+ Mean=1.1
+ 
+ </td>
+<td>
+ 
+ Peak=11 Mean=2.2
+ 
+ 
+ GSL Peak=11
+ 
+ 
+ Cephes Peak=17
+ Mean=2.5
+ 
+ </td>
+<td>
+ 
+ Peak=413 Mean=110
+ 
+ 
+ GSL Peak=6x1011
+ 
+ 
+ Cephes Peak=2x105
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux IA64 / G++ 3.4
+ 
+ </td>
+<td>
+ 
+ Peak=7 Mean=3
+ 
+ </td>
+<td>
+ 
+ Peak=117 Mean=10
+ 
+ </td>
+<td>
+ 
+ Peak=2x104 Mean=6x103
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ SUSE Linux AMD64 / G++ 4.1
+ 
+ </td>
+<td>
+ 
+ Peak=7 Mean=3
+ 
+ </td>
+<td>
+ 
+ Peak=400 Mean=40
+ 
+ </td>
+<td>
+ 
+ Peak=2x104 Mean=1x104
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HP-UX / HP aCC 6
+ 
+ </td>
+<td>
+ 
+ Peak=14 Mean=6
+ 
+ </td>
+<td>
+ 
+ Peak=29 Mean=3
+ 
+ </td>
+<td>
+ 
+ Peak=2700 Mean=450
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id670572"></a>Table 30. Errors Rates in cyl_neumann
+<div class="table-contents"><table class="table" summary="Errors Rates in cyl_neumann">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ J0 and J1
+ 
+ </th>
+<th>
+ 
+ Jn (integer orders)
+ 
+ </th>
+<th>
+ 
+ Jv (fractional orders)
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32 / Visual C++ 8.0
+ 
+ </td>
+<td>
+ 
+ Peak=330 Mean=54
+ 
+ 
+ GSL Peak=34 Mean=9
+ 
+ 
+ Cephes Peak=330
+ Mean=54
+ 
+ </td>
+<td>
+ 
+ Peak=923 Mean=83
+ 
+ 
+ GSL Peak=500 Mean=54
+ 
+ 
+ Cephes Peak=923
+ Mean=83
+ 
+ </td>
+<td>
+ 
+ Peak=561 Mean=36
+ 
+ 
+ GSL Peak=1.4x106 Mean=7x104
+ 
+ 
+ Cephes Peak=+INF
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux IA64 / G++ 3.4
+ 
+ </td>
+<td>
+ 
+ Peak=470 Mean=56
+ 
+ </td>
+<td>
+ 
+ Peak=843 Mean=51
+ 
+ </td>
+<td>
+ 
+ Peak=741 Mean=51
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ SUSE Linux AMD64 / G++ 4.1
+ 
+ </td>
+<td>
+ 
+ Peak=1300 Mean=424
+ 
+ </td>
+<td>
+ 
+ Peak=2x104 Mean=8x103
+ 
+ </td>
+<td>
+ 
+ Peak=1x105 Mean=6x103
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HP-UX / HP aCC 6
+ 
+ </td>
+<td>
+ 
+ Peak=180 Mean=63
+ 
+ </td>
+<td>
+ 
+ Peak=340 Mean=150
+ 
+ </td>
+<td>
+ 
+ Peak=2x104 Mean=1200
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ 
+ Note that for large x these functions are largely
+ dependent on the accuracy of the <code class="computeroutput">std::sin</code>
+ and <code class="computeroutput">std::cos</code> functions.
+ 
+
+ 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 Jv. 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.
+ 
+<a name="math_toolkit.special.bessel.bessel.implementation"></a><h5>
+<a name="id671001"></a>
+ Implementation
+ </h5>
+
+ The implementation is mostly about filtering off various special cases:
+ 
+
+ When x is negative, then the order v
+ 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 x > 0.
+ 
+
+ When the order v is negative then the reflection formulae
+ can be used to move to v > 0:
+ 
+
+ <img src="../../../../equations/bessel9.png">
+ 
+
+ <img src="../../../../equations/bessel10.png">
+ 
+
+ Note that if the order is an integer, then these formulae reduce to:
+ 
+
+ J-n = (-1)nJn
+ 
+
+ Y-n = (-1)nYn
+ 
+
+ However, in general, a negative order implies that we will need to compute
+ both J and Y.
+ 
+
+ When x is large compared to the order v
+ then the asymptotic expansions for large x in M. Abramowitz
+ and I.A. Stegun, Handbook of Mathematical Functions
+ 9.2.19 are used (these were found to be more reliable than those in A&S
+ 9.2.5).
+ 
+
+ When the order v is an integer the method first relates
+ the result to J0, J1, Y0 and Y1 using either forwards or backwards recurrence
+ (Miller's algorithm) depending upon which is stable. The values for J0,
+ J1, Y0 and Y1 are calculated using the rational minimax approximations on
+ root-bracketing intervals for small |x| and Hankel
+ asymptotic expansion for large |x|. The coefficients
+ are from:
+ 
+
+ W.J. Cody, ALGORITHM 715: SPECFUN - A Portable FORTRAN Package
+ of Special Function Routines and Test Drivers, ACM Transactions
+ on Mathematical Software, vol 19, 22 (1993).
+ 
+
+ and
+ 
+
+ J.F. Hart et al, Computer Approximations, John Wiley
+ & Sons, New York, 1968.
+ 
+
+ These approximations are accurate to around 19 decimal digits: therefore
+ these methods are not used when type T has more than 64 binary digits.
+ 
+
+ When x is small, Jx is best computed directly from
+ the series:
+ 
+
+ <img src="../../../../equations/bessel2.png">
+ 
+
+ In the general case we compute Jv and Yv simultaneously.
+ 
+
+ To get the initial values, let μ = ν - floor(ν + 1/2), then μ is the fractional
+ part of ν such that |μ| <= 1/2 (we need this for convergence later). The
+ idea is to calculate Jμ(x), Jμ+1(x), Yμ(x), Yμ+1(x) and use them to obtain
+ Jν(x), Yν(x).
+ 
+
+ The algorithm is called Steed's method, which needs two continued fractions
+ as well as the Wronskian:
+ 
+
+ <img src="../../../../equations/bessel8.png">
+ 
+
+ <img src="../../../../equations/bessel11.png">
+ 
+
+ <img src="../../../../equations/bessel12.png">
+ 
+
+ See: F.S. Acton, Numerical Methods that Work, The
+ Mathematical Association of America, Washington, 1997.
+ 
+
+ The continued fractions are computed using the modified Lentz's method
+ (W.J. Lentz, Generating Bessel functions in Mie scattering calculations
+ using continued fractions, Applied Optics, vol 15, 668 (1976)).
+ Their convergence rates depend on x, therefore we
+ need different strategies for large x and small x.
+ 
+
+ x > v, CF1 needs O(x) iterations
+ to converge, CF2 converges rapidly
+ 
+
+ x <= v, CF1 converges rapidly, CF2 fails to converge
+ when x <code class="literal">-></code> 0
+ 
+
+ When x is large (x > 2), both
+ continued fractions converge (CF1 may be slow for really large x).
+ Jμ, Jμ+1, Yμ, Yμ+1 can be calculated by
+ 
+
+ <img src="../../../../equations/bessel13.png">
+ 
+
+ where
+ 
+
+ <img src="../../../../equations/bessel14.png">
+ 
+
+ Jν and Yμ are then calculated using backward (Miller's algorithm) and forward
+ recurrence respectively.
+ 
+
+ When x is small (x <= 2),
+ CF2 convergence may fail (but CF1 works very well). The solution here is
+ Temme's series:
+ 
+
+ <img src="../../../../equations/bessel15.png">
+ 
+
+ where
+ 
+
+ <img src="../../../../equations/bessel16.png">
+ 
+
+ gk and hk
+are also computed by recursions (involving gamma functions), but
+ the formulas are a little complicated, readers are refered to N.M. Temme,
+ On the numerical evaluation of the ordinary Bessel function of
+ the second kind, Journal of Computational Physics, vol 21, 343
+ (1976). Note Temme's series converge only for |μ| <= 1/2.
+ 
+
+ As the previous case, Yν is calculated from the forward recurrence, so is
+ Yν+1. With these two values and fν, the Wronskian yields Jν(x) directly without
+ backward recurrence.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ Bessel Functions are solutions to Bessel's ordinary differential equation:
+ 
+
+ <img src="../../../../equations/bessel1.png">
+ 
+
+ where ν is the order of the equation, and may be an
+ arbitrary real or complex number, although integer orders are the most
+ common occurrence.
+ 
+
+ This library supports either integer or real orders.
+ 
+
+ Since this is a second order differential equation, there must be two linearly
+ independent solutions, the first of these is denoted Jv
+and known as a Bessel
+ function of the first kind:
+ 
+
+ <img src="../../../../equations/bessel2.png">
+ 
+
+ This function is implemented in this library as cyl_bessel_j.
+ 
+
+ The second solution is denoted either Yv or Nv
+and is known as either a Bessel
+ Function of the second kind, or as a Neumann function:
+ 
+
+ <img src="../../../../equations/bessel3.png">
+ 
+
+ This function is implemented in this library as cyl_neumann.
+ 
+
+ The Bessel functions satisfy the recurrence relations:
+ 
+
+ <img src="../../../../equations/bessel4.png">
+ 
+
+ <img src="../../../../equations/bessel5.png">
+ 
+
+ Have the derivatives:
+ 
+
+ <img src="../../../../equations/bessel6.png">
+ 
+
+ <img src="../../../../equations/bessel7.png">
+ 
+
+ Have the Wronskian relation:
+ 
+
+ <img src="../../../../equations/bessel8.png">
+ 
+
+ and the reflection formulae:
+ 
+
+ <img src="../../../../equations/bessel9.png">
+ 
+
+ <img src="../../../../equations/bessel10.png">
+ 
+<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>
+
+ The Bessel functions are valid for complex argument x,
+ and an important special case is the situation where x
+ is purely imaginary: giving a real valued result. In this case the functions
+ are the two linearly independent solutions to the modified Bessel equation:
+ 
+
+ <img src="../../../../equations/mbessel1.png">
+ 
+
+ 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 Iv and Kv
+respectively:
+ 
+
+ <img src="../../../../equations/mbessel2.png">
+ 
+
+ <img src="../../../../equations/mbessel3.png">
+ 
+
+ These functions are implemented in this library as cyl_bessel_i
+ and cyl_bessel_k
+ respectively.
+ 
+
+ The modified Bessel functions satisfy the recurrence relations:
+ 
+
+ <img src="../../../../equations/mbessel4.png">
+ 
+
+ <img src="../../../../equations/mbessel5.png">
+ 
+
+ Have the derivatives:
+ 
+
+ <img src="../../../../equations/mbessel6.png">
+ 
+
+ <img src="../../../../equations/mbessel7.png">
+ 
+
+ Have the Wronskian relation:
+ 
+
+ <img src="../../../../equations/mbessel8.png">
+ 
+
+ and the reflection formulae:
+ 
+
+ <img src="../../../../equations/mbessel9.png">
+ 
+
+ <img src="../../../../equations/mbessel10.png">
+ 
+<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>
+
+ When solving the Helmholtz equation in spherical coordinates by separation
+ of variables, the radial equation has the form:
+ 
+
+ <img src="../../../../equations/sbessel1.png">
+ 
+
+ The two linearly independent solutions to this equation are called the
+ spherical Bessel functions jn and yn, and are related to the ordinary Bessel
+ functions Jn and Yn by:
+ 
+
+ <img src="../../../../equations/sbessel2.png">
+ 
+
+ The spherical Bessel function of the second kind yn
+is also known as the
+ spherical Neumann function nn.
+ 
+
+ These functions are implemented in this library as sph_bessel
+ and sph_neumann.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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">
+template <class T1, class T2>
+calculated-result-type cyl_bessel_i(T1 v, T2 x);
+
+template <class T1, class T2, class Policy>
+calculated-result-type cyl_bessel_i(T1 v, T2 x, const Policy&);
+
+template <class T1, class T2>
+calculated-result-type cyl_bessel_k(T1 v, T2 x);
+
+template <class T1, class T2, class Policy>
+calculated-result-type cyl_bessel_k(T1 v, T2 x, const Policy&);
+</pre>
+<a name="math_toolkit.special.bessel.mbessel.description"></a><h5>
+<a name="id672300"></a>
+ Description
+ </h5>
+
+ The functions cyl_bessel_i
+ and cyl_bessel_k
+ return the result of the modified Bessel functions of the first and second
+ kind respectively:
+ 
+
+ cyl_bessel_i(v, x) = Iv(x)
+ 
+
+ cyl_bessel_k(v, x) = Kv(x)
+ 
+
+ where:
+ 
+
+ <img src="../../../../equations/mbessel2.png">
+ 
+
+ <img src="../../../../equations/mbessel3.png">
+ 
+
+ 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">result
+ type calculation rules</a> when T1 and T2 are different types.
+ The functions are also optimised for the relatively common case that T1
+ is an integer.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ 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">x <
+ 0</code> and v is not an integer, or when
+ <code class="computeroutput">x ==
+ 0</code> and <code class="computeroutput">v
+ != 0</code>.
+ For cyl_neumann
+ this occurs when <code class="computeroutput">x <=
+ 0</code>.
+ 
+
+ The following graph illustrates the exponential behaviour of Iv.
+ 
+
+ <img src="../../../../graphs/bessel_i.png" alt="bessel_i">
+ 
+
+ The following graph illustrates the exponential decay of Kv.
+ 
+
+ <img src="../../../../graphs/bessel_k.png" alt="bessel_k">
+ 
+<a name="math_toolkit.special.bessel.mbessel.testing"></a><h5>
+<a name="id672660"></a>
+ Testing
+ </h5>
+
+ 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).
+ 
+<a name="math_toolkit.special.bessel.mbessel.accuracy"></a><h5>
+<a name="id672699"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<div class="table">
+<a name="id672739"></a>Table 31. Errors Rates in cyl_bessel_i
+<div class="table-contents"><table class="table" summary="Errors Rates in cyl_bessel_i">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ Iv
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32 / Visual C++ 8.0
+ 
+ </td>
+<td>
+ 
+ Peak=10 Mean=3.4 GSL Peak=6000
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux IA64 / G++ 3.4
+ 
+ </td>
+<td>
+ 
+ Peak=11 Mean=3
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ SUSE Linux AMD64 / G++ 4.1
+ 
+ </td>
+<td>
+ 
+ Peak=11 Mean=4
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HP-UX / HP aCC 6
+ 
+ </td>
+<td>
+ 
+ Peak=15 Mean=4
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id672894"></a>Table 32. Errors Rates in cyl_bessel_k
+<div class="table-contents"><table class="table" summary="Errors Rates in cyl_bessel_k">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ Kv
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32 / Visual C++ 8.0
+ 
+ </td>
+<td>
+ 
+ Peak=9 Mean=2
+ 
+ 
+ GSL Peak=9
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux IA64 / G++ 3.4
+ 
+ </td>
+<td>
+ 
+ Peak=10 Mean=2
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ SUSE Linux AMD64 / G++ 4.1
+ 
+ </td>
+<td>
+ 
+ Peak=10 Mean=2
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HP-UX / HP aCC 6
+ 
+ </td>
+<td>
+ 
+ Peak=12 Mean=5
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <a name="math_toolkit.special.bessel.mbessel.implementation"></a><h5>
+<a name="id673062"></a>
+ Implementation
+ </h5>
+
+ The following are handled as special cases first:
+ 
+
+ When computing Iv for x < 0, then ν must be an integer
+ or a domain error occurs. If ν is an integer, then the function is odd if
+ ν is odd and even if ν is even, and we can reflect to x > 0.
+ 
+
+ For Iv with v equal to 0, 1 or 0.5 are handled as special cases.
+ 
+
+ The 0 and 1 cases use minimax rational approximations on finite and infinite
+ intervals. The coefficients are from:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ J.M. Blair and C.A. Edwards, Stable rational minimax approximations
+ to the modified Bessel functions I_0(x) and I_1(x), Atomic
+ Energy of Canada Limited Report 4928, Chalk River, 1974.
+ </li>
+<li>
+ S. Moshier, Methods and Programs for Mathematical Functions,
+ Ellis Horwood Ltd, Chichester, 1989.
+ </li>
+</ul></div>
+
+ While the 0.5 case is a simple trigonometric function:
+ 
+
+ I0.5(x) = sqrt(2 / πx) * sinh(x)
+ 
+
+ For Kv with v an integer, the result is calculated
+ using the recurrence relation:
+ 
+
+ <img src="../../../../equations/mbessel5.png">
+ 
+
+ starting from K0 and K1 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.
+ 
+
+ In the general case, we first normalize ν to [<code class="literal">0, [inf</code>])
+ with the help of the reflection formulae:
+ 
+
+ <img src="../../../../equations/mbessel9.png">
+ 
+
+ <img src="../../../../equations/mbessel10.png">
+ 
+
+ Let μ = ν - floor(ν + 1/2), then μ is the fractional part of ν such that |μ| <=
+ 1/2 (we need this for convergence later). The idea is to calculate Kμ(x)
+ and Kμ+1(x), and use them to obtain Iν(x) and Kν(x).
+ 
+
+ The algorithm is proposed by Temme in N.M. Temme, On the numerical
+ evaluation of the modified bessel function of the third kind,
+ Journal of Computational Physics, vol 19, 324 (1975), which needs two continued
+ fractions as well as the Wronskian:
+ 
+
+ <img src="../../../../equations/mbessel11.png">
+ 
+
+ <img src="../../../../equations/mbessel12.png">
+ 
+
+ <img src="../../../../equations/mbessel8.png">
+ 
+
+ The continued fractions are computed using the modified Lentz's method
+ (W.J. Lentz, Generating Bessel functions in Mie scattering calculations
+ using continued fractions, Applied Optics, vol 15, 668 (1976)).
+ Their convergence rates depend on x, therefore we
+ need different strategies for large x and small x.
+ 
+
+ x > v, CF1 needs O(x) iterations
+ to converge, CF2 converges rapidly.
+ 
+
+ x <= v, CF1 converges rapidly, CF2 fails to converge
+ when x <code class="literal">-></code> 0.
+ 
+
+ When x is large (x > 2), both
+ continued fractions converge (CF1 may be slow for really large x).
+ Kμ and Kμ+1
+can be calculated by
+ 
+
+ <img src="../../../../equations/mbessel13.png">
+ 
+
+ where
+ 
+
+ <img src="../../../../equations/mbessel14.png">
+ 
+
+ S is also a series that is summed along with CF2,
+ see I.J. Thompson and A.R. Barnett, Modified Bessel functions
+ I_v and K_v of real order and complex argument to selected accuracy,
+ Computer Physics Communications, vol 47, 245 (1987).
+ 
+
+ When x is small (x <= 2),
+ CF2 convergence may fail (but CF1 works very well). The solution here is
+ Temme's series:
+ 
+
+ <img src="../../../../equations/mbessel15.png">
+ 
+
+ where
+ 
+
+ <img src="../../../../equations/mbessel16.png">
+ 
+
+ fk and hk
+are also computed by recursions (involving gamma functions), but
+ the formulas are a little complicated, readers are referred to N.M. Temme,
+ On the numerical evaluation of the modified Bessel function of
+ the third kind, Journal of Computational Physics, vol 19, 324
+ (1975). Note: Temme's series converge only for |μ| <= 1/2.
+ 
+
+ Kν(x) is then calculated from the forward recurrence, as is Kν+1(x). With
+ these two values and fν, the Wronskian yields Iν(x) directly.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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">
+template <class T1, class T2>
+calculated-result-type sph_bessel(unsigned v, T2 x);
+
+template <class T1, class T2, class Policy>
+calculated-result-type sph_bessel(unsigned v, T2 x, const Policy&);
+
+template <class T1, class T2>
+calculated-result-type sph_neumann(unsigned v, T2 x);
+
+template <class T1, class T2, class Policy>
+calculated-result-type sph_neumann(unsigned v, T2 x, const Policy&);
+</pre>
+<a name="math_toolkit.special.bessel.sph_bessel.description"></a><h5>
+<a name="id674250"></a>
+ Description
+ </h5>
+
+ The functions sph_bessel
+ and sph_neumann
+ return the result of the Spherical Bessel functions of the first and second
+ kinds respectively:
+ 
+
+ sph_bessel(v, x) = jv(x)
+ 
+
+ sph_neumann(v, x) = yv(x) = nv(x)
+ 
+
+ where:
+ 
+
+ <img src="../../../../equations/sbessel2.png">
+ 
+
+ 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">result
+ type calculation rules</a> for the single argument type T.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ The functions return the result of domain_error
+ whenever the result is undefined or complex: this occurs when <code class="computeroutput">x < 0</code>.
+ 
+
+ The jv function is cyclic like Jv but differs in its behaviour at the origin:
+ 
+
+ <img src="../../../../graphs/sph_bessel_j.png" alt="sph_bessel_j">
+ 
+
+ Likewise yv is also cyclic for large x, but tends to -∞
+for small x:
+ 
+
+ <img src="../../../../graphs/sph_bessel_y.png" alt="sph_bessel_y">
+ 
+<a name="math_toolkit.special.bessel.sph_bessel.testing"></a><h5>
+<a name="id674501"></a>
+ Testing
+ </h5>
+
+ 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).
+ 
+<a name="math_toolkit.special.bessel.sph_bessel.accuracy"></a><h5>
+<a name="id674540"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.special.bessel.sph_bessel.implementation"></a><h5>
+<a name="id674590"></a>
+ Implementation
+ </h5>
+
+ Other than error handling and a couple of special cases these functions
+ are implemented directly in terms of their definitions:
+ 
+
+ <img src="../../../../equations/sbessel2.png">
+ 
+
+ The special cases occur for:
+ 
+
+ j0= sinc_pi(x)
+ = sin(x) / x
+ 
+
+ and for small x < 1, we can use the series:
+ 
+
+ <img src="../../../../equations/sbessel5.png">
+ 
+
+ which neatly avoids the problem of calculating 0/0 that can occur with
+ the main definition as x → 0.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="ellint/ellint_intro.html"> Elliptic
+ Integral Overview</a></dt>
+<dt><a href="ellint/ellint_carlson.html"> Elliptic
+ Integrals - Carlson Form</a></dt>
+<dt><a href="ellint/ellint_1.html"> Elliptic Integrals
+ of the First Kind - Legendre Form</a></dt>
+<dt><a href="ellint/ellint_2.html"> Elliptic Integrals
+ of the Second Kind - Legendre Form</a></dt>
+<dt><a href="ellint/ellint_3.html"> Elliptic Integrals
+ of the Third Kind - Legendre Form</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/ellint_1.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost { namespace math {
+
+template <class T1, class T2>
+calculated-result-type ellint_1(T1 k, T2 phi);
+
+template <class T1, class T2, class Policy>
+calculated-result-type ellint_1(T1 k, T2 phi, const Policy&);
+
+template <class T>
+calculated-result-type ellint_1(T k);
+
+template <class T, class Policy>
+calculated-result-type ellint_1(T k, const Policy&);
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.ellint.ellint_1.description"></a><h6>
+<a name="id680847"></a>
+ Description
+ </h6>
+
+ These two functions evaluate the incomplete elliptic integral of the first
+ kind F(φ, k) and its complete counterpart K(k)
+ = F(π/2, k).
+ 
+
+ <img src="../../../../graphs/ellint_1.png" alt="ellint_1">
+ 
+
+ 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">result
+ type calculation rules</a> when T1 and T2 are different types:
+ when they are the same type then the result is the same type as the arguments.
+ 
+<pre class="programlisting">
+template <class T1, class T2>
+calculated-result-type ellint_1(T1 k, T2 phi);
+
+template <class T1, class T2, class Policy>
+calculated-result-type ellint_1(T1 k, T2 phi, const Policy&);
+</pre>
+
+ Returns the incomplete elliptic integral of the first kind F(φ,
+ k):
+ 
+
+ <img src="../../../../equations/ellint2.png">
+ 
+
+ Requires -1 <= k <= 1, otherwise returns the result of domain_error.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<pre class="programlisting">
+template <class T>
+calculated-result-type ellint_1(T k);
+
+template <class T>
+calculated-result-type ellint_1(T k, const Policy&);
+</pre>
+
+ Returns the complete elliptic integral of the first kind K(k):
+ 
+
+ <img src="../../../../equations/ellint6.png">
+ 
+
+ Requires -1 <= k <= 1, otherwise returns the result of domain_error.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<a name="math_toolkit.special.ellint.ellint_1.accuracy"></a><h6>
+<a name="id681495"></a>
+ Accuracy
+ </h6>
+
+ 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.
+ 
+<div class="table">
+<a name="id681528"></a>Table 34. Errors Rates in the Elliptic Integrals of the
+ First Kind
+<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>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ F(φ, k)
+ 
+ </th>
+<th>
+ 
+ K(k)
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32 / Visual C++ 8.0
+ 
+ </td>
+<td>
+ 
+ Peak=3 Mean=0.8
+ 
+ </td>
+<td>
+ 
+ Peak=1.8 Mean=0.7
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux / G++ 3.4
+ 
+ </td>
+<td>
+ 
+ Peak=2.6 Mean=1.7
+ 
+ </td>
+<td>
+ 
+ Peak=2.2 Mean=1.8
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HP-UX / HP aCC 6
+ 
+ </td>
+<td>
+ 
+ Peak=4.6 Mean=1.5
+ 
+ </td>
+<td>
+ 
+ Peak=3.7 Mean=1.5
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <a name="math_toolkit.special.ellint.ellint_1.testing"></a><h6>
+<a name="id681691"></a>
+ Testing
+ </h6>
+
+ 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.
+ 
+<a name="math_toolkit.special.ellint.ellint_1.implementation"></a><h6>
+<a name="id681730"></a>
+ Implementation
+ </h6>
+
+ These functions are implemented in terms of Carlson's integrals using the
+ relations:
+ 
+
+ <img src="../../../../equations/ellint19.png">
+ 
+
+ and
+ 
+
+ <img src="../../../../equations/ellint20.png">
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/ellint_2.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost { namespace math {
+
+template <class T1, class T2>
+calculated-result-type ellint_2(T1 k, T2 phi);
+
+template <class T1, class T2, class Policy>
+calculated-result-type ellint_2(T1 k, T2 phi, const Policy&);
+
+template <class T>
+calculated-result-type ellint_2(T k);
+
+template <class T, class Policy>
+calculated-result-type ellint_2(T k, const Policy&);
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.ellint.ellint_2.description"></a><h6>
+<a name="id682410"></a>
+ Description
+ </h6>
+
+ These two functions evaluate the incomplete elliptic integral of the second
+ kind E(φ, k) and its complete counterpart E(k)
+ = E(π/2, k).
+ 
+
+ <img src="../../../../graphs/ellint_2.png" alt="ellint_2">
+ 
+
+ 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">result
+ type calculation rules</a> when T1 and T2 are different types:
+ when they are the same type then the result is the same type as the arguments.
+ 
+<pre class="programlisting">
+template <class T1, class T2>
+calculated-result-type ellint_2(T1 k, T2 phi);
+
+template <class T1, class T2, class Policy>
+calculated-result-type ellint_2(T1 k, T2 phi, const Policy&);
+</pre>
+
+ Returns the incomplete elliptic integral of the second kind E(φ,
+ k):
+ 
+
+ <img src="../../../../equations/ellint3.png">
+ 
+
+ Requires -1 <= k <= 1, otherwise returns the result of domain_error.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<pre class="programlisting">
+template <class T>
+calculated-result-type ellint_2(T k);
+
+template <class T>
+calculated-result-type ellint_2(T k, const Policy&);
+</pre>
+
+ Returns the complete elliptic integral of the first kind E(k):
+ 
+
+ <img src="../../../../equations/ellint7.png">
+ 
+
+ Requires -1 <= k <= 1, otherwise returns the result of domain_error.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<a name="math_toolkit.special.ellint.ellint_2.accuracy"></a><h6>
+<a name="id687324"></a>
+ Accuracy
+ </h6>
+
+ 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.
+ 
+<div class="table">
+<a name="id687358"></a>Table 35. Errors Rates in the Elliptic Integrals of the
+ Second Kind
+<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>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ F(φ, k)
+ 
+ </th>
+<th>
+ 
+ K(k)
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32 / Visual C++ 8.0
+ 
+ </td>
+<td>
+ 
+ Peak=4.6 Mean=1.2
+ 
+ </td>
+<td>
+ 
+ Peak=3.5 Mean=1.0
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux / G++ 3.4
+ 
+ </td>
+<td>
+ 
+ Peak=4.3 Mean=1.1
+ 
+ </td>
+<td>
+ 
+ Peak=4.6 Mean=1.2
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HP-UX / HP aCC 6
+ 
+ </td>
+<td>
+ 
+ Peak=5.8 Mean=2.2
+ 
+ </td>
+<td>
+ 
+ Peak=10.8 Mean=2.3
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <a name="math_toolkit.special.ellint.ellint_2.testing"></a><h6>
+<a name="id687521"></a>
+ Testing
+ </h6>
+
+ 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.
+ 
+<a name="math_toolkit.special.ellint.ellint_2.implementation"></a><h6>
+<a name="id687560"></a>
+ Implementation
+ </h6>
+
+ These functions are implemented in terms of Carlson's integrals using the
+ relations:
+ 
+
+ <img src="../../../../equations/ellint21.png">
+ 
+
+ and
+ 
+
+ <img src="../../../../equations/ellint22.png">
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/ellint_3.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost { namespace math {
+
+template <class T1, class T2, class T3>
+calculated-result-type ellint_3(T1 k, T2 n, T3 phi);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ellint_3(T1 k, T2 n, T3 phi, const Policy&);
+
+template <class T1, class T2>
+calculated-result-type ellint_3(T1 k, T2 n);
+
+template <class T1, class T2, class Policy>
+calculated-result-type ellint_3(T1 k, T2 n, const Policy&);
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.ellint.ellint_3.description"></a><h6>
+<a name="id688377"></a>
+ Description
+ </h6>
+
+ These two functions evaluate the incomplete elliptic integral of the third
+ kind Π(n, φ, k) and its complete counterpart Π(n,
+ k) = E(n, π/2, k).
+ 
+
+ <img src="../../../../graphs/ellint_3.png" alt="ellint_3">
+ 
+
+ 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">result
+ type calculation rules</a> when the arguments are of different
+ types: when they are the same type then the result is the same type as
+ the arguments.
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type ellint_3(T1 k, T2 n, T3 phi);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ellint_3(T1 k, T2 n, T3 phi, const Policy&);
+</pre>
+
+ Returns the incomplete elliptic integral of the third kind Π(n,
+ φ, k):
+ 
+
+ <img src="../../../../equations/ellint4.png">
+ 
+
+ Requires -1 <= k <= 1 and n < 1/sin2(φ),
+ otherwise returns the result of domain_error
+ (outside this range the result would be complex).
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<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">
+ In addition, the region where n > 1 and φ is
+ not in the range [0, π/2] is currently unsupported and returns
+ the result of domain_error. For this
+ reason it is recomended that you keep φ inside its "natural"
+ range of [0, π/2].
+ </td></tr>
+</table></div>
+<pre class="programlisting">
+template <class T1, class T2>
+calculated-result-type ellint_3(T1 k, T2 n);
+
+template <class T1, class T2, class Policy>
+calculated-result-type ellint_3(T1 k, T2 n, const Policy&);
+</pre>
+
+ Returns the complete elliptic integral of the first kind Π(n,
+ k):
+ 
+
+ <img src="../../../../equations/ellint8.png">
+ 
+
+ Requires -1 <= k <= 1 and n < 1,
+ otherwise returns the result of domain_error
+ (outside this range the result would be complex).
+ 
+
+ [opitonal_policy]
+ 
+<a name="math_toolkit.special.ellint.ellint_3.accuracy"></a><h6>
+<a name="id689208"></a>
+ Accuracy
+ </h6>
+
+ 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.
+ 
+<div class="table">
+<a name="id689242"></a>Table 36. Errors Rates in the Elliptic Integrals of the
+ Third Kind
+<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>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ Π(n, φ, k)
+ 
+ </th>
+<th>
+ 
+ Π(n, k)
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32 / Visual C++ 8.0
+ 
+ </td>
+<td>
+ 
+ Peak=29 Mean=2.2
+ 
+ </td>
+<td>
+ 
+ Peak=3 Mean=0.8
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux / G++ 3.4
+ 
+ </td>
+<td>
+ 
+ Peak=14 Mean=1.3
+ 
+ </td>
+<td>
+ 
+ Peak=2.3 Mean=0.8
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HP-UX / HP aCC 6
+ 
+ </td>
+<td>
+ 
+ Peak=10 Mean=1.4
+ 
+ </td>
+<td>
+ 
+ Peak=4.2 Mean=1.1
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <a name="math_toolkit.special.ellint.ellint_3.testing"></a><h6>
+<a name="id689405"></a>
+ Testing
+ </h6>
+
+ 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.
+ 
+<a name="math_toolkit.special.ellint.ellint_3.implementation"></a><h6>
+<a name="id689444"></a>
+ Implementation
+ </h6>
+
+ The implementation for Π(n, φ, k) first siphons off the special cases:
+ 
+
+ Π(0, φ, k) = F(φ, k)
+ 
+
+ Π(n, π/2, k) = Π(n, k)
+ 
+
+ and
+ 
+
+ <img src="../../../../equations/ellint23.png">
+ 
+
+ Then if n < 0 the relations (A&S 17.7.15/16):
+ 
+
+ <img src="../../../../equations/ellint24.png">
+ 
+
+ are used to shift n to the range [0, 1].
+ 
+
+ Then the relations:
+ 
+
+ Π(n, -φ, k) = -Π(n, φ, k)
+ 
+
+ Π(n, φ+mπ, k) = Π(n, φ, k) + 2mΠ(n, k)
+ 
+
+ are used to move φ to the range [0, π/2].
+ 
+
+ The functions are then implemented in terms of Carlson's integrals using
+ the relations:
+ 
+
+ <img src="../../../../equations/ellint25.png">
+ 
+
+ and
+ 
+
+ <img src="../../../../equations/ellint26.png">
+ 
+
+ The remaining problem area occurs when n > 1 and φ is outside the range
+ [0, π/2]. In this range the reduction formula for large φ can no longer be
+ applied. Likewise the identities 17.7.7/8 in A&S for reducing n to
+ the range [0,1] appear to be no longer applicable.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/ellint_rf.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost { namespace math {
+
+template <class T1, class T2, class T3>
+calculated-result-type ellint_rf(T1 x, T2 y, T3 z)
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ellint_rf(T1 x, T2 y, T3 z, const Policy&)
+
+}} // namespaces
+</pre>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/ellint_rd.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost { namespace math {
+
+template <class T1, class T2, class T3>
+calculated-result-type ellint_rd(T1 x, T2 y, T3 z)
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ellint_rd(T1 x, T2 y, T3 z, const Policy&)
+
+}} // namespaces
+</pre>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/ellint_rj.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost { namespace math {
+
+template <class T1, class T2, class T3, class T4>
+calculated-result-type ellint_rj(T1 x, T2 y, T3 z, T4 p)
+
+template <class T1, class T2, class T3, class T4, class Policy>
+calculated-result-type ellint_rj(T1 x, T2 y, T3 z, T4 p, const Policy&)
+
+}} // namespaces
+</pre>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/ellint_rc.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost { namespace math {
+
+template <class T1, class T2>
+calculated-result-type ellint_rc(T1 x, T2 y)
+
+template <class T1, class T2, class Policy>
+calculated-result-type ellint_rc(T1 x, T2 y, const Policy&)
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.ellint.ellint_carlson.description"></a><h6>
+<a name="id677942"></a>
+ Description
+ </h6>
+
+ 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:
+ 
+
+ <img src="../../../../graphs/ellint_c.png" alt="ellint_c">
+ 
+
+ 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">result
+ type calculation rules</a> when the arguments are of different
+ types: otherwise the return is the same type as the arguments.
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type ellint_rf(T1 x, T2 y, T3 z)
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ellint_rf(T1 x, T2 y, T3 z, const Policy&)
+</pre>
+
+ Returns Carlson's Elliptic Integral RF:
+ 
+
+ <img src="../../../../equations/ellint9.png">
+ 
+
+ Requires that all of the arguments are non-negative, and at most one may
+ be zero. Otherwise returns the result of domain_error.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type ellint_rd(T1 x, T2 y, T3 z)
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ellint_rd(T1 x, T2 y, T3 z, const Policy&)
+</pre>
+
+ Returns Carlson's elliptic integral RD:
+ 
+
+ <img src="../../../../equations/ellint10.png">
+ 
+
+ Requires that x and y are non-negative, with at most one of them zero,
+ and that z >= 0. Otherwise returns the result of domain_error.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3, class T4>
+calculated-result-type ellint_rj(T1 x, T2 y, T3 z, T4 p)
+
+template <class T1, class T2, class T3, class T4, class Policy>
+calculated-result-type ellint_rj(T1 x, T2 y, T3 z, T4 p, const Policy&)
+</pre>
+
+ Returns Carlson's elliptic integral RJ:
+ 
+
+ <img src="../../../../equations/ellint11.png">
+ 
+
+ Requires that x, y and z are non-negative, with at most one of them zero,
+ and that p != 0. Otherwise returns the result of
+ domain_error.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ When p < 0 the function returns the <a href="http://en.wikipedia.org/wiki/Cauchy_principal_value" target="_top">Cauchy
+ principal value</a> using the relation:
+ 
+
+ <img src="../../../../equations/ellint17.png">
+ 
+<pre class="programlisting">
+template <class T1, class T2>
+calculated-result-type ellint_rc(T1 x, T2 y)
+
+template <class T1, class T2, class Policy>
+calculated-result-type ellint_rc(T1 x, T2 y, const Policy&)
+</pre>
+
+ Returns Carlson's elliptic integral RC:
+ 
+
+ <img src="../../../../equations/ellint12.png">
+ 
+
+ Requires that x > 0 and that y != 0.
+ Otherwise returns the result of domain_error.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ When y < 0 the function returns the <a href="http://mathworld.wolfram.com/CauchyPrincipalValue.html" target="_top">Cauchy
+ principal value</a> using the relation:
+ 
+
+ <img src="../../../../equations/ellint18.png">
+ 
+<a name="math_toolkit.special.ellint.ellint_carlson.testing"></a><h6>
+<a name="id679701"></a>
+ Testing
+ </h6>
+
+ There are two sets of tests.
+ 
+
+ Spot tests compare selected values with test data given in:
+ 
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ B. C. Carlson, <a href="http://arxiv.org/abs/math.CA/9409227" target="_top">Numerical
+ computation of real or complex elliptic integrals</a>.
+ Numerical Algorithms, Volume 10, Number 1 / March, 1995, pp 13-26.
+ 
+
+ 
+</blockquote></div>
+
+ Random test data generated using NTL::RR at 1000-bit precision and our
+ implementation checks for rounding-errors and/or regressions.
+ 
+
+ There are also sanity checks that use the inter-relations between the integrals
+ to verify their correctness: see the above Carlson paper for details.
+ 
+<a name="math_toolkit.special.ellint.ellint_carlson.accuracy"></a><h6>
+<a name="id679771"></a>
+ Accuracy
+ </h6>
+
+ 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.
+ 
+<div class="table">
+<a name="id679806"></a>Table 33. Errors Rates in the Carlson Elliptic Integrals
+<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>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ RF
+ 
+ </th>
+<th>
+ 
+ RD
+ 
+ </th>
+<th>
+ 
+ RJ
+ 
+ </th>
+<th>
+ 
+ RC
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32 / Visual C++ 8.0
+ 
+ </td>
+<td>
+ 
+ Peak=2.9 Mean=0.75
+ 
+ </td>
+<td>
+ 
+ Peak=2.6 Mean=0.9
+ 
+ </td>
+<td>
+ 
+ Peak=108 Mean=6.9
+ 
+ </td>
+<td>
+ 
+ Peak=2.4 Mean=0.6
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux / G++ 3.4
+ 
+ </td>
+<td>
+ 
+ Peak=2.5 Mean=0.75
+ 
+ </td>
+<td>
+ 
+ Peak=2.7 Mean=0.9
+ 
+ </td>
+<td>
+ 
+ Peak=105 Mean=8
+ 
+ </td>
+<td>
+ 
+ Peak=1.9 Mean=0.7
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HP-UX / HP aCC 6
+ 
+ </td>
+<td>
+ 
+ Peak=5.3 Mean=1.6
+ 
+ </td>
+<td>
+ 
+ Peak=2.9 Mean=0.99
+ 
+ </td>
+<td>
+ 
+ Peak=180 Mean=12
+ 
+ </td>
+<td>
+ 
+ Peak=1.8 Mean=0.7
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <a name="math_toolkit.special.ellint.ellint_carlson.implementation"></a><h6>
+<a name="id680036"></a>
+ Implementation
+ </h6>
+
+ The key of Carlson's algorithm [Carlson79]
+ is the duplication theorem:
+ 
+
+ <img src="../../../../equations/ellint13.png">
+ 
+
+ By applying it repeatedly, x, y,
+ z get closer and closer. When they are nearly equal,
+ the special case equation
+ 
+
+ <img src="../../../../equations/ellint16.png">
+ 
+
+ is used. More specifically, [R F] is evaluated from
+ a Taylor series expansion to the fifth order. The calculations of the other
+ three integrals are analogous.
+ 
+
+ For p < 0 in RJ(x, y, z, p)
+ and y < 0 in RC(x, y), 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:
+ 
+
+ <img src="../../../../equations/ellint17.png">
+ 
+
+ <img src="../../../../equations/ellint18.png">
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ The main reference for the elliptic integrals is:
+ 
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ 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.
+ 
+
+ 
+</blockquote></div>
+
+ Mathworld also contain a lot of useful background information:
+ 
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ <a href="http://mathworld.wolfram.com/EllipticIntegral.html" target="_top">Weisstein,
+ Eric W. "Elliptic Integral." From MathWorld--A Wolfram Web
+ Resource.</a>
+ 
+
+ 
+</blockquote></div>
+
+ As does <a href="http://en.wikipedia.org/wiki/Elliptic_integral" target="_top">Wikipedia
+ Elliptic integral</a>.
+ 
+<a name="math_toolkit.special.ellint.ellint_intro.notation"></a><h5>
+<a name="id674819"></a>
+ Notation
+ </h5>
+
+ All variables are real numbers unless otherwise noted.
+ 
+<a name="ellint_def"></a><a name="math_toolkit.special.ellint.ellint_intro.definition"></a><h5>
+<a name="id674855"></a>
+ Definition
+ </h5>
+
+ <img src="../../../../equations/ellint1.png">
+ 
+
+ is called elliptic integral if R(t, s) is a rational
+ function of t and s, and s2
+ is a cubic or quartic polynomial in t.
+ 
+
+ 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:
+ 
+
+ Elliptic Integral of the First Kind (Legendre form)
+ 
+
+ <img src="../../../../equations/ellint2.png">
+ 
+
+ Elliptic Integral of the Second Kind (Legendre form)
+ 
+
+ <img src="../../../../equations/ellint3.png">
+ 
+
+ Elliptic Integral of the Third Kind (Legendre form)
+ 
+
+ <img src="../../../../equations/ellint4.png">
+ 
+
+ where
+ 
+
+ <img src="../../../../equations/ellint5.png">
+ 
+<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">
+
+ φ is called the amplitude.
+ 
+
+ k is called the modulus.
+ 
+
+ α is called the modular angle.
+ 
+
+ n is called the characteristic.
+ 
+</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">
+
+ Perhaps more than any other special functions the elliptic integrals
+ are expressed in a variety of different ways. In particular, the final
+ parameter k (the modulus) may be expressed using
+ a modular angle α, or a parameter m. These are related
+ by:
+ 
+
+ k = sinα
+ 
+
+ m = k2 = sin2α
+ 
+
+ So that the integral of the third kind (for example) may be expressed
+ as either:
+ 
+
+ Π(n, φ, k)
+ 
+
+ Π(n, φ \ α)
+ 
+
+ Π(n, φ| m)
+ 
+
+ To further complicate matters, some texts refer to the complement
+ of the parameter m, or 1 - m, where:
+ 
+
+ 1 - m = 1 - k2 = cos2α
+ 
+
+ This implementation uses k 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!
+ 
+</td></tr>
+</table></div>
+
+ When φ = π / 2, the elliptic integrals
+ are called complete.
+ 
+
+ Complete Elliptic Integral of the First Kind (Legendre form)
+ 
+
+ <img src="../../../../equations/ellint6.png">
+ 
+
+ Complete Elliptic Integral of the Second Kind (Legendre form)
+ 
+
+ <img src="../../../../equations/ellint7.png">
+ 
+
+ Complete Elliptic Integral of the Third Kind (Legendre form)
+ 
+
+ <img src="../../../../equations/ellint8.png">
+ 
+
+ Carlson [Carlson77] [Carlson78] gives an alternative definition
+ of elliptic integral's canonical forms:
+ 
+
+ Carlson's Elliptic Integral of the First Kind
+ 
+
+ <img src="../../../../equations/ellint9.png">
+ 
+
+ where x, y, z
+ are nonnegative and at most one of them may be zero.
+ 
+
+ Carlson's Elliptic Integral of the Second Kind
+ 
+
+ <img src="../../../../equations/ellint10.png">
+ 
+
+ where x, y are nonnegative, at
+ most one of them may be zero, and z must be positive.
+ 
+
+ Carlson's Elliptic Integral of the Third Kind
+ 
+
+ <img src="../../../../equations/ellint11.png">
+ 
+
+ where x, y, z
+ are nonnegative, at most one of them may be zero, and p
+ must be nonzero.
+ 
+
+ Carlson's Degenerate Elliptic Integral
+ 
+
+ <img src="../../../../equations/ellint12.png">
+ 
+
+ where x is nonnegative and y
+ is nonzero.
+ 
+<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">
+
+ RC(x, y) = RF(x, y, y)
+ 
+
+ RD(x, y, z) = RJ(x, y, z, z)
+ 
+</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>
+
+ Carlson proved in [Carlson78]
+ that
+ 
+
+ <img src="../../../../equations/ellint13.png">
+ 
+<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>
+
+ The Legendre form and Carlson form of elliptic integrals are related by
+ equations:
+ 
+
+ <img src="../../../../equations/ellint14.png">
+ 
+
+ In particular,
+ 
+
+ <img src="../../../../equations/ellint15.png">
+ 
+<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>
+
+ 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.
+ 
+<a name="ellint_refs"></a><a name="math_toolkit.special.ellint.ellint_intro.references"></a><h5>
+<a name="id675843"></a>
+ References
+ </h5>
+
+ Special mention goes to:
+ 
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ A. M. Legendre, Traitd des Fonctions Elliptiques et des Integrales
+ Euleriennes, Vol. 1. Paris (1825).
+ 
+
+ 
+</blockquote></div>
+
+ However the main references are:
+ 
+<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, Computing elliptic integrals by duplication,
+ Numerische Mathematik, vol 33, 1 (1979).
+ </li>
+<li>
+ B.C. Carlson, Elliptic Integrals of the First Kind,
+ SIAM Journal on Mathematical Analysis, vol 8, 231 (1977).
+ </li>
+<li>
+ B.C. Carlson, Short Proofs of Three Theorems on Elliptic Integrals,
+ SIAM Journal on Mathematical Analysis, vol 9, 524 (1978).
+ </li>
+<li>
+ B.C. Carlson and E.M. Notis, ALGORITHM 577: Algorithms for
+ Incomplete Elliptic Integrals, ACM Transactions on Mathematmal
+ Software, vol 7, 398 (1981).
+ </li>
+<li>
+ B. C. Carlson, On computing elliptic integrals and functions.
+ J. Math. and Phys., 44 (1965), pp. 36-51.
+ </li>
+<li>
+ B. C. Carlson, A table of elliptic integrals of the second
+ kind. Math. Comp., 49 (1987), pp. 595-606. (Supplement, ibid.,
+ pp. S13-S17.)
+ </li>
+<li>
+ B. C. Carlson, A table of elliptic integrals of the third kind.
+ Math. Comp., 51 (1988), pp. 267-280. (Supplement, ibid., pp. S1-S5.)
+ </li>
+<li>
+ B. C. Carlson, A table of elliptic integrals: cubic cases.
+ Math. Comp., 53 (1989), pp. 327-333.
+ </li>
+<li>
+ B. C. Carlson, A table of elliptic integrals: one quadratic
+ factor. Math. Comp., 56 (1991), pp. 267-280.
+ </li>
+<li>
+ B. C. Carlson, A table of elliptic integrals: two quadratic
+ factors. Math. Comp., 59 (1992), pp. 165-180.
+ </li>
+<li>
+ B. C. Carlson, <a href="http://arxiv.org/abs/math.CA/9409227" target="_top">Numerical
+ computation of real or complex elliptic integrals</a>.
+ Numerical Algorithms, Volume 10, Number 1 / March, 1995, p13-26.
+ </li>
+<li>
+ B. C. Carlson and John L. Gustafson, <a href="http://arxiv.org/abs/math.CA/9310223" target="_top">Asymptotic
+ Approximations for Symmetric Elliptic Integrals</a>, SIAM
+ Journal on Mathematical Analysis, Volume 25, Issue 2 (March 1994), 288-303.
+ </li>
+</ol></div>
+
+ The following references, while not directly relevent to our implementation,
+ may also be of interest:
+ 
+<div class="orderedlist"><ol type="1">
+<li>
+ R. Burlisch, Numerical Compuation of Elliptic Integrals and
+ Elliptic Functions. Numerical Mathematik 7, 78-90.
+ </li>
+<li>
+ R. Burlisch, An extension of the Bartky Transformation to Incomplete
+ Elliptic Integrals of the Third Kind. Numerical Mathematik
+ 13, 266-284.
+ </li>
+<li>
+ R. Burlisch, Numerical Compuation of Elliptic Integrals and
+ Elliptic Functions. III. Numerical Mathematik 13, 305-315.
+ </li>
+<li>
+ T. Fukushima and H. Ishizaki, <a href="http://adsabs.harvard.edu/abs/1994CeMDA..59..237F" target="_top">Numerical
+ Computation of Incomplete Elliptic Integrals of a General Form.</a>
+ 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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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> Factorial</dt>
+<dt><a href="factorials/sf_double_factorial.html">
+ Double Factorial</a></dt>
+<dt><a href="factorials/sf_rising_factorial.html">
+ Rising Factorial</a></dt>
+<dt><a href="factorials/sf_falling_factorial.html">
+ Falling Factorial</a></dt>
+<dt><a href="factorials/sf_binomial.html"> Binomial
+ Coefficients</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/binomial.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+T binomial_coefficient(unsigned n, unsigned k);
+
+template <class T, class Policy>
+T binomial_coefficient(unsigned n, unsigned k, const Policy&);
+
+}} // namespaces
+</pre>
+
+ Returns the binomial coefficient: nCk.
+ 
+
+ Requires k <= n.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ May return the result of overflow_error
+ if the result is too large to represent in type T.
+ 
+<a name="math_toolkit.special.factorials.sf_binomial.accuracy"></a><h5>
+<a name="id637068"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.special.factorials.sf_binomial.testing"></a><h5>
+<a name="id637108"></a>
+ Testing
+ </h5>
+
+ The spot tests for the binomial coefficients use data generated by functions.wolfram.com.
+ 
+<a name="math_toolkit.special.factorials.sf_binomial.implementation"></a><h5>
+<a name="id637138"></a>
+ Implementation
+ </h5>
+
+ Binomial coefficients are calculated using table lookup of factorials where
+ possible using:
+ 
+
+ nCk = n! / (k!(n-k)!)
+ 
+
+ Otherwise it is implemented in terms of the beta function using the relations:
+ 
+
+ nCk = 1 / (k * beta(k,
+ n-k+1))
+ 
+
+ and
+ 
+
+ nCk = 1 / ((n-k) * beta(k+1,
+ n-k))
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/factorials.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+T double_factorial(unsigned i);
+
+template <class T, class Policy>
+T double_factorial(unsigned i, const Policy&);
+
+}} // namespaces
+</pre>
+
+ Returns <code class="literal">i!!</code>.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ 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 i where table lookup
+ of i! is possible.
+ 
+<a name="math_toolkit.special.factorials.sf_double_factorial.accuracy"></a><h5>
+<a name="id635383"></a>
+ Accuracy
+ </h5>
+
+ The implementation uses a trivial adaptation of the factorial function,
+ so error rates should be no more than a couple of epsilon higher.
+ 
+<a name="math_toolkit.special.factorials.sf_double_factorial.testing"></a><h5>
+<a name="id635414"></a>
+ Testing
+ </h5>
+
+ The spot tests for the double factorial use data generated by functions.wolfram.com.
+ 
+<a name="math_toolkit.special.factorials.sf_double_factorial.implementation"></a><h5>
+<a name="id635446"></a>
+ Implementation
+ </h5>
+
+ The double factorial is implemented in terms of the factorial and gamma
+ functions using the relations:
+ 
+
+ (2n)!! = 2n * n!
+ 
+
+ (2n+1)!! = (2n+1)! / (2n n!)
+ 
+
+ and
+ 
+
+ (2n-1)!! = Γ((2n+1)/2) * 2n / sqrt(pi)
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/factorials.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+T factorial(unsigned i);
+
+template <class T, class Policy>
+T factorial(unsigned i, const Policy&);
+
+template <class T>
+T unchecked_factorial(unsigned i);
+
+template <class T>
+struct max_factorial;
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.factorials.sf_factorial.description"></a><h5>
+<a name="id634342"></a>
+ Description
+ </h5>
+<pre class="programlisting">
+template <class T>
+T factorial(unsigned i);
+
+template <class T, class Policy>
+T factorial(unsigned i, const Policy&);
+</pre>
+
+ Returns <code class="literal">i!</code>.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ For <code class="literal">i <= max_factorial<T>::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.
+ 
+
+ If <code class="literal">i</code> is so large that the result can not be represented
+ in type T, then calls overflow_error.
+ 
+<pre class="programlisting">
+template <class T>
+T unchecked_factorial(unsigned i);
+</pre>
+
+ Returns <code class="literal">i!</code>.
+ 
+
+ 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 <= max_factorial<T>::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.
+ 
+<pre class="programlisting">
+template <class T>
+struct max_factorial
+{
+ static const unsigned value = X;
+};
+</pre>
+
+ This traits class defines the largest value that can be passed to <code class="literal">unchecked_factorial</code>.
+ The member <code class="computeroutput">value</code> can be
+ used where integral constant expressions are required: for example to define
+ the size of further tables that depend on the factorials.
+ 
+<a name="math_toolkit.special.factorials.sf_factorial.accuracy"></a><h5>
+<a name="id634860"></a>
+ Accuracy
+ </h5>
+
+ For arguments smaller than <code class="computeroutput">max_factorial<T>::value</code>
+ the result should be correctly rounded. For larger arguments the accuracy
+ will be the same as for tgamma.
+ 
+<a name="math_toolkit.special.factorials.sf_factorial.testing"></a><h5>
+<a name="id634932"></a>
+ Testing
+ </h5>
+
+ Basic sanity checks and spot values to verify the data tables: the main
+ tests for the tgamma
+ function handle those cases already.
+ 
+<a name="math_toolkit.special.factorials.sf_factorial.implementation"></a><h5>
+<a name="id634973"></a>
+ Implementation
+ </h5>
+
+ The factorial function is table driven for small arguments, and is implemented
+ in terms of tgamma
+ for larger arguments.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/factorials.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+calculated-result-type falling_factorial(T x, unsigned i);
+
+template <class T, class Policy>
+calculated-result-type falling_factorial(T x, unsigned i, const Policy&);
+
+}} // namespaces
+</pre>
+
+ Returns the falling factorial of x and i:
+ 
+
+ falling_factorial(x, i) = x(x-1)(x-2)(x-3)...(x-i+1)
+ 
+
+ Note that this function is only defined for positive i,
+ hence the <code class="computeroutput">unsigned</code> second
+ argument. Argument x can be either positive or negative
+ however.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ May return the result of overflow_error
+ if the result is too large to represent in type T.
+ 
+
+ 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">result
+ type calculation rules</a>: the type of the result is <code class="computeroutput">double</code> if T is an integer type, otherwise
+ the type of the result is T.
+ 
+<a name="math_toolkit.special.factorials.sf_falling_factorial.accuracy"></a><h5>
+<a name="id636551"></a>
+ Accuracy
+ </h5>
+
+ The accuracy will be the same as the tgamma_delta_ratio
+ function.
+ 
+<a name="math_toolkit.special.factorials.sf_falling_factorial.testing"></a><h5>
+<a name="id636590"></a>
+ Testing
+ </h5>
+
+ The spot tests for the falling factorials use data generated by functions.wolfram.com.
+ 
+<a name="math_toolkit.special.factorials.sf_falling_factorial.implementation"></a><h5>
+<a name="id636621"></a>
+ Implementation
+ </h5>
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/factorials.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+calculated-result-type rising_factorial(T x, int i);
+
+template <class T, class Policy>
+calculated-result-type rising_factorial(T x, int i, const Policy&);
+
+}} // namespaces
+</pre>
+
+ Returns the rising factorial of x and i:
+ 
+
+ rising_factorial(x, i) = Γ(x + i) / Γ(x);
+ 
+
+ or
+ 
+
+ rising_factorial(x, i) = x(x+1)(x+2)(x+3)...(x+i)
+ 
+
+ Note that both x and i can be
+ negative as well as positive.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ May return the result of overflow_error
+ if the result is too large to represent in type T.
+ 
+
+ 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">result
+ type calculation rules</a>: the type of the result is <code class="computeroutput">double</code> if T is an integer type, otherwise
+ the type of the result is T.
+ 
+<a name="math_toolkit.special.factorials.sf_rising_factorial.accuracy"></a><h5>
+<a name="id635971"></a>
+ Accuracy
+ </h5>
+
+ The accuracy will be the same as the tgamma_delta_ratio
+ function.
+ 
+<a name="math_toolkit.special.factorials.sf_rising_factorial.testing"></a><h5>
+<a name="id636009"></a>
+ Testing
+ </h5>
+
+ The spot tests for the rising factorials use data generated by functions.wolfram.com.
+ 
+<a name="math_toolkit.special.factorials.sf_rising_factorial.implementation"></a><h5>
+<a name="id636041"></a>
+ Implementation
+ </h5>
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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">
+#define FP_ZERO /* implementation specific value */
+#define FP_NORMAL /* implementation specific value */
+#define FP_INFINITE /* implementation specific value */
+#define FP_NAN /* implementation specific value */
+#define FP_SUBNORMAL /* implementation specific value */
+
+template <class T>
+int fpclassify(T t);
+
+template <class T>
+bool isfinite(T z);
+
+template <class T>
+bool isinf(T t);
+
+template <class T>
+bool isnan(T t);
+
+template <class T>
+bool isnormal(T t);
+</pre>
+<a name="math_toolkit.special.fpclass.description"></a><h5>
+<a name="id697014"></a>
+ Description
+ </h5>
+
+ 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<>
+ to function.
+ 
+
+ Note that the definition of these functions does not suppress the
+ definition of these names as macros by math.h on those platforms
+ that already provide these as macros. That mean that the following have differing
+ meanings:
+ 
+<pre class="programlisting">
+using namespace boost::math;
+
+// This might call a global macro if defined,
+// but might not work if the type of z is unsupported
+// by the std lib macro:
+isnan(z);
+//
+// This calls the Boost version
+// (found via the "using namespace boost::math" declaration)
+// it works for any type that has numeric_limits support for type z:
+(isnan)(z);
+//
+// As above but with namespace qualification.
+(boost::math::isnan)(z);
+//
+// This will cause a compiler error is isnan is a native macro:
+boost::math::isnan(z);
+// So always use (boost::math::isnan)(z); instead.
+</pre>
+
+ Detailed descriptions for each of these functions follows:
+ 
+<pre class="programlisting">
+template <class T>
+int fpclassify(T t);
+</pre>
+
+ Returns an integer value that classifies the value t:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ fpclassify value
+ 
+ </th>
+<th>
+ 
+ class of t.
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ FP_ZERO
+ 
+ </td>
+<td>
+ 
+ If t is zero.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ FP_NORMAL
+ 
+ </td>
+<td>
+ 
+ If t is a non-zero, non-denormalised finite
+ value.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ FP_INFINITE
+ 
+ </td>
+<td>
+ 
+ If t is plus or minus infinity.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ FP_NAN
+ 
+ </td>
+<td>
+ 
+ If t is a NaN.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ FP_SUBNORMAL
+ 
+ </td>
+<td>
+ 
+ If t is a denormalised number.
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+<pre class="programlisting">
+template <class T>
+bool isfinite(T z);
+</pre>
+
+ Returns true only if z is not an infinity or a NaN.
+ 
+<pre class="programlisting">
+template <class T>
+bool isinf(T t);
+</pre>
+
+ Returns true only if z is plus or minus infinity.
+ 
+<pre class="programlisting">
+template <class T>
+bool isnan(T t);
+</pre>
+
+ Returns true only if z is a NaN.
+ 
+<pre class="programlisting">
+template <class T>
+bool isnormal(T t);
+</pre>
+
+ Returns true only if z is a normal number (not zero,
+ infinite, NaN, or denormalised).
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="inv_hyper/inv_hyper_over.html"> Inverse
+ Hyperbolic Functions Overview</a></dt>
+<dt> acosh</dt>
+<dt> asinh</dt>
+<dt> atanh</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/acosh.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+template<class T>
+calculated-result-type acosh(const T x);
+
+template<class T, class Policy>
+calculated-result-type acosh(const T x, const Policy&);
+</pre>
+
+ Computes the reciprocal of (the restriction to the range of <code class="literal">[0;+∞[</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.
+ 
+
+ If x is in the range <code class="literal">]-∞;+1[</code> then returns the result
+ of domain_error.
+ 
+
+ 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">result
+ type calculation rules</a>: the return type is <code class="computeroutput">double</code> when T is an integer type, and T
+ otherwise.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/asinh.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+template<class T>
+calculated-result-type asinh(const T x);
+
+template<class T, class Policy>
+calculated-result-type asinh(const T x, const Policy&);
+</pre>
+
+ 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.
+ 
+
+ 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">result
+ type calculation rules</a>: the return type is <code class="computeroutput">double</code> when T is an integer type, and T
+ otherwise.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/atanh.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+template<class T>
+calculated-result-type atanh(const T x);
+
+template<class T, class Policy>
+calculated-result-type atanh(const T x, const Policy&);
+</pre>
+
+ 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.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ If x is in the range <code class="literal">]-∞;-1[</code> or in the range <code class="literal">]+1;+∞[</code>
+ then returns the result of domain_error.
+ 
+
+ If x is in the range <code class="literal">[-1;-1+ε[</code>, then the result of -overflow_error is returned, with ε
+denoting
+ numeric_limits<T>::epsilon().
+ 
+
+ If x is in the range <code class="literal">]+1-ε;+1]</code>, then the result of overflow_error is returned, with ε
+denoting
+ numeric_limits<T>::epsilon().
+ 
+
+ 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">result
+ type calculation rules</a>: the return type is <code class="computeroutput">double</code> when T is an integer type, and T
+ otherwise.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ The exponential funtion is defined, for all objects for which this makes
+ sense, as the power series <img src="../../../../equations/special_functions_blurb1.png">,
+ with <code class="literal">n! = 1x2x3x4x5...xn</code> (and
+ <code class="literal">0! = 1</code> by definition) being the
+ factorial of <code class="literal">n</code>. In particular,
+ the exponential function is well defined for real numbers, complex number,
+ quaternions, octonions, and matrices of complex numbers, among others.
+ 
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ Graph of exp on R
+ 
+
+ 
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ <img src="../../../../graphs/exp_on_r.png" alt="exp_on_r">
+ 
+
+ 
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ Real and Imaginary parts of exp on
+ C
+ 
+
+ 
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ <img src="../../../../graphs/im_exp_on_c.png" alt="im_exp_on_c">
+ 
+
+ 
+</blockquote></div>
+
+ The hyperbolic functions are defined as power series which can be computed
+ (for reals, complex, quaternions and octonions) as:
+ 
+
+ Hyperbolic cosine: <img src="../../../../equations/special_functions_blurb5.png">
+ 
+
+ Hyperbolic sine: <img src="../../../../equations/special_functions_blurb6.png">
+ 
+
+ Hyperbolic tangent: <img src="../../../../equations/special_functions_blurb7.png">
+ 
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ Trigonometric functions on R (cos:
+ purple; sin: red; tan: blue)
+ 
+
+ 
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ <img src="../../../../graphs/trigonometric.png" alt="trigonometric">
+ 
+
+ 
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ Hyperbolic functions on r (cosh: purple;
+ sinh: red; tanh: blue)
+ 
+
+ 
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ <img src="../../../../graphs/hyperbolic.png" alt="hyperbolic">
+ 
+
+ 
+</blockquote></div>
+
+ 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;+∞[</code>, and
+ therefore both have inverses. The hyperbolic cosine is one to one from
+ <code class="literal">]-∞;+1[</code> onto <code class="literal">]-∞;-1[</code> (and from <code class="literal">]+1;+∞[</code>
+ onto <code class="literal">]-∞;-1[</code>); the inverse function we use here is defined
+ on <code class="literal">]-∞;-1[</code> with range <code class="literal">]-∞;+1[</code>.
+ 
+
+ The inverse of the hyperbolic tangent is called the Argument hyperbolic
+ tangent, and can be computed as <img src="../../../../equations/special_functions_blurb15.png">.
+ 
+
+ The inverse of the hyperbolic sine is called the Argument hyperbolic sine,
+ and can be computed (for <code class="literal">[-1;-1+ε[</code>) as <img src="../../../../equations/special_functions_blurb17.png">.
+ 
+
+ The inverse of the hyperbolic cosine is called the Argument hyperbolic
+ cosine, and can be computed as <img src="../../../../equations/special_functions_blurb18.png">.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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> log1p</dt>
+<dt> expm1</dt>
+<dt> cbrt</dt>
+<dt> sqrt1pm1</dt>
+<dt> powm1</dt>
+<dt> hypot</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/cbrt.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+calculated-result-type cbrt(T x);
+
+template <class T, class Policy>
+calculated-result-type cbrt(T x, const Policy&);
+
+}} // namespaces
+</pre>
+
+ Returns the cubed root of x: x1/3.
+ 
+
+ 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">result
+ type calculation rules</a>: the return is <code class="computeroutput">double</code>
+ when x is an integer type and T otherwise.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Implemented using Halley iteration.
+ 
+<a name="math_toolkit.special.powers.cbrt.accuracy"></a><h5>
+<a name="id691579"></a>
+ Accuracy
+ </h5>
+
+ For built in floating-point types <code class="computeroutput">cbrt</code>
+ should have approximately 2 epsilon accuracy.
+ 
+<a name="math_toolkit.special.powers.cbrt.testing"></a><h5>
+<a name="id691621"></a>
+ Testing
+ </h5>
+
+ A mixture of spot test sanity checks, and random high precision test values
+ calculated using NTL::RR at 1000-bit precision.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/expm1.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+calculated-result-type expm1(T x);
+
+template <class T, class Policy>
+calculated-result-type expm1(T x, const Policy&);
+
+}} // namespaces
+</pre>
+
+ Returns ex - 1.
+ 
+
+ 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">result
+ type calculation rules</a>: the return is <code class="computeroutput">double</code>
+ when x is an integer type and T otherwise.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ For small x, then <code class="computeroutput">ex</code> is very close to 1, as a result calculating <code class="computeroutput">ex - 1</code> results in
+ catastrophic cancellation errors when x is small. <code class="computeroutput">expm1</code>
+ calculates <code class="computeroutput">ex - 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ɛ).
+ 
+
+ Finally when BOOST_HAS_EXPM1 is defined then the <code class="computeroutput">float/double/long double</code>
+ specializations of this template simply forward to the platform's native
+ (POSIX) implementation of this function.
+ 
+<a name="math_toolkit.special.powers.expm1.accuracy"></a><h5>
+<a name="id691116"></a>
+ Accuracy
+ </h5>
+
+ For built in floating point types <code class="computeroutput">expm1</code>
+ should have approximately 1 epsilon accuracy.
+ 
+<a name="math_toolkit.special.powers.expm1.testing"></a><h5>
+<a name="id691157"></a>
+ Testing
+ </h5>
+
+ A mixture of spot test sanity checks, and random high precision test values
+ calculated using NTL::RR at 1000-bit precision.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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">
+template <class T1, class T2>
+calculated-result-type hypot(T1 x, T2 y);
+
+template <class T1, class T2, class Policy>
+calculated-result-type hypot(T1 x, T2 y, const Policy&);
+</pre>
+
+ Effects: computes <img src="../../../../equations/hypot.png">
+in such a
+ way as to avoid undue underflow and overflow.
+ 
+
+ 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">result
+ type calculation rules</a> when T1 and T2 are of different
+ types.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ When calculating <img src="../../../../equations/hypot.png"> it's quite easy for the intermediate terms to
+ either overflow or underflow, even though the result is in fact perfectly
+ representable.
+ 
+<a name="math_toolkit.special.powers.hypot.implementation"></a><h5>
+<a name="id693089"></a>
+ Implementation
+ </h5>
+
+ The function is even and symmetric in x and y, so first take assume x,y
+ > 0 and x > y (we can permute the
+ arguments if this is not the case).
+ 
+
+ Then if x * ε >= y we can simply return x.
+ 
+
+ Otherwise the result is given by:
+ 
+
+ <img src="../../../../equations/hypot2.png">
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/log1p.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+calculated-result-type log1p(T x);
+
+template <class T, class Policy>
+calculated-result-type log1p(T x, const Policy&);
+
+}} // namespaces
+</pre>
+
+ Returns the natural logarithm of <code class="computeroutput">x+1</code>.
+ 
+
+ 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">result
+ type calculation rules</a>: the return is <code class="computeroutput">double</code>
+ when x is an integer type and T otherwise.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ There are many situations where it is desirable to compute <code class="computeroutput">log(x+1)</code>. However, for small <code class="computeroutput">x</code>
+ then <code class="computeroutput">x+1</code> suffers from catastrophic cancellation
+ errors so that <code class="computeroutput">x+1 == 1</code>
+ and <code class="computeroutput">log(x+1) == 0</code>,
+ when in fact for very small x, the best approximation to <code class="computeroutput">log(x+1)</code> would be <code class="computeroutput">x</code>.
+ <code class="computeroutput">log1p</code> calculates the best
+ approximation to <code class="computeroutput">log(1+x)</code> using a Taylor series expansion for accuracy
+ (less than 2ɛ). Alternatively note that there are faster methods available,
+ for example using the equivalence:
+ 
+<pre class="programlisting">
+log(1+x) == (log(1+x) * x) / ((1-x) - 1)
+</pre>
+
+ 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.
+ 
+
+ Finally when BOOST_HAS_LOG1P is defined then the <code class="computeroutput">float/double/long double</code>
+ specializations of this template simply forward to the platform's native
+ (POSIX) implementation of this function.
+ 
+<a name="math_toolkit.special.powers.log1p.accuracy"></a><h5>
+<a name="id690557"></a>
+ Accuracy
+ </h5>
+
+ For built in floating point types <code class="computeroutput">log1p</code>
+ should have approximately 1 epsilon accuracy.
+ 
+<a name="math_toolkit.special.powers.log1p.testing"></a><h5>
+<a name="id690598"></a>
+ Testing
+ </h5>
+
+ A mixture of spot test sanity checks, and random high precision test values
+ calculated using NTL::RR at 1000-bit precision.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/powm1.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T1, class T2>
+calculated-result-type powm1(T1 x, T2 y);
+
+template <class T1, class T2, class Policy>
+calculated-result-type powm1(T1 x, T2 y, const Policy&);
+
+}} // namespaces
+</pre>
+
+ Returns xy - 1.
+ 
+
+ 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">result
+ type calculation rules</a> when T1 and T2 are dufferent types.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ There are two domains where this is useful: when y is very small, or when
+ x is close to 1.
+ 
+
+ Implemented in terms of <code class="computeroutput">expm1</code>.
+ 
+<a name="math_toolkit.special.powers.powm1.accuracy"></a><h5>
+<a name="id692648"></a>
+ Accuracy
+ </h5>
+
+ Should have approximately 2-3 epsilon accuracy.
+ 
+<a name="math_toolkit.special.powers.powm1.testing"></a><h5>
+<a name="id692678"></a>
+ Testing
+ </h5>
+
+ A selection of random high precision test values calculated using NTL::RR
+ at 1000-bit precision.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/sqrt1pm1.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+calculated-result-type sqrt1pm1(T x);
+
+template <class T, class Policy>
+calculated-result-type sqrt1pm1(T x, const Policy&);
+
+}} // namespaces
+</pre>
+
+ Returns <code class="computeroutput">sqrt(1+x) - 1</code>.
+ 
+
+ 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">result
+ type calculation rules</a>: the return is <code class="computeroutput">double</code>
+ when x is an integer type and T otherwise.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ This function is useful when you need the difference between sqrt(x) and
+ 1, when x is itself close to 1.
+ 
+
+ Implemented in terms of <code class="computeroutput">log1p</code>
+ and <code class="computeroutput">expm1</code>.
+ 
+<a name="math_toolkit.special.powers.sqrt1pm1.accuracy"></a><h5>
+<a name="id692117"></a>
+ Accuracy
+ </h5>
+
+ For built in floating-point types <code class="computeroutput">sqrt1pm1</code>
+ should have approximately 3 epsilon accuracy.
+ 
+<a name="math_toolkit.special.powers.sqrt1pm1.testing"></a><h5>
+<a name="id692158"></a>
+ Testing
+ </h5>
+
+ A selection of random high precision test values calculated using NTL::RR
+ at 1000-bit precision.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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> Beta</dt>
+<dt><a href="sf_beta/ibeta_function.html"> Incomplete
+ Beta Functions</a></dt>
+<dt><a href="sf_beta/ibeta_inv_function.html"> The
+ Incomplete Beta Function Inverses</a></dt>
+<dt><a href="sf_beta/beta_derivative.html"> Derivative
+ of the Incomplete Beta Function</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/beta.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T1, class T2, class T3>
+calculated-result-type ibeta_derivative(T1 a, T2 b, T3 x);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibeta_derivative(T1 a, T2 b, T3 x, const Policy&);
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.sf_beta.beta_derivative.description"></a><h5>
+<a name="id651256"></a>
+ Description
+ </h5>
+
+ This function finds some uses in statistical distributions: it computes
+ the partial derivative with respect to x of the incomplete
+ beta function ibeta.
+ 
+
+ <img src="../../../../equations/derivative2.png">
+ 
+
+ 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">result
+ type calculation rules</a> when T1, T2 and T3 are different
+ types.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<a name="math_toolkit.special.sf_beta.beta_derivative.accuracy"></a><h5>
+<a name="id651372"></a>
+ Accuracy
+ </h5>
+
+ Almost identical to the incomplete beta function ibeta.
+ 
+<a name="math_toolkit.special.sf_beta.beta_derivative.implementation"></a><h5>
+<a name="id651410"></a>
+ Implementation
+ </h5>
+
+ This function just expose some of the internals of the incomplete beta
+ function ibeta:
+ refer to the documentation for that function for more information.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/beta.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T1, class T2>
+calculated-result-type beta(T1 a, T2 b);
+
+template <class T1, class T2, class Policy>
+calculated-result-type beta(T1 a, T2 b, const Policy&);
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.sf_beta.beta_function.description"></a><h5>
+<a name="id637663"></a>
+ Description
+ </h5>
+
+ The beta function is defined by:
+ 
+
+ <img src="../../../../equations/beta1.png">
+ 
+
+ <img src="../../../../graphs/beta.png" alt="beta">
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ 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.
+ 
+
+ 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">result
+ type calculation rules</a> when T1 and T2 are different types.
+ 
+<a name="math_toolkit.special.sf_beta.beta_function.accuracy"></a><h5>
+<a name="id637825"></a>
+ Accuracy
+ </h5>
+
+ 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>.
+ 
+<div class="table">
+<a name="id637872"></a>Table 15. Peak Errors In the Beta Function
+<div class="table-contents"><table class="table" summary="Peak Errors In the Beta Function">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ Errors in range
+ 
+ 
+ 0.4 < a,b < 100
+ 
+ </th>
+<th>
+ 
+ Errors in range
+ 
+ 
+ 1e-6 < a,b < 36
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=99 Mean=22
+ 
+ 
+ (GSL Peak=1178 Mean=238)
+ 
+ 
+ (Cephes=1612)
+ 
+ </td>
+<td>
+ 
+ Peak=10.7 Mean=2.6
+ 
+ 
+ (GSL Peak=12 Mean=2.0)
+ 
+ 
+ (Cephes=174)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux IA32, g++ 3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=112.1 Mean=26.9
+ 
+ </td>
+<td>
+ 
+ Peak=15.8 Mean=3.6
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux IA64, g++ 3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=61.4 Mean=19.5
+ 
+ </td>
+<td>
+ 
+ Peak=12.2 Mean=3.6
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=42.03 Mean=13.94
+ 
+ </td>
+<td>
+ 
+ Peak=9.8 Mean=3.1
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ 
+ 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.
+ 
+<a name="math_toolkit.special.sf_beta.beta_function.testing"></a><h5>
+<a name="id638118"></a>
+ Testing
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.special.sf_beta.beta_function.implementation"></a><h5>
+<a name="id638156"></a>
+ Implementation
+ </h5>
+
+ 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:
+ 
+
+ <img src="../../../../equations/beta2.png">
+ 
+
+ which is almost the ideal solution, however almost all of the error occurs
+ in evaluating the power terms when a or b
+ are large. If we assume that a > b then the larger
+ of the two power terms can be reduced by a factor of b,
+ which immediately cuts the maximum error in half:
+ 
+
+ <img src="../../../../equations/beta3.png">
+ 
+
+ This may not be the final solution, but it is very competitive compared
+ to other implementation methods.
+ 
+
+ 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:
+ 
+
+ <img src="../../../../equations/beta8.png">
+ 
+
+ where la, lb and lc are the integration limits used for a, b, and a+b.
+ 
+
+ There are a few special cases worth mentioning:
+ 
+
+ When a or b are less than one,
+ we can use the recurrence relations:
+ 
+
+ <img src="../../../../equations/beta4.png">
+ 
+
+ <img src="../../../../equations/beta5.png">
+ 
+
+ to move to a more favorable region where they are both greater than 1.
+ 
+
+ In addition:
+ 
+
+ <img src="../../../../equations/beta7.png">
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/gamma.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T1, class T2, class T3>
+calculated-result-type ibeta(T1 a, T2 b, T3 x);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibeta(T1 a, T2 b, T3 x, const Policy&);
+
+template <class T1, class T2, class T3>
+calculated-result-type ibetac(T1 a, T2 b, T3 x);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibetac(T1 a, T2 b, T3 x, const Policy&);
+
+template <class T1, class T2, class T3>
+calculated-result-type beta(T1 a, T2 b, T3 x);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type beta(T1 a, T2 b, T3 x, const Policy&);
+
+template <class T1, class T2, class T3>
+calculated-result-type betac(T1 a, T2 b, T3 x);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type betac(T1 a, T2 b, T3 x, const Policy&);
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.sf_beta.ibeta_function.description"></a><h5>
+<a name="id639863"></a>
+ Description
+ </h5>
+
+ 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 regularized
+ 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).
+ 
+
+ All of these functions require a > 0, b
+ > 0 and 0 <= x <= 1.
+ 
+
+ 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">result
+ type calculation rules</a> when T1, T2 and T3 are different
+ types.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type ibeta(T1 a, T2 b, T3 x);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibeta(T1 a, T2 b, T3 x, const Policy&);
+</pre>
+
+ Returns the normalised incomplete beta function of a, b and x:
+ 
+
+ <img src="../../../../equations/ibeta3.png">
+ 
+
+ <img src="../../../../graphs/ibeta.png" alt="ibeta">
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type ibetac(T1 a, T2 b, T3 x);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibetac(T1 a, T2 b, T3 x, const Policy&);
+</pre>
+
+ Returns the normalised complement of the incomplete beta function of a,
+ b and x:
+ 
+
+ <img src="../../../../equations/ibeta4.png">
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type beta(T1 a, T2 b, T3 x);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type beta(T1 a, T2 b, T3 x, const Policy&);
+</pre>
+
+ Returns the full (non-normalised) incomplete beta function of a, b and
+ x:
+ 
+
+ <img src="../../../../equations/ibeta1.png">
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type betac(T1 a, T2 b, T3 x);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type betac(T1 a, T2 b, T3 x, const Policy&);
+</pre>
+
+ Returns the full (non-normalised) complement of the incomplete beta function
+ of a, b and x:
+ 
+
+ <img src="../../../../equations/ibeta2.png">
+ 
+<a name="math_toolkit.special.sf_beta.ibeta_function.accuracy"></a><h5>
+<a name="id641408"></a>
+ Accuracy
+ </h5>
+
+ 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>.
+ 
+
+ 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.
+ 
+<div class="table">
+<a name="id641465"></a>Table 16. Errors In the Function ibeta(a,b,x)
+<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>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ 0 < a,b < 10
+ 
+ 
+ and
+ 
+ 
+ 0 < x < 1
+ 
+ </th>
+<th>
+ 
+ 0 < a,b < 100
+ 
+ 
+ and
+ 
+ 
+ 0 < x < 1
+ 
+ </th>
+<th>
+ 
+ 1x10-5 < a,b < 1x105
+ 
+ 
+ and
+ 
+ 
+ 0 < x < 1
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=42.3 Mean=2.9
+ 
+ 
+ (GSL Peak=682 Mean=32.5)
+ 
+ 
+ (Cephes Peak=42.7
+ Mean=7.0)
+ 
+ </td>
+<td>
+ 
+ Peak=108 Mean=16.6
+ 
+ 
+ (GSL Peak=690 Mean=151)
+ 
+ 
+ (Cephes Peak=1545
+ Mean=218)
+ 
+ </td>
+<td>
+ 
+ Peak=4x103 Mean=203
+ 
+ 
+ (GSL Peak~3x105 Mean~2x104)
+ 
+ 
+ (Cephes Peak~5x105 Mean~2x104)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA32, gcc-3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=21.9 Mean=3.1
+ 
+ </td>
+<td>
+ 
+ Peak=270.7 Mean=26.8
+ 
+ </td>
+<td>
+ 
+ Peak~5x104 Mean=3x103
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA64, gcc-3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=15.4 Mean=3.0
+ 
+ </td>
+<td>
+ 
+ Peak=112.9 Mean=14.3
+ 
+ </td>
+<td>
+ 
+ Peak~5x104 Mean=3x103
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=20.9 Mean=2.6
+ 
+ </td>
+<td>
+ 
+ Peak=88.1 Mean=14.3
+ 
+ </td>
+<td>
+ 
+ Peak~2x104 Mean=1x103
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id641814"></a>Table 17. Errors In the Function ibetac(a,b,x)
+<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>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ 0 < a,b < 10
+ 
+ 
+ and
+ 
+ 
+ 0 < x < 1
+ 
+ </th>
+<th>
+ 
+ 0 < a,b < 100
+ 
+ 
+ and
+ 
+ 
+ 0 < x < 1
+ 
+ </th>
+<th>
+ 
+ 1x10-5 < a,b < 1x105
+ 
+ 
+ and
+ 
+ 
+ 0 < x < 1
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=13.9 Mean=2.0
+ 
+ </td>
+<td>
+ 
+ Peak=56.2 Mean=14
+ 
+ </td>
+<td>
+ 
+ Peak=3x103 Mean=159
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA32, gcc-3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=21.1 Mean=3.6
+ 
+ </td>
+<td>
+ 
+ Peak=221.7 Mean=25.8
+ 
+ </td>
+<td>
+ 
+ Peak~9x104 Mean=3x103
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA64, gcc-3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=10.6 Mean=2.2
+ 
+ </td>
+<td>
+ 
+ Peak=73.9 Mean=11.9
+ 
+ </td>
+<td>
+ 
+ Peak~9x104 Mean=3x103
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=9.9 Mean=2.6
+ 
+ </td>
+<td>
+ 
+ Peak=117.7 Mean=15.1
+ 
+ </td>
+<td>
+ 
+ Peak~3x104 Mean=1x103
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id642099"></a>Table 18. Errors In the Function beta(a, b, x)
+<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>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ 0 < a,b < 10
+ 
+ 
+ and
+ 
+ 
+ 0 < x < 1
+ 
+ </th>
+<th>
+ 
+ 0 < a,b < 100
+ 
+ 
+ and
+ 
+ 
+ 0 < x < 1
+ 
+ </th>
+<th>
+ 
+ 1x10-5 < a,b < 1x105
+ 
+ 
+ and
+ 
+ 
+ 0 < x < 1
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=39 Mean=2.9
+ 
+ </td>
+<td>
+ 
+ Peak=91 Mean=12.7
+ 
+ </td>
+<td>
+ 
+ Peak=635 Mean=25
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA32, gcc-3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=26 Mean=3.6
+ 
+ </td>
+<td>
+ 
+ Peak=180.7 Mean=30.1
+ 
+ </td>
+<td>
+ 
+ Peak~7x104 Mean=3x103
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA64, gcc-3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=13 Mean=2.4
+ 
+ </td>
+<td>
+ 
+ Peak=67.1 Mean=13.4
+ 
+ </td>
+<td>
+ 
+ Peak~7x104 Mean=3x103
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=27.3 Mean=3.6
+ 
+ </td>
+<td>
+ 
+ Peak=49.8 Mean=9.1
+ 
+ </td>
+<td>
+ 
+ Peak~6x104 Mean=3x103
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id642380"></a>Table 19. Errors In the Function betac(a,b,x)
+<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>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ 0 < a,b < 10
+ 
+ 
+ and
+ 
+ 
+ 0 < x < 1
+ 
+ </th>
+<th>
+ 
+ 0 < a,b < 100
+ 
+ 
+ and
+ 
+ 
+ 0 < x < 1
+ 
+ </th>
+<th>
+ 
+ 1x10-5 < a,b < 1x105
+ 
+ 
+ and
+ 
+ 
+ 0 < x < 1
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=12.0 Mean=2.4
+ 
+ </td>
+<td>
+ 
+ Peak=91 Mean=15
+ 
+ </td>
+<td>
+ 
+ Peak=4x103 Mean=113
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA32, gcc-3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=19.8 Mean=3.8
+ 
+ </td>
+<td>
+ 
+ Peak=295.1 Mean=33.9
+ 
+ </td>
+<td>
+ 
+ Peak~1x105 Mean=5x103
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA64, gcc-3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=11.2 Mean=2.4
+ 
+ </td>
+<td>
+ 
+ Peak=63.5 Mean=13.6
+ 
+ </td>
+<td>
+ 
+ Peak~1x105 Mean=5x103
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=15.6 Mean=3.5
+ 
+ </td>
+<td>
+ 
+ Peak=39.8 Mean=8.9
+ 
+ </td>
+<td>
+ 
+ Peak~9x104 Mean=5x103
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <a name="math_toolkit.special.sf_beta.ibeta_function.testing"></a><h5>
+<a name="id642673"></a>
+ Testing
+ </h5>
+
+ 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).
+ 
+
+ 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 not used in the implementation, and therefore we
+ have test data that is fully independent of the code.
+ 
+<a name="math_toolkit.special.sf_beta.ibeta_function.implementation"></a><h5>
+<a name="id642736"></a>
+ Implementation
+ </h5>
+
+ 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>
+ 
+
+ 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:
+ 
+
+ <img src="../../../../equations/ibeta_inv5.png">
+ 
+
+ 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.
+ 
+
+ 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:
+ 
+
+ <img src="../../../../equations/ibeta5.png">
+ 
+
+ 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:
+ 
+
+ <img src="../../../../equations/ibeta6.png">
+ 
+
+ For smallish b and x then a series representation can be used:
+ 
+
+ <img src="../../../../equations/ibeta7.png">
+ 
+
+ When b << 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:
+ 
+
+ <img src="../../../../equations/ibeta8.png">
+ 
+
+ 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 pn previously computed, which does limit the precision of the
+ method, depending upon the size of the table used.
+ 
+
+ When a and b are both small integers,
+ then we can relate the incomplete beta to the binomial distribution and
+ use the following finite sum:
+ 
+
+ <img src="../../../../equations/ibeta12.png">
+ 
+
+ Finally we can sidestep difficult areas, or move to an area with a more
+ efficient means of computation, by using the duplication formulae:
+ 
+
+ <img src="../../../../equations/ibeta10.png">
+ 
+
+ <img src="../../../../equations/ibeta11.png">
+ 
+
+ 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>.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/beta.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T1, class T2, class T3>
+calculated-result-type ibeta_inv(T1 a, T2 b, T3 p);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibeta_inv(T1 a, T2 b, T3 p, const Policy&);
+
+template <class T1, class T2, class T3, class T4>
+calculated-result-type ibeta_inv(T1 a, T2 b, T3 p, T4* py);
+
+template <class T1, class T2, class T3, class T4, class Policy>
+calculated-result-type ibeta_inv(T1 a, T2 b, T3 p, T4* py, const Policy&);
+
+template <class T1, class T2, class T3>
+calculated-result-type ibetac_inv(T1 a, T2 b, T3 q);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibetac_inv(T1 a, T2 b, T3 q, const Policy&);
+
+template <class T1, class T2, class T3, class T4>
+calculated-result-type ibetac_inv(T1 a, T2 b, T3 q, T4* py);
+
+template <class T1, class T2, class T3, class T4, class Policy>
+calculated-result-type ibetac_inv(T1 a, T2 b, T3 q, T4* py, const Policy&);
+
+template <class T1, class T2, class T3>
+calculated-result-type ibeta_inva(T1 b, T2 x, T3 p);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibeta_inva(T1 b, T2 x, T3 p, const Policy&);
+
+template <class T1, class T2, class T3>
+calculated-result-type ibetac_inva(T1 b, T2 x, T3 q);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibetac_inva(T1 b, T2 x, T3 q, const Policy&);
+
+template <class T1, class T2, class T3>
+calculated-result-type ibeta_invb(T1 a, T2 x, T3 p);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibeta_invb(T1 a, T2 x, T3 p, const Policy&);
+
+template <class T1, class T2, class T3>
+calculated-result-type ibetac_invb(T1 a, T2 x, T3 q);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibetac_invb(T1 a, T2 x, T3 q, const Policy&);
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.sf_beta.ibeta_inv_function.description"></a><h5>
+<a name="id645886"></a>
+ Description
+ </h5>
+
+ 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).
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<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">
+
+ When people normally talk about the inverse of the incomplete beta function,
+ they are talking about inverting on parameter x.
+ These are implemented here as ibeta_inv and ibeta_inv, and are by far
+ the most efficient of the inverses presented here.
+ 
+
+ The inverses on the a and b
+ 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.
+ 
+</td></tr>
+</table></div>
+
+ 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">result
+ type calculation rules</a> when called with arguments T1...TN
+ of different types.
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type ibeta_inv(T1 a, T2 b, T3 p);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibeta_inv(T1 a, T2 b, T3 p, const Policy&);
+
+template <class T1, class T2, class T3, class T4>
+calculated-result-type ibeta_inv(T1 a, T2 b, T3 p, T4* py);
+
+template <class T1, class T2, class T3, class T4, class Policy>
+calculated-result-type ibeta_inv(T1 a, T2 b, T3 p, T4* py, const Policy&);
+</pre>
+
+ Returns a value x such that: <code class="computeroutput">p
+ = ibeta(a,
+ b,
+ x);</code>
+ and sets <code class="computeroutput">*py
+ = 1 - x</code> when
+ the <code class="computeroutput">py</code> parameter is provided
+ and is non-null. Note that internally this function computes whichever
+ is the smaller of <code class="computeroutput">x</code> and
+ <code class="computeroutput">1-x</code>, and therefore the value assigned to
+ <code class="computeroutput">*py</code>
+ is free from cancellation errors. That means that even if the function
+ returns <code class="computeroutput">1</code>, the value stored
+ in <code class="computeroutput">*py</code>
+ may be non-zero, albeit very small.
+ 
+
+ Requires: a,b > 0 and 0 <= p <=
+ 1.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type ibetac_inv(T1 a, T2 b, T3 q);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibetac_inv(T1 a, T2 b, T3 q, const Policy&);
+
+template <class T1, class T2, class T3, class T4>
+calculated-result-type ibetac_inv(T1 a, T2 b, T3 q, T4* py);
+
+template <class T1, class T2, class T3, class T4, class Policy>
+calculated-result-type ibetac_inv(T1 a, T2 b, T3 q, T4* py, const Policy&);
+</pre>
+
+ Returns a value x such that: <code class="computeroutput">q
+ = ibetac(a,
+ b,
+ x);</code>
+ and sets <code class="computeroutput">*py
+ = 1 - x</code> when
+ the <code class="computeroutput">py</code> parameter is provided
+ and is non-null. Note that internally this function computes whichever
+ is the smaller of <code class="computeroutput">x</code> and
+ <code class="computeroutput">1-x</code>, and therefore the value assigned to
+ <code class="computeroutput">*py</code>
+ is free from cancellation errors. That means that even if the function
+ returns <code class="computeroutput">1</code>, the value stored
+ in <code class="computeroutput">*py</code>
+ may be non-zero, albeit very small.
+ 
+
+ Requires: a,b > 0 and 0 <= q <=
+ 1.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type ibeta_inva(T1 b, T2 x, T3 p);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibeta_inva(T1 b, T2 x, T3 p, const Policy&);
+</pre>
+
+ Returns a value a such that: <code class="computeroutput">p
+ = ibeta(a,
+ b,
+ x);</code>
+ 
+
+ Requires: b > 0, 0 < x < 1
+ and 0 <= p <= 1.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type ibetac_inva(T1 b, T2 x, T3 p);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibetac_inva(T1 b, T2 x, T3 p, const Policy&);
+</pre>
+
+ Returns a value a such that: <code class="computeroutput">q
+ = ibetac(a,
+ b,
+ x);</code>
+ 
+
+ Requires: b > 0, 0 < x < 1
+ and 0 <= q <= 1.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type ibeta_invb(T1 b, T2 x, T3 p);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibeta_invb(T1 b, T2 x, T3 p, const Policy&);
+</pre>
+
+ Returns a value b such that: <code class="computeroutput">p
+ = ibeta(a,
+ b,
+ x);</code>
+ 
+
+ Requires: a > 0, 0 < x < 1
+ and 0 <= p <= 1.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type ibetac_invb(T1 b, T2 x, T3 p);
+
+template <class T1, class T2, class T3, class Policy>
+calculated-result-type ibetac_invb(T1 b, T2 x, T3 p, const Policy&);
+</pre>
+
+ Returns a value b such that: <code class="computeroutput">q
+ = ibetac(a,
+ b,
+ x);</code>
+ 
+
+ Requires: a > 0, 0 < x < 1
+ and 0 <= q <= 1.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<a name="math_toolkit.special.sf_beta.ibeta_inv_function.accuracy"></a><h5>
+<a name="id649618"></a>
+ Accuracy
+ </h5>
+
+ 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 p (or it's complement
+ q) is very close to <code class="computeroutput">0</code>
+ or <code class="computeroutput">1</code>.
+ 
+<a name="math_toolkit.special.sf_beta.ibeta_inv_function.testing"></a><h5>
+<a name="id649684"></a>
+ Testing
+ </h5>
+
+ There are two sets of tests:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Basic sanity checks attempt to "round-trip" from a,
+ b and x to p or
+ q 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 p
+ or q 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>
+
+ These two functions share a common implementation.
+ 
+
+ 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 12 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 and b (which generally
+ form the more important use cases).
+ 
+
+ The initial guesses used for iteration are obtained as follows:
+ 
+
+ Firstly recall that:
+ 
+
+ <img src="../../../../equations/ibeta_inv5.png">
+ 
+
+ 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.
+ 
+
+ For <code class="computeroutput">a+b >= 5</code> the initial guess is computed using the
+ methods described in:
+ 
+
+ Asymptotic Inversion of the Incomplete Beta Function, by N. M. Temme.
+ Journal of Computational and Applied Mathematics 41 (1992) 145-157.
+ 
+
+ The nearly symmetrical case (section 2 of the paper) is used for
+ 
+
+ <img src="../../../../equations/ibeta_inv2.png">
+ 
+
+ 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 = 105</code>.
+ 
+
+ The general error function case (section 3 of the paper) is used for
+ 
+
+ <img src="../../../../equations/ibeta_inv3.png">
+ 
+
+ 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 =
+ 105</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
+ p1/a < 0.0025 then it is better to use the following as an initial estimate:
+ 
+
+ <img src="../../../../equations/ibeta_inv4.png">
+ 
+
+ Finally the for all other cases where <code class="computeroutput">a+b >
+ 5</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 = 105</code>. This method is limited
+ to a > 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">q1/p < 10-3</code>) we use:
+ 
+
+ <img src="../../../../equations/ibeta_inv6.png">
+ 
+
+ which is both cheaper to compute than the full method, and a more accurate
+ estimate on q.
+ 
+
+ 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.
+ 
+
+ 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">xs
+ = (1 - a) / (2 - a
+ - b)</code>. Therefore if <code class="literal">p > Ix(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">xs</code>,
+ and on a convex curve. An initial estimate for x is made with:
+ 
+
+ <img src="../../../../equations/ibeta_inv7.png">
+ 
+
+ 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.
+ 
+
+ 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">xs
+ = (1 - a) / (2 - a
+ - b)</code>. Therefore if <code class="literal">p > Ix(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">xs</code>,
+ and on a concave curve. An initial estimate for x is made with:
+ 
+
+ <img src="../../../../equations/ibeta_inv4.png">
+ 
+
+ which can be improved somewhat to:
+ 
+
+ <img src="../../../../equations/ibeta_inv1.png">
+ 
+
+ when b and x are both small (I've used b < a and x < 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.
+ 
+
+ 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 < 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
+ 
+
+ <img src="../../../../equations/ibeta_inv4.png">
+ 
+
+ 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.
+ 
+
+ Things can be improved by considering the incomplete beta as a distorted
+ quarter circle, and estimating y from:
+ 
+
+ <img src="../../../../equations/ibeta_inv8.png">
+ 
+
+ 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.
+ 
+<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>
+
+ These four functions share a common implementation.
+ 
+
+ First an initial approximation is computed for a or
+ b: where possible this uses a Cornish-Fisher expansion
+ for the negative binomial distribution to get within around 1 of the result.
+ However, when a or b are very
+ small the Cornish Fisher expansion is not usable, in this case the initial
+ approximation is chosen so that Ix(a, b) is near the middle of the range
+ [0,1].
+ 
+
+ 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 a or b
+ would improve these functions quite substantially: currently 10-20 incomplete
+ beta function invocations are required to find the root.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="sf_erf/error_function.html"> Error
+ Functions</a></dt>
+<dt><a href="sf_erf/error_inv.html"> Error Function
+ Inverses</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/erf.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+calculated-result-type erf(T z);
+
+template <class T, class Policy>
+calculated-result-type erf(T z, const Policy&);
+
+template <class T>
+calculated-result-type erfc(T z);
+
+template <class T, class Policy>
+calculated-result-type erfc(T z, const Policy&);
+
+}} // namespaces
+</pre>
+
+ 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">result
+ type calculation rules</a>: the return type is <code class="computeroutput">double</code> if T is an integer type, and T otherwise.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<a name="math_toolkit.special.sf_erf.error_function.description"></a><h5>
+<a name="id652036"></a>
+ Description
+ </h5>
+<pre class="programlisting">
+template <class T>
+calculated-result-type erf(T z);
+
+template <class T, class Policy>
+calculated-result-type erf(T z, const Policy&);
+</pre>
+
+ Returns the <a href="http://en.wikipedia.org/wiki/Error_function" target="_top">error
+ function</a> erf
+ of z:
+ 
+
+ <img src="../../../../equations/erf1.png">
+ 
+
+ <img src="../../../../graphs/erf1.png" alt="erf1">
+ 
+<pre class="programlisting">
+template <class T>
+calculated-result-type erfc(T z);
+
+template <class T, class Policy>
+calculated-result-type erfc(T z, const Policy&);
+</pre>
+
+ Returns the complement of the <a href="http://functions.wolfram.com/GammaBetaErf/Erfc/" target="_top">error
+ function</a> of z:
+ 
+
+ <img src="../../../../equations/erf2.png">
+ 
+
+ <img src="../../../../graphs/erf2.png" alt="erf2">
+ 
+<a name="math_toolkit.special.sf_erf.error_function.accuracy"></a><h5>
+<a name="id652546"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<div class="table">
+<a name="id652607"></a>Table 20. Errors In the Function erf(z)
+<div class="table-contents"><table class="table" summary="Errors In the Function erf(z)">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ z < 0.5
+ 
+ </th>
+<th>
+ 
+ 0.5 < z < 8
+ 
+ </th>
+<th>
+ 
+ z > 8
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=0 Mean=0
+ 
+ 
+ GSL Peak=2.0 Mean=0.3
+ 
+ 
+ Cephes Peak=1.1
+ Mean=0.7
+ 
+ </td>
+<td>
+ 
+ Peak=0.9 Mean=0.09
+ 
+ 
+ GSL Peak=2.3 Mean=0.3
+ 
+ 
+ Cephes Peak=1.3
+ Mean=0.2
+ 
+ </td>
+<td>
+ 
+ Peak=0 Mean=0
+ 
+ 
+ GSL Peak=0 Mean=0
+ 
+ 
+ Cephes Peak=0
+ Mean=0
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ RedHat Linux IA32, gcc-3.3
+ 
+ </td>
+<td>
+ 
+ Peak=0.7 Mean=0.07
+ 
+ 
+ GNU C Lib
+ Peak=0.9 Mean=0.2
+ 
+ </td>
+<td>
+ 
+ Peak=0.9 Mean=0.2
+ 
+ 
+ GNU C Lib
+ Peak=0.9 Mean=0.07
+ 
+ </td>
+<td>
+ 
+ Peak=0 Mean=0
+ 
+ 
+ GNU C Lib
+ Peak=0 Mean=0
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA64, gcc-3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=0.7 Mean=0.07
+ 
+ 
+ GNU C Lib
+ Peak=0 Mean=0
+ 
+ </td>
+<td>
+ 
+ Peak=0.9 Mean=0.1
+ 
+ 
+ GNU C Lib
+ Peak=0.5 Mean=0.03
+ 
+ </td>
+<td>
+ 
+ Peak=0 Mean=0
+ 
+ 
+ GNU C Lib
+ Peak=0 Mean=0
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=0.8 Mean=0.1
+ 
+ 
+ <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
+ 
+ </td>
+<td>
+ 
+ Peak=0.9 Mean=0.1
+ 
+ 
+ <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
+ 
+ </td>
+<td>
+ 
+ Peak=0 Mean=0
+ 
+ 
+ <a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX C
+ Library</a> Lib Peak=0 Mean=0
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id652980"></a>Table 21. Errors In the Function erfc(z)
+<div class="table-contents"><table class="table" summary="Errors In the Function erfc(z)">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ z < 0.5
+ 
+ </th>
+<th>
+ 
+ 0.5 < z < 8
+ 
+ </th>
+<th>
+ 
+ z > 8
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=0.7 Mean=0.06
+ 
+ 
+ GSL Peak=1.0 Mean=0.4
+ 
+ 
+ Cephes Peak=0.7
+ Mean=0.06
+ 
+ </td>
+<td>
+ 
+ Peak=0.99 Mean=0.3
+ 
+ 
+ GSL Peak=2.6 Mean=0.6
+ 
+ 
+ Cephes Peak=3.6
+ Mean=0.7
+ 
+ </td>
+<td>
+ 
+ Peak=1.0 Mean=0.2
+ 
+ 
+ GSL Peak=3.9 Mean=0.4
+ 
+ 
+ Cephes Peak=2.7
+ Mean=0.4
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ RedHat Linux IA32, gcc-3.3
+ 
+ </td>
+<td>
+ 
+ Peak=0 Mean=0
+ 
+ 
+ GNU C Lib
+ Peak=0 Mean=0
+ 
+ </td>
+<td>
+ 
+ Peak=1.4 Mean=0.3
+ 
+ 
+ GNU C Lib
+ Peak=1.3 Mean=0.3
+ 
+ </td>
+<td>
+ 
+ Peak=1.6 Mean=0.4
+ 
+ 
+ GNU C Lib
+ Peak=1.3 Mean=0.4
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA64, gcc-3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=0 Mean=0
+ 
+ 
+ GNU C Lib
+ Peak=0 Mean=0
+ 
+ </td>
+<td>
+ 
+ Peak=1.4 Mean=0.3
+ 
+ 
+ GNU C Lib
+ Peak=0 Mean=0
+ 
+ </td>
+<td>
+ 
+ Peak=1.5 Mean=0.4
+ 
+ 
+ GNU C Lib
+ Peak=0 Mean=0
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=0 Mean=0
+ 
+ 
+ <a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX C
+ Library</a> Peak=0 Mean=0
+ 
+ </td>
+<td>
+ 
+ Peak=1.5 Mean=0.3
+ 
+ 
+ <a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX C
+ Library</a> Peak=0.9 Mean=0.08
+ 
+ </td>
+<td>
+ 
+ Peak=1.6 Mean=0.4
+ 
+ 
+ <a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX C
+ Library</a> Peak=0.9 Mean=0.1
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <a name="math_toolkit.special.sf_erf.error_function.testing"></a><h5>
+<a name="id653363"></a>
+ Testing
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.special.sf_erf.error_function.implementation"></a><h5>
+<a name="id653416"></a>
+ Implementation
+ </h5>
+
+ All versions of these functions first use the usual reflection formulas
+ to make their arguments positive:
+ 
+<pre class="programlisting">
+erf(-z) = 1 - erf(z);
+
+erfc(-z) = 2 - erfc(z); // preferred when -z < -0.5
+
+erfc(-z) = 1 + erf(z); // preferred when -0.5 <= -z < 0
+</pre>
+
+ The generic versions of these functions are implemented in terms of the
+ incomplete gamma function.
+ 
+
+ 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.
+ 
+
+ For <code class="computeroutput">z <=
+ 0.5</code> then a rational approximation
+ to erf is used, based on the observation that:
+ 
+<pre class="programlisting">
+erf(z)/z ~ 1.12....
+</pre>
+
+ Therefore erf is calculated using:
+ 
+<pre class="programlisting">
+erf(z) = z * (1.125F + R(z));
+</pre>
+
+ 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.
+ 
+
+ For <code class="computeroutput">z >
+ 0.5</code> we observe that over a small
+ interval [a, b) then:
+ 
+<pre class="programlisting">
+erfc(z) * exp(z*z) * z ~ c
+</pre>
+
+ for some constant c.
+ 
+
+ Therefore for <code class="computeroutput">z >
+ 0.5</code> we calculate erfc using:
+ 
+<pre class="programlisting">
+erfc(z) = exp(-z*z) * (c + R(z)) / z;
+</pre>
+
+ Again R(z) is optimised for absolute error, and the constant <code class="computeroutput">c</code> is the average of <code class="computeroutput">erfc(z)
+ * exp(z*z) *
+ z</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">c</code> then <code class="computeroutput">c + R(z)</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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/erf.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+calculated-result-type erf_inv(T p);
+
+template <class T, class Policy>
+calculated-result-type erf_inv(T p, const Policy&);
+
+template <class T>
+calculated-result-type erfc_inv(T p);
+
+template <class T, class Policy>
+calculated-result-type erfc_inv(T p, const Policy&);
+
+}} // namespaces
+</pre>
+
+ 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">result
+ type calculation rules</a>: the return type is <code class="computeroutput">double</code> if T is an integer type, and T otherwise.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<a name="math_toolkit.special.sf_erf.error_inv.description"></a><h5>
+<a name="id654839"></a>
+ Description
+ </h5>
+<pre class="programlisting">
+template <class T>
+calculated-result-type erf_inv(T z);
+
+template <class T, class Policy>
+calculated-result-type erf_inv(T z, const Policy&);
+</pre>
+
+ 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:
+ 
+<pre class="programlisting">
+p = erf(x);
+</pre>
+
+ <img src="../../../../graphs/erf_inv.png" alt="erf_inv">
+ 
+<pre class="programlisting">
+template <class T>
+calculated-result-type erfc_inv(T z);
+
+template <class T, class Policy>
+calculated-result-type erfc_inv(T z, const Policy&);
+</pre>
+
+ Returns the inverse of the complement of the error function of z, that
+ is a value x such that:
+ 
+<pre class="programlisting">
+p = erfc(x);
+</pre>
+
+ <img src="../../../../graphs/erfc_inv.png" alt="erfc_inv">
+ 
+<a name="math_toolkit.special.sf_erf.error_inv.accuracy"></a><h5>
+<a name="id655359"></a>
+ Accuracy
+ </h5>
+
+ 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>.
+ 
+<a name="math_toolkit.special.sf_erf.error_inv.testing"></a><h5>
+<a name="id655400"></a>
+ Testing
+ </h5>
+
+ There are two sets of tests:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Basic sanity checks attempt to "round-trip" from x
+ to p 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 p
+ 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_erf.error_inv.implementation"></a><h5>
+<a name="id655462"></a>
+ Implementation
+ </h5>
+
+ 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-19, 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>.
+ 
+
+ 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-34 accuracy suitable for use with 128-bit reals.
+ 
+
+ In the following discussion, p is the value passed
+ to erf_inv, and q is the value passed to erfc_inv,
+ so that p = 1 - q and q = 1 - p
+ and in both cases we want to solve for the same result x.
+ 
+
+ For p < 0.5 the inverse erf function is reasonably
+ smooth and the approximation:
+ 
+<pre class="programlisting">
+x = p(p + 10)(Y + R(p))
+</pre>
+
+ Gives a good result for a constant Y, and R(p) optimised for low absolute
+ error compared to |Y|.
+ 
+
+ For q < 0.5 things get trickier, over the interval 0.5 >
+ q > 0.25 the following approximation works well:
+ 
+<pre class="programlisting">
+x = sqrt(-2log(q)) / (Y + R(q))
+</pre>
+
+ While for q < 0.25, let
+ 
+<pre class="programlisting">
+z = sqrt(-log(q))
+</pre>
+
+ Then the result is given by:
+ 
+<pre class="programlisting">
+x = z(Y + R(z - B))
+</pre>
+
+ 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 z 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">long
+ double</code> precision the extended exponent
+ range compared to <code class="computeroutput">double</code> means
+ that the tail goes on for a very long way indeed).
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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> Gamma</dt>
+<dt> Log Gamma</dt>
+<dt> Digamma</dt>
+<dt><a href="sf_gamma/gamma_ratios.html"> Ratios
+ of Gamma Functions</a></dt>
+<dt><a href="sf_gamma/igamma.html"> Incomplete Gamma
+ Functions</a></dt>
+<dt><a href="sf_gamma/igamma_inv.html"> Incomplete
+ Gamma Function Inverses</a></dt>
+<dt><a href="sf_gamma/gamma_derivatives.html"> Derivative
+ of the Incomplete Gamma Function</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/digamma.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+calculated-result-type digamma(T z);
+
+template <class T, class Policy>
+calculated-result-type digamma(T z, const Policy&);
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.sf_gamma.digamma.description"></a><h5>
+<a name="id622697"></a>
+ Description
+ </h5>
+
+ Returns the digamma or psi function of x. Digamma
+ is defined as the logarithmic derivative of the gamma function:
+ 
+
+ <img src="../../../../equations/digamma1.png">
+ 
+
+ <img src="../../../../graphs/digamma.png" alt="digamma">
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ 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.
+ 
+
+ 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">result
+ type calculation rules</a>: the result is of type <code class="computeroutput">double</code> when T is an integer type, and type
+ T otherwise.
+ 
+<a name="math_toolkit.special.sf_gamma.digamma.accuracy"></a><h5>
+<a name="id622843"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ Random Positive Values
+ 
+ </th>
+<th>
+ 
+ Values Near The Positive Root
+ 
+ </th>
+<th>
+ 
+ Values Near Zero
+ 
+ </th>
+<th>
+ 
+ Negative Values
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32 Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=0.98 Mean=0.36
+ 
+ </td>
+<td>
+ 
+ Peak=0.99 Mean=0.5
+ 
+ </td>
+<td>
+ 
+ Peak=0.95 Mean=0.5
+ 
+ </td>
+<td>
+ 
+ Peak=214 Mean=16
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Linux IA32 / GCC
+ 
+ </td>
+<td>
+ 
+ Peak=1.4 Mean=0.4
+ 
+ </td>
+<td>
+ 
+ Peak=1.3 Mean=0.45
+ 
+ </td>
+<td>
+ 
+ Peak=0.98 Mean=0.35
+ 
+ </td>
+<td>
+ 
+ Peak=180 Mean=13
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Linux IA64 / GCC
+ 
+ </td>
+<td>
+ 
+ Peak=0.92 Mean=0.4
+ 
+ </td>
+<td>
+ 
+ Peak=1.3 Mean=0.45
+ 
+ </td>
+<td>
+ 
+ Peak=0.98 Mean=0.4
+ 
+ </td>
+<td>
+ 
+ Peak=180 Mean=13
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=0.9 Mean=0.4
+ 
+ </td>
+<td>
+ 
+ Peak=1.1 Mean=0.5
+ 
+ </td>
+<td>
+ 
+ Peak=0.99 Mean=0.4
+ 
+ </td>
+<td>
+ 
+ Peak=64 Mean=6
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+
+ 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.
+ 
+<a name="math_toolkit.special.sf_gamma.digamma.testing"></a><h5>
+<a name="id623147"></a>
+ Testing
+ </h5>
+
+ 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).
+ 
+<a name="math_toolkit.special.sf_gamma.digamma.implementation"></a><h5>
+<a name="id623189"></a>
+ Implementation
+ </h5>
+
+ The implementation is divided up into the following domains:
+ 
+
+ For Negative arguments the reflection formula:
+ 
+<pre class="programlisting">
+digamma(1-x) = digamma(x) + pi/tan(pi*x);
+</pre>
+
+ is used to make x positive.
+ 
+
+ For arguments in the range [0,1] the recurrence relation:
+ 
+<pre class="programlisting">
+digamma(x) = digamma(x+1) - 1/x
+</pre>
+
+ is used to shift the evaluation to [1,2].
+ 
+
+ 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).
+ 
+
+ For arguments in the range [2,BIG] the recurrence relation:
+ 
+<pre class="programlisting">
+digamma(x+1) = digamma(x) + 1/x;
+</pre>
+
+ is used to shift the evaluation to the range [1,2].
+ 
+
+ For arguments > BIG the asymptotic expansion:
+ 
+
+ <img src="../../../../equations/digamma2.png">
+ 
+
+ can be used. However, this expansion is divergent after a few terms: exactly
+ how many terms depends on the size of x. Therefore
+ the value of BIG 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 BIG. 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">1/(x*x)</code>.
+ 
+
+ 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.
+ 
+
+ 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:
+ 
+
+ <img src="../../../../equations/digamma3.png">
+ 
+
+ 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">99-(1/y)</code>
+ digits if y 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).
+ 
+
+ Likewise a few spot tests agreed with values calculated using functions.wolfram.com
+ to >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.
+ 
+
+ 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:
+ 
+<pre class="programlisting">
+digamma(x) = (x - X0)(Y + R(x - 1));
+</pre>
+
+ 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 x 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) will not be zero.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/gamma.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T1, class T2>
+calculated-result-type gamma_p_derivative(T1 a, T2 x);
+
+template <class T1, class T2, class Policy>
+calculated-result-type gamma_p_derivative(T1 a, T2 x, const Policy&);
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.sf_gamma.gamma_derivatives.description"></a><h5>
+<a name="id633670"></a>
+ Description
+ </h5>
+
+ This function find some uses in statistical distributions: it implements
+ the partial derivative with respect to x of the incomplete
+ gamma function.
+ 
+
+ <img src="../../../../equations/derivative1.png">
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Note that the derivative of the function gamma_q
+ can be obtained by negating the result of this function.
+ 
+
+ 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">result
+ type calculation rules</a> when T1 and T2 are different types,
+ otherwise the return type is simply T1.
+ 
+<a name="math_toolkit.special.sf_gamma.gamma_derivatives.accuracy"></a><h5>
+<a name="id633795"></a>
+ Accuracy
+ </h5>
+
+ Almost identical to the incomplete gamma function gamma_p:
+ refer to the documentation for that function for more information.
+ 
+<a name="math_toolkit.special.sf_gamma.gamma_derivatives.implementation"></a><h5>
+<a name="id633836"></a>
+ Implementation
+ </h5>
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/gamma.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T1, class T2>
+calculated-result-type tgamma_ratio(T1 a, T2 b);
+
+template <class T1, class T2, class Policy>
+calculated-result-type tgamma_ratio(T1 a, T2 b, const Policy&);
+
+template <class T1, class T2>
+calculated-result-type tgamma_delta_ratio(T1 a, T2 delta);
+
+template <class T1, class T2, class Policy>
+calculated-result-type tgamma_delta_ratio(T1 a, T2 delta, const Policy&);
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.sf_gamma.gamma_ratios.description"></a><h5>
+<a name="id624568"></a>
+ Description
+ </h5>
+<pre class="programlisting">
+template <class T1, class T2>
+calculated-result-type tgamma_ratio(T1 a, T2 b);
+
+template <class T1, class T2, class Policy>
+calculated-result-type tgamma_ratio(T1 a, T2 b, const Policy&);
+</pre>
+
+ Returns the ratio of gamma functions:
+ 
+
+ <img src="../../../../equations/gamma_ratio0.png">
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Internally this just calls <code class="computeroutput">tgamma_delta_ratio(a,
+ b-a)</code>.
+ 
+<pre class="programlisting">
+template <class T1, class T2>
+calculated-result-type tgamma_delta_ratio(T1 a, T2 delta);
+
+template <class T1, class T2, class Policy>
+calculated-result-type tgamma_delta_ratio(T1 a, T2 delta, const Policy&);
+</pre>
+
+ Returns the ratio of gamma functions:
+ 
+
+ <img src="../../../../equations/gamma_ratio1.png">
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Note that the result is calculated accurately even when delta
+ is small compared to a: indeed even if a+delta
+ ~ a. The function is typically used when a
+ is large and delta is very small.
+ 
+
+ 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">result
+ type calculation rules</a> when T1 and T2 are different types,
+ otherwise the result type is simple T1.
+ 
+<a name="math_toolkit.special.sf_gamma.gamma_ratios.accuracy"></a><h5>
+<a name="id625306"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<div class="table">
+<a name="id625339"></a>Table 9. Errors In the Function tgamma_delta_ratio(a, delta)
+<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>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ 20 < a < 80
+ 
+ 
+ and
+ 
+ 
+ delta < 1
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=16.9 Mean=1.7
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA32, gcc-3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=24 Mean=2.7
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA64, gcc-3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=12.8 Mean=1.8
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=21.4 Mean=2.3
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id625500"></a>Table 10. Errors In the Function tgamma_ratio(a,
+ b)
+<div class="table-contents"><table class="table" summary="Errors In the Function tgamma_ratio(a,
+ b)">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ 6 < a,b < 50
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=34 Mean=9
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA32, gcc-3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=91 Mean=23
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA64, gcc-3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=35.6 Mean=9.3
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=43.9 Mean=13.2
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <a name="math_toolkit.special.sf_gamma.gamma_ratios.testing"></a><h5>
+<a name="id625662"></a>
+ Testing
+ </h5>
+
+ 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 Γ(x)/Γ(y).
+ 
+<a name="math_toolkit.special.sf_gamma.gamma_ratios.implementation"></a><h5>
+<a name="id625702"></a>
+ Implementation
+ </h5>
+
+ 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.
+ 
+
+ In addition there are optimisations for the situation where delta
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/gamma.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T1, class T2>
+calculated-result-type gamma_p(T1 a, T2 z);
+
+template <class T1, class T2, class Policy>
+calculated-result-type gamma_p(T1 a, T2 z, const Policy&);
+
+template <class T1, class T2>
+calculated-result-type gamma_q(T1 a, T2 z);
+
+template <class T1, class T2, class Policy>
+calculated-result-type gamma_q(T1 a, T2 z, const Policy&);
+
+template <class T1, class T2>
+calculated-result-type tgamma_lower(T1 a, T2 z);
+
+template <class T1, class T2, class Policy>
+calculated-result-type tgamma_lower(T1 a, T2 z, const Policy&);
+
+template <class T1, class T2>
+calculated-result-type tgamma(T1 a, T2 z);
+
+template <class T1, class T2, class Policy>
+calculated-result-type tgamma(T1 a, T2 z, const Policy&);
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.sf_gamma.igamma.description"></a><h5>
+<a name="id626884"></a>
+ Description
+ </h5>
+
+ There are four <a href="http://mathworld.wolfram.com/IncompleteGammaFunction.html" target="_top">incomplete
+ gamma functions</a>: two are normalised versions (also known as regularized
+ incomplete gamma functions) that return values in the range [0, 1], and
+ two are non-normalised and return values in the range [0, Γ(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>.
+ 
+
+ All of these functions require a > 0 and z
+ >= 0, otherwise they return the result of domain_error.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ 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">result
+ type calculation rules</a> when T1 and T2 are different types,
+ otherwise the return type is simply T1.
+ 
+<pre class="programlisting">
+template <class T1, class T2>
+calculated-result-type gamma_p(T1 a, T2 z);
+
+template <class T1, class T2, class Policy>
+calculated-result-type gamma_p(T1 a, T2 z, const Policy&);
+</pre>
+
+ Returns the normalised lower incomplete gamma function of a and z:
+ 
+
+ <img src="../../../../equations/igamma4.png">
+ 
+
+ This function changes rapidly from 0 to 1 around the point z == a:
+ 
+
+ <img src="../../../../graphs/gamma_p.png" alt="gamma_p">
+ 
+<pre class="programlisting">
+template <class T1, class T2>
+calculated-result-type gamma_q(T1 a, T2 z);
+
+template <class T1, class T2, class Policy>
+calculated-result-type gamma_q(T1 a, T2 z, const Policy&);
+</pre>
+
+ Returns the normalised upper incomplete gamma function of a and z:
+ 
+
+ <img src="../../../../equations/igamma3.png">
+ 
+
+ This function changes rapidly from 1 to 0 around the point z == a:
+ 
+
+ <img src="../../../../graphs/gamma_q.png" alt="gamma_q">
+ 
+<pre class="programlisting">
+template <class T1, class T2>
+calculated-result-type tgamma_lower(T1 a, T2 z);
+
+template <class T1, class T2, class Policy>
+calculated-result-type tgamma_lower(T1 a, T2 z, const Policy&);
+</pre>
+
+ Returns the full (non-normalised) lower incomplete gamma function of a
+ and z:
+ 
+
+ <img src="../../../../equations/igamma2.png">
+ 
+<pre class="programlisting">
+template <class T1, class T2>
+calculated-result-type tgamma(T1 a, T2 z);
+
+template <class T1, class T2, class Policy>
+calculated-result-type tgamma(T1 a, T2 z, const Policy&);
+</pre>
+
+ Returns the full (non-normalised) upper incomplete gamma function of a
+ and z:
+ 
+
+ <img src="../../../../equations/igamma1.png">
+ 
+<a name="math_toolkit.special.sf_gamma.igamma.accuracy"></a><h5>
+<a name="id628184"></a>
+ Accuracy
+ </h5>
+
+ 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>.
+ 
+
+ Note that errors grow as a grows larger.
+ 
+
+ 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.
+ 
+
+ All values are in units of epsilon.
+ 
+<div class="table">
+<a name="id628253"></a>Table 11. Errors In the Function gamma_p(a,z)
+<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>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ 0.5 < a < 100
+ 
+ 
+ and
+ 
+ 
+ 0.01*a < z < 100*a
+ 
+ </th>
+<th>
+ 
+ 1x10-12 < a < 5x10-2
+ 
+ 
+ and
+ 
+ 
+ 0.01*a < z < 100*a
+ 
+ </th>
+<th>
+ 
+ 1e-6 < a < 1.7x106
+ 
+ 
+ and
+ 
+ 
+ 1 < z < 100*a
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=36 Mean=9.1
+ 
+ 
+ (GSL Peak=342 Mean=46)
+ 
+ 
+ (Cephes Peak=491
+ Mean=102)
+ 
+ </td>
+<td>
+ 
+ Peak=4.5 Mean=1.4
+ 
+ 
+ (GSL Peak=4.8 Mean=0.76)
+ 
+ 
+ (Cephes Peak=21
+ Mean=5.6)
+ 
+ </td>
+<td>
+ 
+ Peak=244 Mean=21
+ 
+ 
+ (GSL Peak=1022 Mean=1054)
+ 
+ 
+ (Cephes Peak~8x106 Mean~7x104)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ RedHat Linux IA32, gcc-3.3
+ 
+ </td>
+<td>
+ 
+ Peak=241 Mean=36
+ 
+ </td>
+<td>
+ 
+ Peak=4.7 Mean=1.5
+ 
+ </td>
+<td>
+ 
+ Peak~30,220 Mean=1929
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA64, gcc-3.4
+ 
+ </td>
+<td>
+ 
+ Peak=41 Mean=10
+ 
+ </td>
+<td>
+ 
+ Peak=4.7 Mean=1.4
+ 
+ </td>
+<td>
+ 
+ Peak~30,790 Mean=1864
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=40.2 Mean=10.2
+ 
+ </td>
+<td>
+ 
+ Peak=5 Mean=1.6
+ 
+ </td>
+<td>
+ 
+ Peak=5,476 Mean=440
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id628572"></a>Table 12. Errors In the Function gamma_q(a,z)
+<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>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ 0.5 < a < 100
+ 
+ 
+ and
+ 
+ 
+ 0.01*a < z < 100*a
+ 
+ </th>
+<th>
+ 
+ 1x10-12 < a < 5x10-2
+ 
+ 
+ and
+ 
+ 
+ 0.01*a < z < 100*a
+ 
+ </th>
+<th>
+ 
+ 1x10-6 < a < 1.7x106
+ 
+ 
+ and
+ 
+ 
+ 1 < z < 100*a
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=28.3 Mean=7.2
+ 
+ 
+ (GSL Peak=201 Mean=13)
+ 
+ 
+ (Cephes Peak=556
+ Mean=97)
+ 
+ </td>
+<td>
+ 
+ Peak=4.8 Mean=1.6
+ 
+ 
+ (GSL Peak~1.3x1010 Mean=1x10+9)
+ 
+ 
+ (Cephes Peak~3x1011 Mean=4x1010)
+ 
+ </td>
+<td>
+ 
+ Peak=469 Mean=33
+ 
+ 
+ (GSL Peak=27,050 Mean=2159)
+ 
+ 
+ (Cephes Peak~8x106 Mean~7x105)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ RedHat Linux IA32, gcc-3.3
+ 
+ </td>
+<td>
+ 
+ Peak=280 Mean=33
+ 
+ </td>
+<td>
+ 
+ Peak=4.1 Mean=1.6
+ 
+ </td>
+<td>
+ 
+ Peak=11,490 Mean=732
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA64, gcc-3.4
+ 
+ </td>
+<td>
+ 
+ Peak=32 Mean=9.4
+ 
+ </td>
+<td>
+ 
+ Peak=4.7 Mean=1.5
+ 
+ </td>
+<td>
+ 
+ Peak=6815 Mean=414
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=37 Mean=10
+ 
+ </td>
+<td>
+ 
+ Peak=11.2 Mean=2.0
+ 
+ </td>
+<td>
+ 
+ Peak=4,999 Mean=298
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id628910"></a>Table 13. Errors In the Function tgamma_lower(a,z)
+<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>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ 0.5 < a < 100
+ 
+ 
+ and
+ 
+ 
+ 0.01*a < z < 100*a
+ 
+ </th>
+<th>
+ 
+ 1x10-12 < a < 5x10-2
+ 
+ 
+ and
+ 
+ 
+ 0.01*a < z < 100*a
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=5.5 Mean=1.4
+ 
+ </td>
+<td>
+ 
+ Peak=3.6 Mean=0.78
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ RedHat Linux IA32, gcc-3.3
+ 
+ </td>
+<td>
+ 
+ Peak=402 Mean=79
+ 
+ </td>
+<td>
+ 
+ Peak=3.4 Mean=0.8
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA64, gcc-3.4
+ 
+ </td>
+<td>
+ 
+ Peak=6.8 Mean=1.4
+ 
+ </td>
+<td>
+ 
+ Peak=3.4 Mean=0.78
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=6.1 Mean=1.8
+ 
+ </td>
+<td>
+ 
+ Peak=3.7 Mean=0.89
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id629123"></a>Table 14. Errors In the Function tgamma(a,z)
+<div class="table-contents"><table class="table" summary="Errors In the Function tgamma(a,z)">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ 0.5 < a < 100
+ 
+ 
+ and
+ 
+ 
+ 0.01*a < z < 100*a
+ 
+ </th>
+<th>
+ 
+ 1x10-12 < a < 5x10-2
+ 
+ 
+ and
+ 
+ 
+ 0.01*a < z < 100*a
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=5.9 Mean=1.5
+ 
+ </td>
+<td>
+ 
+ Peak=1.8 Mean=0.6
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ RedHat Linux IA32, gcc-3.3
+ 
+ </td>
+<td>
+ 
+ Peak=596 Mean=116
+ 
+ </td>
+<td>
+ 
+ Peak=3.2 Mean=0.84
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Redhat Linux IA64, gcc-3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=40.2 Mean=2.5
+ 
+ </td>
+<td>
+ 
+ Peak=3.2 Mean=0.8
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=364 Mean=17.6
+ 
+ </td>
+<td>
+ 
+ Peak=12.7 Mean=1.8
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <a name="math_toolkit.special.sf_gamma.igamma.testing"></a><h5>
+<a name="id629344"></a>
+ Testing
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.special.sf_gamma.igamma.implementation"></a><h5>
+<a name="id629402"></a>
+ Implementation
+ </h5>
+
+ These four functions share a common implementation since they are all related
+ via:
+ 
+
+ 1) <img src="../../../../equations/igamma5.png">
+ 
+
+ 2) <img src="../../../../equations/igamma6.png">
+ 
+
+ 3) <img src="../../../../equations/igamma7.png">
+ 
+
+ The lower incomplete gamma is computed from its series representation:
+ 
+
+ 4) <img src="../../../../equations/igamma8.png">
+ 
+
+ Or by subtraction of the upper integral from either Γ(a) or 1 when x
+ > a and x > 1.1.
+ 
+
+ The upper integral is computed from Legendre's continued fraction representation:
+ 
+
+ 5) <img src="../../../../equations/igamma9.png">
+ 
+
+ When x > 1.1 or by subtraction of the lower integral
+ from either Γ(a) or 1 when x < a.
+ 
+
+ For x < 1.1 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:
+ 
+
+ 6) <img src="../../../../equations/igamma10.png">
+ 
+
+ That lends itself to calculation of the upper integral via rearrangement
+ to:
+ 
+
+ 7) <img src="../../../../equations/igamma11.png">
+ 
+
+ 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.
+ 
+
+ For x < 1.1 the crossover point where the result
+ is ~0.5 no longer occurs for x ~ y. Using x
+ * 1.1 < a as the crossover criterion for 0.5 <
+ x <= 1.1 keeps the maximum value computed (whether it's the
+ upper or lower interval) to around 0.6. Likewise for x <=
+ 0.5 then using -0.4 / log(x) < a as
+ the crossover criterion keeps the maximum value computed to around 0.7
+ (whether it's the upper or lower interval).
+ 
+
+ 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 1 <=
+ a < 30 then the following finite sum is used:
+ 
+
+ 9) <img src="../../../../equations/igamma1f.png">
+ 
+
+ While for half integers in the range 0.5 <= a < 30
+ then the following finite sum is used:
+ 
+
+ 10) <img src="../../../../equations/igamma2f.png">
+ 
+
+ These are both more stable and more efficient than the continued fraction
+ alternative.
+ 
+
+ When the argument a is large, and x ~ a
+ then the series (4) and continued fraction (5) above are very slow to converge.
+ In this area an expansion due to Temme is used:
+ 
+
+ 11) <img src="../../../../equations/igamma16.png">
+ 
+
+ 12) <img src="../../../../equations/igamma17.png">
+ 
+
+ 13) <img src="../../../../equations/igamma18.png">
+ 
+
+ 14) <img src="../../../../equations/igamma19.png">
+ 
+
+ 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 Ckn are
+ computed in advance using the recurrence relations given by Temme. The
+ zone where these expansions are used is
+ 
+<pre class="programlisting">
+(a > 20) && (a < 200) && fabs(x-a)/a < 0.4
+</pre>
+
+ And:
+ 
+<pre class="programlisting">
+(a > 200) && (fabs(x-a)/a < 4.5/sqrt(a))
+</pre>
+
+ 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-6, 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">exp</code>
+ and <code class="computeroutput">erfc</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.
+ 
+
+ 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:
+ 
+
+ 15) <img src="../../../../equations/igamma12.png">
+ 
+
+ In the event that this causes underflowoverflow then the exponent
+ can be reduced by a factor of /a and brought inside the power
+ term.
+ 
+
+ 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:
+ 
+
+ 16) <img src="../../../../equations/igamma13.png">
+ 
+
+ when a-x 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 exp
+ 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 log(1+x)-x here is inspired
+ by Temme (see references below).
+ 
+<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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/gamma.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T1, class T2>
+calculated-result-type gamma_q_inv(T1 a, T2 q);
+
+template <class T1, class T2, class Policy>
+calculated-result-type gamma_q_inv(T1 a, T2 q, const Policy&);
+
+template <class T1, class T2>
+calculated-result-type gamma_p_inv(T1 a, T2 p);
+
+template <class T1, class T2, class Policy>
+calculated-result-type gamma_p_inv(T1 a, T2 p, const Policy&);
+
+template <class T1, class T2>
+calculated-result-type gamma_q_inva(T1 x, T2 q);
+
+template <class T1, class T2, class Policy>
+calculated-result-type gamma_q_inva(T1 x, T2 q, const Policy&);
+
+template <class T1, class T2>
+calculated-result-type gamma_p_inva(T1 x, T2 p);
+
+template <class T1, class T2, class Policy>
+calculated-result-type gamma_p_inva(T1 x, T2 p, const Policy&);
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.sf_gamma.igamma_inv.description"></a><h5>
+<a name="id631636"></a>
+ Description
+ </h5>
+
+ There are four <a href="http://mathworld.wolfram.com/IncompleteGammaFunction.html" target="_top">incomplete
+ gamma function</a> inverses which either compute x
+ given a and p or q,
+ or else compute a given x and
+ either p or q.
+ 
+
+ 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">result
+ type calculation rules</a> when T1 and T2 are different types,
+ otherwise the return type is simply T1.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<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">
+
+ When people normally talk about the inverse of the incomplete gamma function,
+ they are talking about inverting on parameter x.
+ These are implemented here as gamma_p_inv and gamma_q_inv, and are by
+ far the most efficient of the inverses presented here.
+ 
+
+ The inverse on the a 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.
+ 
+</td></tr>
+</table></div>
+<pre class="programlisting">
+template <class T1, class T2>
+calculated-result-type gamma_q_inv(T1 a, T2 q);
+
+template <class T1, class T2, class Policy>
+calculated-result-type gamma_q_inv(T1 a, T2 q, const Policy&);
+</pre>
+
+ Returns a value x such that: <code class="computeroutput">q
+ = gamma_q(a,
+ x);</code>
+ 
+
+ Requires: a > 0 and 1 >= p,q >=
+ 0.
+ 
+<pre class="programlisting">
+template <class T1, class T2>
+calculated-result-type gamma_p_inv(T1 a, T2 p);
+
+template <class T1, class T2, class Policy>
+calculated-result-type gamma_p_inv(T1 a, T2 p, const Policy&);
+</pre>
+
+ Returns a value x such that: <code class="computeroutput">p
+ = gamma_p(a,
+ x);</code>
+ 
+
+ Requires: a > 0 and 1 >= p,q >=
+ 0.
+ 
+<pre class="programlisting">
+template <class T1, class T2>
+calculated-result-type gamma_q_inva(T1 x, T2 q);
+
+template <class T1, class T2, class Policy>
+calculated-result-type gamma_q_inva(T1 x, T2 q, const Policy&);
+</pre>
+
+ Returns a value a such that: <code class="computeroutput">q
+ = gamma_q(a,
+ x);</code>
+ 
+
+ Requires: x > 0 and 1 >= p,q >=
+ 0.
+ 
+<pre class="programlisting">
+template <class T1, class T2>
+calculated-result-type gamma_p_inva(T1 x, T2 p);
+
+template <class T1, class T2, class Policy>
+calculated-result-type gamma_p_inva(T1 x, T2 p, const Policy&);
+</pre>
+
+ Returns a value a such that: <code class="computeroutput">p
+ = gamma_p(a,
+ x);</code>
+ 
+
+ Requires: x > 0 and 1 >= p,q >=
+ 0.
+ 
+<a name="math_toolkit.special.sf_gamma.igamma_inv.accuracy"></a><h5>
+<a name="id633033"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.special.sf_gamma.igamma_inv.testing"></a><h5>
+<a name="id633087"></a>
+ Testing
+ </h5>
+
+ There are two sets of tests:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Basic sanity checks attempt to "round-trip" from a
+ and x to p or q
+ 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 p or q
+ 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>
+
+ The functions gamma_p_inv and gamma_q_inv
+ share a common implementation.
+ 
+
+ First an initial approximation is computed using the methodology described
+ in:
+ 
+
+ <a href="http://portal.acm.org/citation.cfm?id=23109&coll=portal&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>
+ 
+
+ 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.
+ 
+
+ 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.
+ 
+
+ An initial approximation for a is computed very crudely
+ so that gamma_p(a, x) ~ 0.5, 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/gamma.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+calculated-result-type lgamma(T z);
+
+template <class T, class Policy>
+calculated-result-type lgamma(T z, const Policy&);
+
+template <class T>
+calculated-result-type lgamma(T z, int* sign);
+
+template <class T, class Policy>
+calculated-result-type lgamma(T z, int* sign, const Policy&);
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.sf_gamma.lgamma.description"></a><h5>
+<a name="id620556"></a>
+ Description
+ </h5>
+
+ The lgamma function
+ is defined by:
+ 
+
+ <img src="../../../../equations/lgamm1.png">
+ 
+
+ 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).
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ <img src="../../../../graphs/lgamma.png" alt="lgamma">
+ 
+
+ 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.
+ 
+
+ 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">result
+ type calculation rules</a>: the result is of type <code class="computeroutput">double</code> if T is an integer type, or type
+ T otherwise.
+ 
+<a name="math_toolkit.special.sf_gamma.lgamma.accuracy"></a><h5>
+<a name="id620744"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+
+ 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.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ Factorials and Half factorials
+ 
+ </th>
+<th>
+ 
+ Values Near Zero
+ 
+ </th>
+<th>
+ 
+ Values Near 1 or 2
+ 
+ </th>
+<th>
+ 
+ Values Near a Negative Pole
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32 Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=0.88 Mean=0.14
+ 
+ 
+ (GSL=33) (Cephes=1.5)
+ 
+ </td>
+<td>
+ 
+ Peak=0.96 Mean=0.46
+ 
+ 
+ (GSL=5.2) (Cephes=1.1)
+ 
+ </td>
+<td>
+ 
+ Peak=0.86 Mean=0.46
+ 
+ 
+ (GSL=1168) (Cephes~500000)
+ 
+ </td>
+<td>
+ 
+ Peak=4.2 Mean=1.3
+ 
+ 
+ (GSL=25) (Cephes=1.6)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Linux IA32 / GCC
+ 
+ </td>
+<td>
+ 
+ Peak=1.9 Mean=0.43
+ 
+ 
+ (GNU C Lib
+ Peak=1.7 Mean=0.49)
+ 
+ </td>
+<td>
+ 
+ Peak=1.4 Mean=0.57
+ 
+ 
+ (GNU C Lib
+ Peak= 0.96 Mean=0.54)
+ 
+ </td>
+<td>
+ 
+ Peak=0.86 Mean=0.35
+ 
+ 
+ (GNU C Lib
+ Peak=0.74 Mean=0.26)
+ 
+ </td>
+<td>
+ 
+ Peak=6.0 Mean=1.8
+ 
+ 
+ (GNU C Lib
+ Peak=3.0 Mean=0.86)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Linux IA64 / GCC
+ 
+ </td>
+<td>
+ 
+ Peak=0.99 Mean=0.12
+ 
+ 
+ (GNU C Lib
+ Peak 0)
+ 
+ </td>
+<td>
+ 
+ Pek=1.2 Mean=0.6
+ 
+ 
+ (GNU C Lib
+ Peak 0)
+ 
+ </td>
+<td>
+ 
+ Peak=0.86 Mean=0.16
+ 
+ 
+ (GNU C Lib
+ Peak 0)
+ 
+ </td>
+<td>
+ 
+ Peak=2.3 Mean=0.69
+ 
+ 
+ (GNU C Lib
+ Peak 0)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=0.96 Mean=0.13
+ 
+ 
+ (<a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX
+ C Library</a> Peak 0)
+ 
+ </td>
+<td>
+ 
+ Peak=0.99 Mean=0.53
+ 
+ 
+ (<a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX
+ C Library</a> Peak 0)
+ 
+ </td>
+<td>
+ 
+ Peak=0.9 Mean=0.4
+ 
+ 
+ (<a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX
+ C Library</a> Peak 0)
+ 
+ </td>
+<td>
+ 
+ Peak=3.0 Mean=0.9
+ 
+ 
+ (<a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX
+ C Library</a> Peak 0)
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.special.sf_gamma.lgamma.testing"></a><h5>
+<a name="id621267"></a>
+ Testing
+ </h5>
+
+ The main tests for this function involve comparisons against the logs of
+ the factorials which can be independently calculated to very high accuracy.
+ 
+
+ Random tests in key problem areas are also used.
+ 
+<a name="math_toolkit.special.sf_gamma.lgamma.implementation"></a><h5>
+<a name="id621303"></a>
+ Implementation
+ </h5>
+
+ The generic version of this function is implemented by combining the series
+ and continued fraction representations for the incomplete gamma function:
+ 
+
+ <img src="../../../../equations/lgamm2.png">
+ 
+
+ where l is an arbitrary integration limit: choosing
+ <code class="literal">l = max(10, a)</code> seems to work fairly well. For negative
+ z the logarithm version of the reflection formula
+ is used:
+ 
+
+ <img src="../../../../equations/lgamm3.png">
+ 
+
+ 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">boost::math::lanczos::lanczos_traits</code>
+ maps type T to an appropriate approximation. The logarithmic version of
+ the Lanczos approximation
+ is:
+ 
+
+ <img src="../../../../equations/lgamm4.png">
+ 
+
+ Where Le,g is the Lanczos sum, scaled by eg.
+ 
+
+ As before the reflection formula is used for z < 0.
+ 
+
+ 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).
+ 
+
+ 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:
+ 
+<pre class="programlisting">
+lgamma(z) = (z-2)(z+1)(Y + R(z-2));
+</pre>
+
+ 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:
+ 
+<pre class="programlisting">
+lgamma(z+1) = log(z) + lgamma(z);
+</pre>
+
+ Over the interval [1,2] two approximations have to be used, one for small
+ z uses:
+ 
+<pre class="programlisting">
+lgamma(z) = (z-1)(z-2)(Y + R(z-1));
+</pre>
+
+ Once again Y is a constant, and R(z-1) is optimised for low absolute error
+ compared to Y. For z > 1.5 the above form wouldn't converge to a minimax
+ solution but this similar form does:
+ 
+<pre class="programlisting">
+lgamma(z) = (2-z)(1-z)(Y + R(2-z));
+</pre>
+
+ Finally for z < 1 the recurrence relation can be used to move to z >
+ 1:
+ 
+<pre class="programlisting">
+lgamma(z) = lgamma(z+1) - log(z);
+</pre>
+
+ Note that while this involves a subtraction, it appears not to suffer from
+ cancellation error: as z decreases from 1 the <code class="computeroutput">-log(z)</code> term
+ grows positive much more rapidly than the <code class="computeroutput">lgamma(z+1)</code> term becomes
+ negative. So in this specific case, significant digits are preserved, rather
+ than cancelled.
+ 
+
+ 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 z
+ = 1, and then multiplying the Lanczos coefficients by the same
+ value. Now each term will take the value 1 at z = 1
+ 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 z = 1), we obtain a new summation
+ that can be also be fed into log1p. Crucially, all of the terms tend to
+ zero, as z -> 1:
+ 
+
+ <img src="../../../../equations/lgamm5.png">
+ 
+
+ The Ck terms in the above are the same as in the <a href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
+ approximation</a>.
+ 
+
+ A similar rearrangement can be performed at z = 2:
+ 
+
+ <img src="../../../../equations/lgamm6.png">
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/gamma.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+calculated-result-type tgamma(T z);
+
+template <class T, class Policy>
+calculated-result-type tgamma(T z, const Policy&);
+
+template <class T>
+calculated-result-type tgamma1pm1(T dz);
+
+template <class T, class Policy>
+calculated-result-type tgamma1pm1(T dz, const Policy&);
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.sf_gamma.tgamma.description"></a><h5>
+<a name="id618103"></a>
+ Description
+ </h5>
+<pre class="programlisting">
+template <class T>
+calculated-result-type tgamma(T z);
+
+template <class T, class Policy>
+calculated-result-type tgamma(T z, const Policy&);
+</pre>
+
+ Returns the "true gamma" (hence name tgamma) of value z:
+ 
+
+ <img src="../../../../equations/gamm1.png">
+ 
+
+ <img src="../../../../graphs/gamma.png" alt="gamma">
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ 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.
+ 
+
+ 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">result
+ type calculation rules</a>: the result is <code class="computeroutput">double</code>
+ when T is an integer type, and T otherwise.
+ 
+<pre class="programlisting">
+template <class T>
+calculated-result-type tgamma1pm1(T dz);
+
+template <class T, class Policy>
+calculated-result-type tgamma1pm1(T dz, const Policy&);
+</pre>
+
+ Returns <code class="computeroutput">tgamma(dz + 1) -
+ 1</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">dz</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.
+ 
+
+ 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">result
+ type calculation rules</a>: the result is <code class="computeroutput">double</code>
+ when T is an integer type, and T otherwise.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<a name="math_toolkit.special.sf_gamma.tgamma.accuracy"></a><h5>
+<a name="id618776"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ Factorials and Half factorials
+ 
+ </th>
+<th>
+ 
+ Values Near Zero
+ 
+ </th>
+<th>
+ 
+ Values Near 1 or 2
+ 
+ </th>
+<th>
+ 
+ Values Near a Negative Pole
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32 Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=1.9 Mean=0.7
+ 
+ 
+ (GSL=3.9)
+ 
+ 
+ (Cephes=3.0)
+ 
+ </td>
+<td>
+ 
+ Peak=2.0 Mean=1.1
+ 
+ 
+ (GSL=4.5)
+ 
+ 
+ (Cephes=1)
+ 
+ </td>
+<td>
+ 
+ Peak=2.0 Mean=1.1
+ 
+ 
+ (GSL=7.9)
+ 
+ 
+ (Cephes=1.0)
+ 
+ </td>
+<td>
+ 
+ Peak=2.6 Mean=1.3
+ 
+ 
+ (GSL=2.5)
+ 
+ 
+ (Cephes=2.7)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Linux IA32 / GCC
+ 
+ </td>
+<td>
+ 
+ Peak=300 Mean=49.5
+ 
+ 
+ (GNU C Lib
+ Peak=395 Mean=89)
+ 
+ </td>
+<td>
+ 
+ Peak=3.0 Mean=1.4
+ 
+ 
+ (GNU C Lib
+ Peak=11 Mean=3.3)
+ 
+ </td>
+<td>
+ 
+ Peak=5.0 Mean=1.8
+ 
+ 
+ (GNU C Lib
+ Peak=0.92 Mean=0.2)
+ 
+ </td>
+<td>
+ 
+ Peak=157 Mean=65
+ 
+ 
+ (GNU C Lib
+ Peak=205 Mean=108)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Linux IA64 / GCC
+ 
+ </td>
+<td>
+ 
+ GNU C Lib
+ Peak 2.8 Mean=0.9
+ 
+ 
+ (GNU C Lib
+ Peak 0.7)
+ 
+ </td>
+<td>
+ 
+ Peak=4.8 Mean=1.5
+ 
+ 
+ (GNU C Lib
+ Peak 0)
+ 
+ </td>
+<td>
+ 
+ Peak=4.8 Mean=1.5
+ 
+ 
+ (GNU C Lib
+ Peak 0)
+ 
+ </td>
+<td>
+ 
+ Peak=5.0 Mean=1.7 (<a href="http://www.gnu.org/software/libc/" target="_top">GNU
+ C Lib</a> Peak 0)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=2.5 Mean=1.1
+ 
+ 
+ (<a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX
+ C Library</a> Peak 0)
+ 
+ </td>
+<td>
+ 
+ Peak=3.5 Mean=1.7
+ 
+ 
+ (<a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX
+ C Library</a> Peak 0)
+ 
+ </td>
+<td>
+ 
+ Peak=3.5 Mean=1.6
+ 
+ 
+ (<a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX
+ C Library</a> Peak 0)
+ 
+ </td>
+<td>
+ 
+ Peak=5.2 Mean=1.92
+ 
+ 
+ (<a href="http://docs.hp.com/en/B9106-90010/index.html" target="_top">HP-UX
+ C Library</a> Peak 0)
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+<a name="math_toolkit.special.sf_gamma.tgamma.testing"></a><h5>
+<a name="id619314"></a>
+ Testing
+ </h5>
+
+ 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.
+ 
+
+ The function <code class="computeroutput">tgamma1pm1</code>
+ is tested against values calculated very naively using the formula <code class="computeroutput">tgamma(1+dz)-1</code> with
+ a lanczos approximation accurate to around 100 decimal digits.
+ 
+<a name="math_toolkit.special.sf_gamma.tgamma.implementation"></a><h5>
+<a name="id619406"></a>
+ Implementation
+ </h5>
+
+ The generic version of the <code class="computeroutput">tgamma</code>
+ function is implemented by combining the series and continued fraction
+ representations for the incomplete gamma function:
+ 
+
+ <img src="../../../../equations/gamm2.png">
+ 
+
+ where l is an arbitrary integration limit: choosing
+ <code class="literal">l = max(10, a)</code> seems to work fairly well.
+ 
+
+ 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">boost::math::lanczos::lanczos_traits</code>
+ maps type T to an appropriate approximation.
+ 
+
+ For z in the range -20 < z < 1 then recursion is used to shift to
+ z > 1 via:
+ 
+
+ <img src="../../../../equations/gamm3.png">
+ 
+
+ For very small z, this helps to preserve the identity:
+ 
+
+ <img src="../../../../equations/gamm4.png">
+ 
+
+ For z < -20 the reflection formula:
+ 
+
+ <img src="../../../../equations/gamm5.png">
+ 
+
+ is used. Particular care has to be taken to evaluate the <code class="computeroutput">z * sin([pi][space] * z)</code>
+ part: a special routine is used to reduce z prior to multiplying by π to
+ ensure that the result in is the range [0, π/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 exceptionally
+ high).
+ 
+
+ Finally if the argument is a small integer then table lookup of the factorial
+ is used.
+ 
+
+ The function <code class="computeroutput">tgamma1pm1</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">-0.5 < dz < 2</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">log(tgamma(dz+1))</code> which can fed into expm1
+ to give the desired result. Outside the range <code class="computeroutput">-0.5 < dz < 2</code> then the naive formula <code class="computeroutput">tgamma1pm1(dz)
+ = tgamma(dz+1)-1</code>
+ can be used directly.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="sf_poly/legendre.html"> Legendre (and
+ Associated) Polynomials</a></dt>
+<dt><a href="sf_poly/laguerre.html"> Laguerre (and
+ Associated) Polynomials</a></dt>
+<dt> Hermite Polynomials</dt>
+<dt> Spherical Harmonics</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/hermite.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+calculated-result-type hermite(unsigned n, T x);
+
+template <class T, class Policy>
+calculated-result-type hermite(unsigned n, T x, const Policy&);
+
+template <class T1, class T2, class T3>
+calculated-result-type hermite_next(unsigned n, T1 x, T2 Hn, T3 Hnm1);
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.sf_poly.hermite.description"></a><h5>
+<a name="id664226"></a>
+ Description
+ </h5>
+
+ 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">result
+ type calculation rules</a>: note than when there is a single
+ template argument the result is the same type as that argument or <code class="computeroutput">double</code> if the template argument is an integer
+ type.
+ 
+<pre class="programlisting">
+template <class T>
+calculated-result-type hermite(unsigned n, T x);
+
+template <class T, class Policy>
+calculated-result-type hermite(unsigned n, T x, const Policy&);
+</pre>
+
+ Returns the value of the Hermite Polynomial of order n
+ at point x:
+ 
+
+ <img src="../../../../equations/hermite_0.png">
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+
+ The following graph illustrates the behaviour of the first few Hermite
+ Polynomials:
+ 
+
+ <img src="../../../../graphs/hermite.png" alt="hermite">
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type hermite_next(unsigned n, T1 x, T2 Hn, T3 Hnm1);
+</pre>
+
+ 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 x, and for rising n.
+ 
+
+ <img src="../../../../equations/hermite_1.png">
+ 
+
+ For example we could produce a vector of the first 10 polynomial values
+ using:
+ 
+<pre class="programlisting">
+double x = 0.5; // Abscissa value
+vector<double> v;
+v.push_back(hermite(0, x)).push_back(hermite(1, x));
+for(unsigned l = 1; l < 10; ++l)
+ v.push_back(hermite_next(l, x, v[l], v[l-1]));
+</pre>
+
+ Formally the arguments are:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>n</dt>
+<dd>
+ The degree n of the last polynomial calculated.
+ </dd>
+<dt>x</dt>
+<dd>
+ The abscissa value
+ </dd>
+<dt>Hn</dt>
+<dd>
+ The value of the polynomial evaluated at degree n.
+ </dd>
+<dt>Hnm1</dt>
+<dd>
+ The value of the polynomial evaluated at degree n-1.
+ </dd>
+</dl>
+</div>
+<a name="math_toolkit.special.sf_poly.hermite.accuracy"></a><h5>
+<a name="id665228"></a>
+ Accuracy
+ </h5>
+
+ 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>.
+ 
+<div class="table">
+<a name="id665258"></a>Table 27. Peak Errors In the Hermite Polynomial
+<div class="table-contents"><table class="table" summary="Peak Errors In the Hermite Polynomial">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ Errors in range
+ 
+ 
+ 0 < l < 20
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=4.5 Mean=1.5
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux IA32, g++ 4.1
+ 
+ </td>
+<td>
+ 
+ Peak=6 Mean=2
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux IA64, g++ 3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=6 Mean=2
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=6 Mean=4
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ 
+ 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.
+ 
+<a name="math_toolkit.special.sf_poly.hermite.testing"></a><h5>
+<a name="id665441"></a>
+ Testing
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.special.sf_poly.hermite.implementation"></a><h5>
+<a name="id665480"></a>
+ Implementation
+ </h5>
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/laguerre.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+calculated-result-type laguerre(unsigned n, T x);
+
+template <class T, class Policy>
+calculated-result-type laguerre(unsigned n, T x, const Policy&);
+
+template <class T>
+calculated-result-type laguerre(unsigned n, unsigned m, T x);
+
+template <class T, class Policy>
+calculated-result-type laguerre(unsigned n, unsigned m, T x, const Policy&);
+
+template <class T1, class T2, class T3>
+calculated-result-type laguerre_next(unsigned n, T1 x, T2 Ln, T3 Lnm1);
+
+template <class T1, class T2, class T3>
+calculated-result-type laguerre_next(unsigned n, unsigned m, T1 x, T2 Ln, T3 Lnm1);
+
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.sf_poly.laguerre.description"></a><h5>
+<a name="id661220"></a>
+ Description
+ </h5>
+
+ 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">result
+ type calculation rules</a>: note than when there is a single
+ template argument the result is the same type as that argument or <code class="computeroutput">double</code> if the template argument is an integer
+ type.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<pre class="programlisting">
+template <class T>
+calculated-result-type laguerre(unsigned n, T x);
+
+template <class T, class Policy>
+calculated-result-type laguerre(unsigned n, T x, const Policy&);
+</pre>
+
+ Returns the value of the Laguerre Polynomial of order n
+ at point x:
+ 
+
+ <img src="../../../../equations/laguerre_0.png">
+ 
+
+ The following graph illustrates the behaviour of the first few Laguerre
+ Polynomials:
+ 
+
+ <img src="../../../../graphs/laguerre.png" alt="laguerre">
+ 
+<pre class="programlisting">
+template <class T>
+calculated-result-type laguerre(unsigned n, unsigned m, T x);
+
+template <class T, class Policy>
+calculated-result-type laguerre(unsigned n, unsigned m, T x, const Policy&);
+</pre>
+
+ Returns the Associated Laguerre polynomial of degree n
+ and order m at point x:
+ 
+
+ <img src="../../../../equations/laguerre_1.png">
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type laguerre_next(unsigned n, T1 x, T2 Ln, T3 Lnm1);
+</pre>
+
+ 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 x, and for rising n.
+ 
+
+ <img src="../../../../equations/laguerre_2.png">
+ 
+
+ For example we could produce a vector of the first 10 polynomial values
+ using:
+ 
+<pre class="programlisting">
+double x = 0.5; // Abscissa value
+vector<double> v;
+v.push_back(laguerre(0, x)).push_back(laguerre(1, x));
+for(unsigned l = 1; l < 10; ++l)
+ v.push_back(laguerre_next(l, x, v[l], v[l-1]));
+</pre>
+
+ Formally the arguments are:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>n</dt>
+<dd>
+ The degree n of the last polynomial calculated.
+ </dd>
+<dt>x</dt>
+<dd>
+ The abscissa value
+ </dd>
+<dt>Ln</dt>
+<dd>
+ The value of the polynomial evaluated at degree n.
+ </dd>
+<dt>Lnm1</dt>
+<dd>
+ The value of the polynomial evaluated at degree n-1.
+ </dd>
+</dl>
+</div>
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type laguerre_next(unsigned n, unsigned m, T1 x, T2 Ln, T3 Lnm1);
+</pre>
+
+ 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 x, and for rising degree n.
+ 
+
+ <img src="../../../../equations/laguerre_3.png">
+ 
+
+ For example we could produce a vector of the first 10 polynomial values
+ using:
+ 
+<pre class="programlisting">
+double x = 0.5; // Abscissa value
+int m = 10; // order
+vector<double> v;
+v.push_back(laguerre(0, m, x)).push_back(laguerre(1, m, x));
+for(unsigned l = 1; l < 10; ++l)
+ v.push_back(laguerre_next(l, m, x, v[l], v[l-1]));
+</pre>
+
+ Formally the arguments are:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>n</dt>
+<dd>
+ The degree of the last polynomial calculated.
+ </dd>
+<dt>m</dt>
+<dd>
+ The order of the Associated Polynomial.
+ </dd>
+<dt>x</dt>
+<dd>
+ The abscissa value.
+ </dd>
+<dt>Ln</dt>
+<dd>
+ The value of the polynomial evaluated at degree n.
+ </dd>
+<dt>Lnm1</dt>
+<dd>
+ The value of the polynomial evaluated at degree n-1.
+ </dd>
+</dl>
+</div>
+<a name="math_toolkit.special.sf_poly.laguerre.accuracy"></a><h5>
+<a name="id663251"></a>
+ Accuracy
+ </h5>
+
+ 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>.
+ 
+<div class="table">
+<a name="id663282"></a>Table 25. Peak Errors In the Laguerre Polynomial
+<div class="table-contents"><table class="table" summary="Peak Errors In the Laguerre Polynomial">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ Errors in range
+ 
+ 
+ 0 < l < 20
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=3000 Mean=185
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ SUSE Linux IA32, g++ 4.1
+ 
+ </td>
+<td>
+ 
+ Peak=1x104 Mean=828
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux IA64, g++ 3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=1x104 Mean=828
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=680 Mean=40
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id663447"></a>Table 26. Peak Errors In the Associated Laguerre
+ Polynomial
+<div class="table-contents"><table class="table" summary="Peak Errors In the Associated Laguerre
+ Polynomial">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ Errors in range
+ 
+ 
+ 0 < l < 20
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=433 Mean=11
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ SUSE Linux IA32, g++ 4.1
+ 
+ </td>
+<td>
+ 
+ Peak=61.4 Mean=19.5
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux IA64, g++ 3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=61.4 Mean=19.5
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=540 Mean=13.94
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ 
+ 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.
+ 
+<a name="math_toolkit.special.sf_poly.laguerre.testing"></a><h5>
+<a name="id663624"></a>
+ Testing
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.special.sf_poly.laguerre.implementation"></a><h5>
+<a name="id663663"></a>
+ Implementation
+ </h5>
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/legendre.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T>
+calculated-result-type legendre_p(int n, T x);
+
+template <class T, class Policy>
+calculated-result-type legendre_p(int n, T x, const Policy&);
+
+template <class T>
+calculated-result-type legendre_p(int n, int m, T x);
+
+template <class T, class Policy>
+calculated-result-type legendre_p(int n, int m, T x, const Policy&);
+
+template <class T>
+calculated-result-type legendre_q(unsigned n, T x);
+
+template <class T, class Policy>
+calculated-result-type legendre_q(unsigned n, T x, const Policy&);
+
+template <class T1, class T2, class T3>
+calculated-result-type legendre_next(unsigned l, T1 x, T2 Pl, T3 Plm1);
+
+template <class T1, class T2, class T3>
+calculated-result-type legendre_next(unsigned l, unsigned m, T1 x, T2 Pl, T3 Plm1);
+
+
+}} // namespaces
+</pre>
+
+ 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">result
+ type calculation rules</a>: note than when there is a single
+ template argument the result is the same type as that argument or <code class="computeroutput">double</code> if the template argument is an integer
+ type.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<a name="math_toolkit.special.sf_poly.legendre.description"></a><h5>
+<a name="id657167"></a>
+ Description
+ </h5>
+<pre class="programlisting">
+template <class T>
+calculated-result-type legendre_p(int l, T x);
+
+template <class T, class Policy>
+calculated-result-type legendre_p(int l, T x, const Policy&);
+</pre>
+
+ Returns the Legendre Polynomial of the first kind:
+ 
+
+ <img src="../../../../equations/legendre_0.png">
+ 
+
+ Requires -1 <= x <= 1, otherwise returns the result of domain_error.
+ 
+
+ Negative orders are handled via the reflection formula:
+ 
+
+ P-l-1(x) = Pl(x)
+ 
+
+ The following graph illustrates the behaviour of the first few Legendre
+ Polynomials:
+ 
+
+ <img src="../../../../graphs/legendre_p1.png" alt="legendre_p1">
+ 
+<pre class="programlisting">
+template <class T>
+calculated-result-type legendre_p(int l, int m, T x);
+
+template <class T, class Policy>
+calculated-result-type legendre_p(int l, int m, T x, const Policy&);
+</pre>
+
+ Returns the associated Legendre polynomial of the first kind:
+ 
+
+ <img src="../../../../equations/legendre_1.png">
+ 
+
+ Requires -1 <= x <= 1, otherwise returns the result of domain_error.
+ 
+
+ Negative values of l and m are
+ handled via the identity relations:
+ 
+
+ <img src="../../../../equations/legendre_3.png">
+ 
+<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">
+
+ The definition of the associated Legendre polynomial used here includes
+ a leading Condon-Shortley phase term of (-1)m. 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.
+ 
+
+ See:
+ 
+
+ <a href="http://mathworld.wolfram.com/LegendrePolynomial.html" target="_top">Weisstein,
+ Eric W. "Legendre Polynomial." From MathWorld--A Wolfram Web
+ Resource</a>.
+ 
+
+ 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.
+ 
+</td></tr>
+</table></div>
+<pre class="programlisting">
+template <class T>
+calculated-result-type legendre_q(unsigned n, T x);
+
+template <class T, class Policy>
+calculated-result-type legendre_q(unsigned n, T x, const Policy&);
+</pre>
+
+ Returns the value of the Legendre polynomial that is the second solution
+ to the Legendre differential equation, for example:
+ 
+
+ <img src="../../../../equations/legendre_2.png">
+ 
+
+ Requires -1 <= x <= 1, otherwise domain_error
+ is called.
+ 
+
+ The following graph illustrates the first few Legendre functions of the
+ second kind:
+ 
+
+ <img src="../../../../graphs/legendre_q.png" alt="legendre_q">
+ 
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type legendre_next(unsigned l, T1 x, T2 Pl, T3 Plm1);
+</pre>
+
+ 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 x, and for rising l. This
+ recurrence relation holds for Legendre Polynomials of both the first and
+ second kinds.
+ 
+
+ <img src="../../../../equations/legendre_4.png">
+ 
+
+ For example we could produce a vector of the first 10 polynomial values
+ using:
+ 
+<pre class="programlisting">
+double x = 0.5; // Abscissa value
+vector<double> v;
+v.push_back(legendre_p(0, x)).push_back(legendre_p(1, x));
+for(unsigned l = 1; l < 10; ++l)
+ v.push_back(legendre_next(l, x, v[l], v[l-1]));
+</pre>
+
+ Formally the arguments are:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>l</dt>
+<dd>
+ The degree of the last polynomial calculated.
+ </dd>
+<dt>x</dt>
+<dd>
+ The abscissa value
+ </dd>
+<dt>Pl</dt>
+<dd>
+ The value of the polynomial evaluated at degree l.
+ </dd>
+<dt>Plm1</dt>
+<dd>
+ The value of the polynomial evaluated at degree l-1.
+ </dd>
+</dl>
+</div>
+<pre class="programlisting">
+template <class T1, class T2, class T3>
+calculated-result-type legendre_next(unsigned l, unsigned m, T1 x, T2 Pl, T3 Plm1);
+</pre>
+
+ 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 x, and for rising l.
+ 
+
+ <img src="../../../../equations/legendre_5.png">
+ 
+
+ For example we could produce a vector of the first m+10 polynomial values
+ using:
+ 
+<pre class="programlisting">
+double x = 0.5; // Abscissa value
+int m = 10; // order
+vector<double> v;
+v.push_back(legendre_p(m, m, x)).push_back(legendre_p(1 + m, m, x));
+for(unsigned l = 1 + m; l < m + 10; ++l)
+ v.push_back(legendre_next(l, m, x, v[l], v[l-1]));
+</pre>
+
+ Formally the arguments are:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>l</dt>
+<dd>
+ The degree of the last polynomial calculated.
+ </dd>
+<dt>m</dt>
+<dd>
+ The order of the Associated Polynomial.
+ </dd>
+<dt>x</dt>
+<dd>
+ The abscissa value
+ </dd>
+<dt>Pl</dt>
+<dd>
+ The value of the polynomial evaluated at degree l.
+ </dd>
+<dt>Plm1</dt>
+<dd>
+ The value of the polynomial evaluated at degree l-1.
+ </dd>
+</dl>
+</div>
+<a name="math_toolkit.special.sf_poly.legendre.accuracy"></a><h5>
+<a name="id659594"></a>
+ Accuracy
+ </h5>
+
+ 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>.
+ 
+<div class="table">
+<a name="id659625"></a>Table 22. Peak Errors In the Legendre P Function
+<div class="table-contents"><table class="table" summary="Peak Errors In the Legendre P Function">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ Errors in range
+ 
+ 
+ 0 < l < 20
+ 
+ </th>
+<th>
+ 
+ Errors in range
+ 
+ 
+ 20 < l < 120
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=211 Mean=20
+ 
+ </td>
+<td>
+ 
+ Peak=300 Mean=33
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ SUSE Linux IA32, g++ 4.1
+ 
+ </td>
+<td>
+ 
+ Peak=70 Mean=10
+ 
+ </td>
+<td>
+ 
+ Peak=700 Mean=60
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux IA64, g++ 3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=70 Mean=10
+ 
+ </td>
+<td>
+ 
+ Peak=700 Mean=60
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=35 Mean=6
+ 
+ </td>
+<td>
+ 
+ Peak=292 Mean=41
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id659824"></a>Table 23. Peak Errors In the Associated Legendre
+ P Function
+<div class="table-contents"><table class="table" summary="Peak Errors In the Associated Legendre
+ P Function">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ Errors in range
+ 
+ 
+ 0 < l < 20
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=1200 Mean=7
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ SUSE Linux IA32, g++ 4.1
+ 
+ </td>
+<td>
+ 
+ Peak=80 Mean=5
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux IA64, g++ 3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=80 Mean=5
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=42 Mean=4
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <div class="table">
+<a name="id659981"></a>Table 24. Peak Errors In the Legendre Q Function
+<div class="table-contents"><table class="table" summary="Peak Errors In the Legendre Q Function">
+<colgroup>
+<col>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ Errors in range
+ 
+ 
+ 0 < l < 20
+ 
+ </th>
+<th>
+ 
+ Errors in range
+ 
+ 
+ 20 < l < 120
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=50 Mean=7
+ 
+ </td>
+<td>
+ 
+ Peak=4600 Mean=370
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ SUSE Linux IA32, g++ 4.1
+ 
+ </td>
+<td>
+ 
+ Peak=51 Mean=8
+ 
+ </td>
+<td>
+ 
+ Peak=6000 Mean=480
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux IA64, g++ 3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=51 Mean=8
+ 
+ </td>
+<td>
+ 
+ Peak=6000 Mean=480
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=90 Mean=10
+ 
+ </td>
+<td>
+ 
+ Peak=1700 Mean=140
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ 
+ 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.
+ 
+
+ 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.
+ 
+<a name="math_toolkit.special.sf_poly.legendre.testing"></a><h5>
+<a name="id660207"></a>
+ Testing
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.special.sf_poly.legendre.implementation"></a><h5>
+<a name="id660246"></a>
+ Implementation
+ </h5>
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/spheric_harmonic.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{
+
+template <class T1, class T2>
+std::complex<calculated-result-type> spherical_harmonic(unsigned n, int m, T1 theta, T2 phi);
+
+template <class T1, class T2, class Policy>
+std::complex<calculated-result-type> spherical_harmonic(unsigned n, int m, T1 theta, T2 phi, const Policy&);
+
+template <class T1, class T2>
+calculated-result-type spherical_harmonic_r(unsigned n, int m, T1 theta, T2 phi);
+
+template <class T1, class T2, class Policy>
+calculated-result-type spherical_harmonic_r(unsigned n, int m, T1 theta, T2 phi, const Policy&);
+
+template <class T1, class T2>
+calculated-result-type spherical_harmonic_i(unsigned n, int m, T1 theta, T2 phi);
+
+template <class T1, class T2, class Policy>
+calculated-result-type spherical_harmonic_i(unsigned n, int m, T1 theta, T2 phi, const Policy&);
+
+}} // namespaces
+</pre>
+<a name="math_toolkit.special.sf_poly.sph_harm.description"></a><h5>
+<a name="id666662"></a>
+ Description
+ </h5>
+
+ 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">result
+ type calculation rules</a> when T1 and T2 are different types.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+<pre class="programlisting">
+template <class T1, class T2>
+std::complex<calculated-result-type> spherical_harmonic(unsigned n, int m, T1 theta, T2 phi);
+
+template <class T1, class T2, class Policy>
+std::complex<calculated-result-type> spherical_harmonic(unsigned n, int m, T1 theta, T2 phi, const Policy&);
+</pre>
+
+ Returns the value of the Spherical Harmonic Ynm(theta, phi):
+ 
+
+ <img src="../../../../equations/spherical_0.png">
+ 
+
+ The spherical harmonics Ynm(theta, phi) are the angular portion of the
+ solution to Laplace's equation in spherical coordinates where azimuthal
+ symmetry is not present.
+ 
+<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">
+
+ Care must be taken in correctly identifying the arguments to this function:
+ θ is taken as the polar (colatitudinal) coordinate with θ in [0, π], and φ as
+ the azimuthal (longitudinal) coordinate with φ in [0,2π). 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.
+ 
+
+ Some other sources include an additional Condon-Shortley phase term of
+ (-1)m in the definition of this function: note however that our definition
+ of the associated Legendre polynomial already includes this term.
+ 
+
+ This implementation returns zero for m > n
+ 
+
+ For θ outside [0, π] and φ outside [0, 2π] this implementation follows the
+ convention used by Mathematica: the function is periodic with period
+ π in θ and 2π in φ. Please note that this is not the behaviour one would get
+ from a casual application of the function's definition. Cautious users
+ should keep θ and φ to the range [0, π] and [0, 2π] respectively.
+ 
+
+ See: <a href="http://mathworld.wolfram.com/SphericalHarmonic.html" target="_top">Weisstein,
+ Eric W. "Spherical Harmonic." From MathWorld--A Wolfram Web
+ Resource</a>.
+ 
+</td></tr>
+</table></div>
+<pre class="programlisting">
+template <class T1, class T2>
+calculated-result-type spherical_harmonic_r(unsigned n, int m, T1 theta, T2 phi);
+
+template <class T1, class T2, class Policy>
+calculated-result-type spherical_harmonic_r(unsigned n, int m, T1 theta, T2 phi, const Policy&);
+</pre>
+
+ Returns the real part of Ynm(theta, phi):
+ 
+
+ <img src="../../../../equations/spherical_1.png">
+ 
+<pre class="programlisting">
+template <class T1, class T2>
+calculated-result-type spherical_harmonic_i(unsigned n, int m, T1 theta, T2 phi);
+
+template <class T1, class T2, class Policy>
+calculated-result-type spherical_harmonic_i(unsigned n, int m, T1 theta, T2 phi, const Policy&);
+</pre>
+
+ Returns the imaginary part of Ynm(theta, phi):
+ 
+
+ <img src="../../../../equations/spherical_2.png">
+ 
+<a name="math_toolkit.special.sf_poly.sph_harm.accuracy"></a><h5>
+<a name="id667938"></a>
+ Accuracy
+ </h5>
+
+ 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.
+ 
+
+ All values are in units of epsilon.
+ 
+<div class="table">
+<a name="id667977"></a>Table 28. Peak Errors In the Sperical Harmonic Functions
+<div class="table-contents"><table class="table" summary="Peak Errors In the Sperical Harmonic Functions">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Significand Size
+ 
+ </th>
+<th>
+ 
+ Platform and Compiler
+ 
+ </th>
+<th>
+ 
+ Errors in range
+ 
+ 
+ 0 < l < 20
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ 53
+ 
+ </td>
+<td>
+ 
+ Win32, Visual C++ 8
+ 
+ </td>
+<td>
+ 
+ Peak=2x104 Mean=700
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ SUSE Linux IA32, g++ 4.1
+ 
+ </td>
+<td>
+ 
+ Peak=2900 Mean=100
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 64
+ 
+ </td>
+<td>
+ 
+ Red Hat Linux IA64, g++ 3.4.4
+ 
+ </td>
+<td>
+ 
+ Peak=2900 Mean=100
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ 113
+ 
+ </td>
+<td>
+ 
+ HPUX IA64, aCC A.06.06
+ 
+ </td>
+<td>
+ 
+ Peak=6700 Mean=230
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ 
+ 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.
+ 
+<a name="math_toolkit.special.sf_poly.sph_harm.testing"></a><h5>
+<a name="id668157"></a>
+ Testing
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.special.sf_poly.sph_harm.implementation"></a><h5>
+<a name="id668196"></a>
+ Implementation
+ </h5>
+
+ 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 1-x2 term
+ used by the associated Legendre functions is calculated without roundoff
+ error using x = cos(theta), and 1-x2 = sin2(theta)).
+ The limiting factor in the error rates for these functions is the need
+ to calculate values near the roots of the associated Legendre functions.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="sinc/sinc_overview.html"> Sinus Cardinal
+ and Hyperbolic Sinus Cardinal Functions Overview</a></dt>
+<dt>sinc_pi</dt>
+<dt>sinhc_pi</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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
+ > 0</code>) is defined by <img src="../../../../equations/special_functions_blurb20.png">;
+ it sees heavy use in signal processing tasks.
+ 
+
+ 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 > 0</code>) is defined by <img src="../../../../equations/special_functions_blurb22.png">.
+ 
+
+ These two families of functions are composed of entire functions.
+ 
+
+ 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.
+ 
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ Sinus Cardinal of index pi (purple)
+ and Hyperbolic Sinus Cardinal of index pi (red) on R
+ 
+
+ 
+</blockquote></div>
+<div class="blockquote"><blockquote class="blockquote">
+
+ 
+
+ <img src="../../../../graphs/sinc_pi_and_sinhc_pi_on_r.png" alt="sinc_pi_and_sinhc_pi_on_r">
+ 
+
+ 
+</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/sinc.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+template<class T>
+calculated-result-type sinc_pi(const T x);
+
+template<class T, class Policy>
+calculated-result-type sinc_pi(const T x, const Policy&);
+
+template<class T, template<typename> class U>
+U<T> sinc_pi(const U<T> x);
+
+template<class T, template<typename> class U, class Policy>
+U<T> sinc_pi(const U<T> x, const Policy&);
+</pre>
+
+ Computes <a href="sinc_overview.html" title="Sinus Cardinal and Hyperbolic Sinus Cardinal Functions Overview">the Sinus
+ Cardinal</a> of x:
+ 
+<pre class="programlisting">
+sinc_pi(x) = sin(x) / x
+</pre>
+
+ The second form is for complex numbers, quaternions, octonions etc. Taylor
+ series are used at the origin to ensure accuracy.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/special_functions/sinhc.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+template<class T>
+calculated-result-type sinhc_pi(const T x);
+
+template<class T, class Policy>
+calculated-result-type sinhc_pi(const T x, const Policy&);
+
+template<typename T, template<typename> class U>
+U<T> sinhc_pi(const U<T> x);
+
+template<class T, template<typename> class U, class Policy>
+U<T> sinhc_pi(const U<T> x, const Policy&);
+</pre>
+
+ 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:
+ 
+<pre class="programlisting">
+sinhc_pi(x) = sinh(x) / x
+</pre>
+
+ The second form is for complex numbers, quaternions, octonions etc. Taylor
+ series are used at the origin to ensure accuracy.
+ 
+
+ 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">result
+ type calculation rules</a> when T is an integer type.
+ 
+
+ 
+
+ 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.
+ 
+
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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> History and What's New</dt>
+<dt> Compilers</dt>
+<dt> Known Issues, and Todo List</dt>
+<dt> Credits and Acknowledgements</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ The code has been compiled and tested with:
+ 
+<div class="table">
+<a name="id791316"></a>Table 45. Compiler Notes
+<div class="table-contents"><table class="table" summary="Compiler Notes">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Compiler
+ 
+ </th>
+<th>
+ 
+ Platform
+ 
+ </th>
+<th>
+ 
+ Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Intel 9.1, 8.1
+ 
+ </td>
+<td>
+ 
+ Win32 and Linux
+ 
+ </td>
+<td>
+ 
+ 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.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ g++
+ 
+ </td>
+<td>
+ 
+ Linux and HP-UX
+ 
+ </td>
+<td>
+ 
+ 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.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ HP aCC
+ 
+ </td>
+<td>
+ 
+ HP-UX
+ 
+ </td>
+<td>
+ 
+ Unfortunately this emits quite a few warnings from libraries upon which
+ we depend (TR1, Array etc).
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Borland 5.8.2
+ 
+ </td>
+<td>
+ 
+ Windows
+ 
+ </td>
+<td>
+ 
+ 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, we
+ cannot recommend using this library with this compiler,
+ as the correct operation of the code cannot be guaranteed.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ MSVC 8.0
+ 
+ </td>
+<td>
+ 
+ Windows
+ 
+ </td>
+<td>
+ 
+ Warning free at level 4
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ Hubert Holin started the Boost.Math library. The inverse hyperbolic functions,
+ and the sinus cardinal functions are his.
+ 
+
+ 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.
+ 
+
+ 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).
+ 
+
+ Xiaogang Zhang worked on the Bessel functions and elliptic integrals for
+ his Google Summer of Code project 2006.
+ 
+
+ Professor Nico Temme for advice on the inverse incomplete beta function.
+ 
+
+ 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.
+ 
+
+ 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.
+ 
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ <a name="math_toolkit.status.history1.milestone_5__post_review_first_official_release"></a>
+ 
+<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>
+
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Added Policy based framework that allows fine grained control over function
+ behaviour.
+ </li>
+<li>
+Breaking change: 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>
+Breaking change: Changed exception thrown
+ when an internal evaluation error occurs to boost::math::evaluation_error.
+ </li>
+<li>
+Breaking change: 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>
+
+ <a name="math_toolkit.status.history1.milestone_4__second_review_candidate__1st_march_2007_"></a>
+ 
+<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>
+
+ 
+<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>
+
+ <a name="math_toolkit.status.history1.milestone_3__first_review_candidate__31st_dec_2006_"></a>
+ 
+<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>
+
+ 
+<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>
+
+ <a name="math_toolkit.status.history1.milestone_2__released_september_10th_2006"></a>
+ 
+<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>
+
+ 
+<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>
+
+ <a name="math_toolkit.status.history1.milestone_1__released_march_31st_2006"></a>
+ 
+<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>
+
+ 
+<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>
+
+ 
+
+ SVN Revisions:
+ 
+
+ 
+
+ Sandbox revision merged to trunk: 39833. Trunk revision: 39833.
+ 
+
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ This section lists those issues that are known about.
+ 
+
+ 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.
+ 
+
+ If you don't see a component listed here, then we don't have any known issues
+ with it.
+ 
+<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>
+Carlson's algorithms (mainly RJ) are somewhat prone to internal overflow/underflow
+ when the arguments are very large or small. The homogeneity relations:
+RF(ka,
+ kb, kc) = k-1/2 RF(a, b, c)
+and
+RJ(ka, kb, kc, kr) = k-3/2 RJ(a, b, c, r)
+could
+ be used to sidestep trouble here: provided the problem domains can be accurately
+ identified. (Medium Priority).
+</li>
+<li>
+ Carlson's RC 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 RG? 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(φ, k), Z(β, k), Λ0(β, k) and Bulirsch's
+ el 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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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> Overview</dt>
+<dt> Reused Utilities</dt>
+<dd><dl>
+<dt><a href="toolkit/internals1/series_evaluation.html">
+ Series Evaluation</a></dt>
+<dt><a href="toolkit/internals1/cf.html"> Continued Fraction
+ Evaluation</a></dt>
+<dt><a href="toolkit/internals1/rational.html"> Polynomial
+ and Rational Function Evaluation</a></dt>
+<dt><a href="toolkit/internals1/roots.html"> Root Finding
+ With Derivatives</a></dt>
+<dt><a href="toolkit/internals1/roots2.html"> Root Finding
+ Without Derivatives</a></dt>
+<dt><a href="toolkit/internals1/minima.html"> Locating Function
+ Minima</a></dt>
+</dl></dd>
+<dt> Testing and Development</dt>
+<dd><dl>
+<dt> Polynomials</dt>
+<dt><a href="toolkit/internals2/minimax.html"> Minimax Approximations
+ and the Remez Algorithm</a></dt>
+<dt><a href="toolkit/internals2/error_test.html"> Relative
+ Error and Testing</a></dt>
+<dt><a href="toolkit/internals2/test_data.html"> Graphing,
+ Profiling, and Generating Test Data for Special Functions</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="internals1/series_evaluation.html">
+ Series Evaluation</a></dt>
+<dt><a href="internals1/cf.html"> Continued Fraction
+ Evaluation</a></dt>
+<dt><a href="internals1/rational.html"> Polynomial
+ and Rational Function Evaluation</a></dt>
+<dt><a href="internals1/roots.html"> Root Finding
+ With Derivatives</a></dt>
+<dt><a href="internals1/roots2.html"> Root Finding
+ Without Derivatives</a></dt>
+<dt><a href="internals1/minima.html"> Locating Function
+ Minima</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/tools/fraction.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{ namespace tools{
+
+template <class Gen>
+typename detail::fraction_traits<Gen>::result_type
+ continued_fraction_b(Gen& g, int bits);
+
+template <class Gen>
+typename detail::fraction_traits<Gen>::result_type
+ continued_fraction_b(Gen& g, int bits, boost::uintmax_t& max_terms);
+
+template <class Gen>
+typename detail::fraction_traits<Gen>::result_type
+ continued_fraction_a(Gen& g, int bits);
+
+template <class Gen>
+typename detail::fraction_traits<Gen>::result_type
+ continued_fraction_a(Gen& g, int bits, boost::uintmax_t& max_terms);
+
+}}} // namespaces
+</pre>
+<a name="math_toolkit.toolkit.internals1.cf.description"></a><h5>
+<a name="id700540"></a>
+ Description
+ </h5>
+
+ <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 generator
+ type argument. The functions with an "_a" suffix evaluate the
+ fraction:
+ 
+
+ <img src="../../../../equations/fraction2.png">
+ 
+
+ and those with a "_b" suffix evaluate the fraction:
+ 
+
+ <img src="../../../../equations/fraction1.png">
+ 
+
+ This latter form is somewhat more natural in that it corresponds with the
+ usual definition of a continued fraction, but note that the first a
+ value returned by the generator is discarded. Further, often the first
+ a and b values in a continued
+ fraction have different defining equations to the remaining terms, which
+ may make the "_a" suffixed form more appropriate.
+ 
+
+ The generator type should be a function object which supports the following
+ operations:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Expression
+ 
+ </th>
+<th>
+ 
+ Description
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Gen::result_type
+ 
+ </td>
+<td>
+ 
+ The type that is the result of invoking operator(). This can be
+ either an arithmetic type, or a std::pair<> of arithmetic
+ types.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ g()
+ 
+ </td>
+<td>
+ 
+ Returns an object of type Gen::result_type.
+ 
+ 
+ Each time this operator is called then the next pair of a
+ and b values is returned. Or, if result_type
+ is an arithmetic type, then the next b value
+ is returned and all the a values are assumed
+ to 1.
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+
+ In all the continued fraction evaluation functions the bits
+ 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 bits bits in the result unchanged.
+ 
+
+ If the optional max_terms parameter is specified then
+ no more than max_terms calls to the generator will
+ be made, and on output, max_terms will be set to actual
+ number of calls made. This facility is particularly useful when profiling
+ a continued fraction for convergence.
+ 
+<a name="math_toolkit.toolkit.internals1.cf.implementation"></a><h5>
+<a name="id700818"></a>
+ Implementation
+ </h5>
+
+ 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.
+ 
+<a name="math_toolkit.toolkit.internals1.cf.examples"></a><h5>
+<a name="id700852"></a>
+ Examples
+ </h5>
+
+ 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:
+ 
+
+ <img src="../../../../equations/fraction3.png">
+ 
+
+ We begin by defining a generator function:
+ 
+<pre class="programlisting">
+template <class T>
+struct golden_ratio_fraction
+{
+ typedef T result_type;
+
+ result_type operator()
+ {
+ return 1;
+ }
+};
+</pre>
+
+ The golden ratio can then be computed to double precision using:
+ 
+<pre class="programlisting">
+continued_fraction_a(
+ golden_ratio_fraction<double>(),
+ std::numeric_limits<double>::digits);
+</pre>
+
+ It's more usual though to have to define both the a's
+ and the b's when evaluating special functions by continued
+ fractions, for example the tan function is defined by:
+ 
+
+ <img src="../../../../equations/fraction4.png">
+ 
+
+ So it's generator object would look like:
+ 
+<pre class="programlisting">
+template <class T>
+struct tan_fraction
+{
+private:
+ T a, b;
+public:
+ tan_fraction(T v)
+ : a(-v*v), b(-1)
+ {}
+
+ typedef std::pair<T,T> result_type;
+
+ std::pair<T,T> operator()()
+ {
+ b += 2;
+ return std::make_pair(a, b);
+ }
+};
+</pre>
+
+ Notice that if the continuant is subtracted from the b
+ terms, as is the case here, then all the a terms returned
+ by the generator will be negative. The tangent function can now be evaluated
+ using:
+ 
+<pre class="programlisting">
+template <class T>
+T tan(T a)
+{
+ tan_fraction<T> fract(a);
+ return a / continued_fraction_b(fract, std::numeric_limits<T>::digits);
+}
+</pre>
+
+ Notice that this time we're using the "_b" suffixed version to
+ evaluate the fraction: we're removing the leading a
+ term during fraction evaluation as it's different from all the others.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/tools/minima.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+template <class F, class T>
+std::pair<T, T> brent_find_minima(F f, T min, T max, int bits);
+
+template <class F, class T>
+std::pair<T, T> brent_find_minima(F f, T min, T max, int bits, boost::uintmax_t& max_iter);
+</pre>
+<a name="math_toolkit.toolkit.internals1.minima.description"></a><h5>
+<a name="id718047"></a>
+ Description
+ </h5>
+
+ These two functions locate the minima of the continuous function f
+ using Brent's algorithm. Parameters are:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>f</dt>
+<dd>
+ The function to minimise. The function should be smooth over the range
+ [min,max], with no maxima occurring in that interval.
+ </dd>
+<dt>min</dt>
+<dd>
+ The lower endpoint of the range in which to search for the minima.
+ </dd>
+<dt>max</dt>
+<dd>
+ The upper endpoint of the range in which to search for the minima.
+ </dd>
+<dt>bits</dt>
+<dd>
+ 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 bits
+ is set to a value greater than one half of the bits in type T, then
+ the value will be ignored.
+ </dd>
+<dt>max_iter</dt>
+<dd>
+ 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.
+ </dd>
+</dl>
+</div>
+
+ Returns: a pair containing the value of
+ the abscissa at the minima and the value of f(x) at the minima.
+ 
+<a name="math_toolkit.toolkit.internals1.minima.implementation"></a><h5>
+<a name="id718186"></a>
+ Implementation
+ </h5>
+
+ This is a reasonably faithful implementation of Brent's algorithm, refer
+ to:
+ 
+
+ Brent, R.P. 1973, Algorithms for Minimization without Derivatives (Englewood
+ Cliffs, NJ: Prentice-Hall), Chapter 5.
+ 
+
+ 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.
+ 
+
+ An algorithm with guaranteed convergence for finding a zero of a function,
+ R. P. Brent, The Computer Journal, Vol 44, 1971.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/tools/rational.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+// Polynomials:
+template <std::size_t N, class T, class V>
+V evaluate_polynomial(const T(&poly)[N], const V& val);
+
+template <std::size_t N, class T, class V>
+V evaluate_polynomial(const boost::array<T,N>& poly, const V& val);
+
+template <class T, class U>
+U evaluate_polynomial(const T* poly, U z, std::size_t count);
+
+// Even polynomials:
+template <std::size_t N, class T, class V>
+V evaluate_even_polynomial(const T(&poly)[N], const V& z);
+
+template <std::size_t N, class T, class V>
+V evaluate_even_polynomial(const boost::array<T,N>& poly, const V& z);
+
+template <class T, class U>
+U evaluate_even_polynomial(const T* poly, U z, std::size_t count);
+
+// Odd polynomials
+template <std::size_t N, class T, class V>
+V evaluate_odd_polynomial(const T(&a)[N], const V& z);
+
+template <std::size_t N, class T, class V>
+V evaluate_odd_polynomial(const boost::array<T,N>& a, const V& z);
+
+template <class T, class U>
+U evaluate_odd_polynomial(const T* poly, U z, std::size_t count);
+
+// Rational Functions:
+template <std::size_t N, class T, class V>
+V evaluate_rational(const T(&a)[N], const T(&b)[N], const V& z);
+
+template <std::size_t N, class T, class V>
+V evaluate_rational(const boost::array<T,N>& a, const boost::array<T,N>& b, const V& z);</spa
n>
+
+template <class T, class U, class V>
+V evaluate_rational(const T* num, const U* denom, V z, unsigned count);
+</pre>
+<a name="math_toolkit.toolkit.internals1.rational.description"></a><h5>
+<a name="id703965"></a>
+ Description
+ </h5>
+
+ 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.
+ 
+<pre class="programlisting">
+template <std::size_t N, class T, class V>
+V evaluate_polynomial(const T(&poly)[N], const V& val);
+
+template <std::size_t N, class T, class V>
+V evaluate_polynomial(const boost::array<T,N>& poly, const V& val);
+
+template <class T, class U>
+U evaluate_polynomial(const T* poly, U z, std::size_t count);
+</pre>
+
+ Evaluates the polynomial
+ described by the coefficients stored in poly.
+ 
+
+ If the size of the array is specified at runtime, then the polynomial most
+ have order count-1 with count
+ coefficients. Otherwise it has order N-1 with N
+ coefficients.
+ 
+
+ Coefficients should be stored such that the coefficients for the xi terms
+ are in poly[i].
+ 
+
+ The types of the coefficients and of variable z may
+ differ as long as *poly is convertible to type U.
+ This allows, for example, for the coefficient table to be a table of integers
+ if this is appropriate.
+ 
+<pre class="programlisting">
+template <std::size_t N, class T, class V>
+V evaluate_even_polynomial(const T(&poly)[N], const V& z);
+
+template <std::size_t N, class T, class V>
+V evaluate_even_polynomial(const boost::array<T,N>& poly, const V& z);
+
+template <class T, class U>
+U evaluate_even_polynomial(const T* poly, U z, std::size_t count);
+</pre>
+
+ As above, but evaluates an even polynomial: one where all the powers of
+ z are even numbers. Equivalent to calling <code class="computeroutput">evaluate_polynomial(poly, z*z, count)</code>.
+ 
+<pre class="programlisting">
+template <std::size_t N, class T, class V>
+V evaluate_odd_polynomial(const T(&a)[N], const V& z);
+
+template <std::size_t N, class T, class V>
+V evaluate_odd_polynomial(const boost::array<T,N>& a, const V& z);
+
+template <class T, class U>
+U evaluate_odd_polynomial(const T* poly, U z, std::size_t count);
+</pre>
+
+ As above but evaluates a polynomial where all the powers are odd numbers.
+ Equivalent to <code class="computeroutput">evaluate_polynomial(poly+1,
+ z*z, count-1)
+ * z
+ + poly[0]</code>.
+ 
+<pre class="programlisting">
+template <std::size_t N, class T, class U, class V>
+V evaluate_rational(const T(&num)[N], const U(&denom)[N], const V& z);
+
+template <std::size_t N, class T, class U, class V>
+V evaluate_rational(const boost::array<T,N>& num, const boost::array<U,N>& denom, const V& z)
;
+
+template <class T, class U, class V>
+V evaluate_rational(const T* num, const U* denom, V z, unsigned count);
+</pre>
+
+ Evaluates the rational function (the ratio of two polynomials) described
+ by the coefficients stored in num and demom.
+ 
+
+ If the size of the array is specified at runtime then both polynomials
+ most have order count-1 with count
+ coefficients. Otherwise both polynomials have order N-1
+ with N coefficients.
+ 
+
+ Array num describes the numerator, and demon
+ the denominator.
+ 
+
+ Coefficients should be stored such that the coefficients for the xi terms
+ are in num[i] and denom[i].
+ 
+
+ The types of the coefficients and of variable v may
+ differ as long as *num and *denom
+ are convertible to type V. This allows, for example,
+ for one or both of the coefficient tables to be a table of integers if
+ this is appropriate.
+ 
+
+ These functions are designed to safely evaluate the result, even when the
+ value z 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 z 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.
+ 
+<a name="math_toolkit.toolkit.internals1.rational.implementation"></a><h5>
+<a name="id706434"></a>
+ Implementation
+ </h5>
+
+ 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.
+ 
+
+ 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 v
+ is greater than one, then the polynomials are evaluated in reverse order
+ as polynomials in 1/v: this avoids unnecessary numerical
+ overflow when the coefficients are large.
+ 
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/tools/roots.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{ namespace tools{
+
+template <class F, class T>
+T newton_raphson_iterate(F f, T guess, T min, T max, int digits);
+
+template <class F, class T>
+T newton_raphson_iterate(F f, T guess, T min, T max, int digits, boost::uintmax_t& max_iter);
+
+template <class F, class T>
+T halley_iterate(F f, T guess, T min, T max, int digits);
+
+template <class F, class T>
+T halley_iterate(F f, T guess, T min, T max, int digits, boost::uintmax_t& max_iter);
+
+template <class F, class T>
+T schroeder_iterate(F f, T guess, T min, T max, int digits);
+
+template <class F, class T>
+T schroeder_iterate(F f, T guess, T min, T max, int digits, boost::uintmax_t& max_iter);
+
+}}} // namespaces
+</pre>
+<a name="math_toolkit.toolkit.internals1.roots.description"></a><h5>
+<a name="id707710"></a>
+ Description
+ </h5>
+
+ These functions all perform iterative root finding: <code class="computeroutput">newton_raphson_iterate</code>
+ performs second order Newton Raphson iteration,
+ while <code class="computeroutput">halley_iterate</code> and
+ <code class="computeroutput">schroeder_iterate</code> perform
+ third order Halley and Schroeder
+ iteration respectively.
+ 
+
+ The functions all take the same parameters:
+ 
+<div class="variablelist">
+Parameters of the root finding functions
+<dl>
+<dt>F
+ f</dt>
+<dd>
+
+ Type F must be a callable function object that accepts one parameter
+ and returns a tuple:
+ 
+
+ 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.
+ 
+
+ 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.
+ 
+</dd>
+<dt>T guess</dt>
+<dd>
+ The initial starting value.
+ </dd>
+<dt>T min</dt>
+<dd>
+ The minimum possible value for the result, this is used as an initial
+ lower bracket.
+ </dd>
+<dt>T max</dt>
+<dd>
+ The maximum possible value for the result, this is used as an initial
+ upper bracket.
+ </dd>
+<dt>int digits</dt>
+<dd>
+ The desired number of binary digits.
+ </dd>
+<dt>uintmax_t max_iter</dt>
+<dd>
+ An optional maximum number of iterations to perform.
+ </dd>
+</dl>
+</div>
+
+ When using these functions you should note that:
+ 
+<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 of the correct sign 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 digits 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 digits 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, digits
+ 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>
+ 
+<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>
+
+ Given an initial guess x0 the subsequent values are computed using:
+ 
+
+ <img src="../../../../equations/roots1.png">
+ 
+
+ Out of bounds steps revert to bisection of the current bounds.
+ 
+
+ Under ideal conditions, the number of correct digits doubles with each
+ iteration.
+ 
+<a name="halley"></a>
+ 
+<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>
+
+ Given an initial guess x0 the subsequent values are computed using:
+ 
+
+ <img src="../../../../equations/roots2.png">
+ 
+
+ Over-compensation by the second derivative (one which would proceed in
+ the wrong direction) causes the method to revert to a Newton-Raphson step.
+ 
+
+ Out of bounds steps revert to bisection of the current bounds.
+ 
+
+ Under ideal conditions, the number of correct digits trebles with each
+ iteration.
+ 
+<a name="schroeder"></a>
+ 
+<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>
+
+ Given an initial guess x0 the subsequent values are computed using:
+ 
+
+ <img src="../../../../equations/roots3.png">
+ 
+
+ 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%.
+ 
+
+ Out of bounds steps revert to bisection of the current bounds.
+ 
+
+ Under ideal conditions, the number of correct digits trebles with each
+ iteration.
+ 
+<a name="math_toolkit.toolkit.internals1.roots.example"></a><h5>
+<a name="id708279"></a>
+ Example
+ </h5>
+
+ Lets suppose we want to find the cube root of a number, the equation we
+ want to solve along with its derivatives are:
+ 
+
+ <img src="../../../../equations/roots4.png">
+ 
+
+ 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:
+ 
+<pre class="programlisting">
+template <class T>
+struct cbrt_functor
+{
+ cbrt_functor(T const& target) : a(target){}
+ std::tr1::tuple<T, T> operator()(T const& z)
+ {
+ T sqr = z * z;
+ return std::tr1::make_tuple(sqr * z - a, 3 * sqr);
+ }
+private:
+ T a;
+};
+</pre>
+
+ 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:
+ 
+<pre class="programlisting">
+template <class T>
+T cbrt(T z)
+{
+ using namespace std;
+ int exp;
+ frexp(z, &exp);
+ T min = ldexp(0.5, exp/3);
+ T max = ldexp(2.0, exp/3);
+ T guess = ldexp(1.0, exp/3);
+ int digits = std::numeric_limits<T>::digits;
+ return tools::newton_raphson_iterate(detail::cbrt_functor<T>(z), guess, min, max, digits);
+}
+</pre>
+
+ 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">std::numeric_limits<T>::digits
+ * 2 / 3</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.
+ 
+
+ 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!
+ 
+
+ Now lets adapt the functor slightly to return the second derivative as
+ well:
+ 
+<pre class="programlisting">
+template <class T>
+struct cbrt_functor
+{
+ cbrt_functor(T const& target) : a(target){}
+ std::tr1::tuple<T, T, T> operator()(T const& z)
+ {
+ T sqr = z * z;
+ return std::tr1::make_tuple(sqr * z - a, 3 * sqr, 6 * z);
+ }
+private:
+ T a;
+};
+</pre>
+
+ And then adapt the <code class="computeroutput">cbrt</code>
+ function to use Halley iterations:
+ 
+<pre class="programlisting">
+template <class T>
+T cbrt(T z)
+{
+ using namespace std;
+ int exp;
+ frexp(z, &exp);
+ T min = ldexp(0.5, exp/3);
+ T max = ldexp(2.0, exp/3);
+ T guess = ldexp(1.0, exp/3);
+ int digits = std::numeric_limits<T>::digits / 2;
+ return tools::halley_iterate(detail::cbrt_functor<T>(z), guess, min, max, digits);
+}
+</pre>
+
+ 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.
+ 
+
+ Just to complete the picture, we could have called <code class="computeroutput">schroeder_iterate</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".
+ 
+
+ 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: nothing
+ beats a really good initial guess!
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/tools/roots.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{ namespace tools{
+
+template <class F, class T, class Tol>
+std::pair<T, T>
+ bisect(
+ F f,
+ T min,
+ T max,
+ Tol tol,
+ boost::uintmax_t& max_iter);
+
+template <class F, class T, class Tol>
+std::pair<T, T>
+ bisect(
+ F f,
+ T min,
+ T max,
+ Tol tol);
+
+template <class F, class T, class Tol, class Policy>
+std::pair<T, T>
+ bisect(
+ F f,
+ T min,
+ T max,
+ Tol tol,
+ boost::uintmax_t& max_iter,
+ const Policy&);
+
+template <class F, class T, class Tol>
+std::pair<T, T>
+ bracket_and_solve_root(
+ F f,
+ const T& guess,
+ const T& factor,
+ bool rising,
+ Tol tol,
+ boost::uintmax_t& max_iter);
+
+template <class F, class T, class Tol, class Policy>
+std::pair<T, T>
+ bracket_and_solve_root(
+ F f,
+ const T& guess,
+ const T& factor,
+ bool rising,
+ Tol tol,
+ boost::uintmax_t& max_iter,
+ const Policy&);
+
+template <class F, class T, class Tol>
+std::pair<T, T>
+ toms748_solve(
+ F f,
+ const T& a,
+ const T& b,
+ Tol tol,
+ boost::uintmax_t& max_iter);
+
+template <class F, class T, class Tol, class Policy>
+std::pair<T, T>
+ toms748_solve(
+ F f,
+ const T& a,
+ const T& b,
+ Tol tol,
+ boost::uintmax_t& max_iter,
+ const Policy&);
+
+template <class F, class T, class Tol>
+std::pair<T, T>
+ toms748_solve(
+ F f,
+ const T& a,
+ const T& b,
+ const T& fa,
+ const T& fb,
+ Tol tol,
+ boost::uintmax_t& max_iter);
+
+template <class F, class T, class Tol, class Policy>
+std::pair<T, T>
+ toms748_solve(
+ F f,
+ const T& a,
+ const T& b,
+ const T& fa,
+ const T& fb,
+ Tol tol,
+ boost::uintmax_t& max_iter,
+ const Policy&);
+
+// Termination conditions:
+template <class T>
+struct eps_tolerance;
+
+struct equal_floor;
+struct equal_ceil;
+struct equal_nearest_integer;
+
+}}} // namespaces
+</pre>
+<a name="math_toolkit.toolkit.internals1.roots2.description"></a><h5>
+<a name="id713044"></a>
+ Description
+ </h5>
+
+ These functions solve the root of some function f(x)
+ without the need for the derivatives of f(x). 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.
+ 
+
+ 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.
+ 
+
+ 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 never
+ 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: eps_tolerance causes termination when
+ the relative error in the enclosing interval is below a certain threshold,
+ while equal_floor and equal_ceil
+ 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.
+ 
+<pre class="programlisting">
+template <class F, class T, class Tol>
+std::pair<T, T>
+ bisect(
+ F f,
+ T min,
+ T max,
+ Tol tol,
+ boost::uintmax_t& max_iter);
+
+template <class F, class T, class Tol>
+std::pair<T, T>
+ bisect(
+ F f,
+ T min,
+ T max,
+ Tol tol);
+
+template <class F, class T, class Tol, class Policy>
+std::pair<T, T>
+ bisect(
+ F f,
+ T min,
+ T max,
+ Tol tol,
+ boost::uintmax_t& max_iter,
+ const Policy&);
+</pre>
+
+ These functions locate the root using bisection, function arguments are:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>f</dt>
+<dd>
+ A unary functor which is the function whose root is to be found.
+ </dd>
+<dt>min</dt>
+<dd>
+ The left bracket of the interval known to contain the root.
+ </dd>
+<dt>max</dt>
+<dd>
+ The right bracket of the interval known to contain the root. It is
+ a precondition that min < max and f(min)*f(max)
+ <= 0, 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.
+ </dd>
+<dt>tol</dt>
+<dd>
+ A binary functor that specifies the termination condition: the function
+ will return the current brackets enclosing the root when tol(min,max)
+ becomes true.
+ </dd>
+<dt>max_iter</dt>
+<dd>
+ The maximum number of invocations of f(x) to make
+ while searching for the root.
+ </dd>
+</dl>
+</div>
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Returns: a pair of values r that bracket the root
+ so that:
+ 
+<pre class="programlisting">
+f(r.first) * f(r.second) <= 0
+</pre>
+
+ and either
+ 
+<pre class="programlisting">
+tol(r.first, r.second) == true
+</pre>
+
+ or
+ 
+<pre class="programlisting">
+max_iter >= m
+</pre>
+
+ where m is the initial value of max_iter
+ passed to the function.
+ 
+
+ In other words, it's up to the caller to verify whether termination occurred
+ as a result of exceeding max_iter function invocations
+ (easily done by checking the value of max_iter when
+ the function returns), rather than because the termination condition tol
+ was satisfied.
+ 
+<pre class="programlisting">
+template <class F, class T, class Tol>
+std::pair<T, T>
+ bracket_and_solve_root(
+ F f,
+ const T& guess,
+ const T& factor,
+ bool rising,
+ Tol tol,
+ boost::uintmax_t& max_iter);
+
+template <class F, class T, class Tol, class Policy>
+std::pair<T, T>
+ bracket_and_solve_root(
+ F f,
+ const T& guess,
+ const T& factor,
+ bool rising,
+ Tol tol,
+ boost::uintmax_t& max_iter,
+ const Policy&);
+</pre>
+
+ This is a convenience function that calls toms748_solve
+ internally to find the root of f(x). It's usable only
+ when f(x) 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 x. The
+ parameters are:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>f</dt>
+<dd>
+ A unary functor that is the function whose root is to be solved. f(x)
+ must be uniformly increasing or decreasing on x.
+ </dd>
+<dt>guess</dt>
+<dd>
+ An initial approximation to the root
+ </dd>
+<dt>factor</dt>
+<dd>
+ A scaling factor that is used to bracket the root: the value guess
+ is multiplied (or divided as appropriate) by factor
+ until two values are found that bracket the root. A value such as 2
+ is a typical choice for factor.
+ </dd>
+<dt>rising</dt>
+<dd>
+ Set to true if f(x) is rising
+ on x and false if f(x)
+ is falling on x. This value is used along with
+ the result of f(guess) to determine if guess
+ is above or below the root.
+ </dd>
+<dt>tol</dt>
+<dd>
+ A binary functor that determines the termination condition for the
+ search for the root. tol is passed the current
+ brackets at each step, when it returns true then the current brackets
+ are returned as the result.
+ </dd>
+<dt>max_iter</dt>
+<dd>
+ The maximum number of function invocations to perform in the search
+ for the root.
+ </dd>
+</dl>
+</div>
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Returns: a pair of values r that bracket the root
+ so that:
+ 
+<pre class="programlisting">
+f(r.first) * f(r.second) <= 0
+</pre>
+
+ and either
+ 
+<pre class="programlisting">
+tol(r.first, r.second) == true
+</pre>
+
+ or
+ 
+<pre class="programlisting">
+max_iter >= m
+</pre>
+
+ where m is the initial value of max_iter
+ passed to the function.
+ 
+
+ In other words, it's up to the caller to verify whether termination occurred
+ as a result of exceeding max_iter function invocations
+ (easily done by checking the value of max_iter when
+ the function returns), rather than because the termination condition tol
+ was satisfied.
+ 
+<pre class="programlisting">
+template <class F, class T, class Tol>
+std::pair<T, T>
+ toms748_solve(
+ F f,
+ const T& a,
+ const T& b,
+ Tol tol,
+ boost::uintmax_t& max_iter);
+
+template <class F, class T, class Tol, class Policy>
+std::pair<T, T>
+ toms748_solve(
+ F f,
+ const T& a,
+ const T& b,
+ Tol tol,
+ boost::uintmax_t& max_iter,
+ const Policy&);
+
+template <class F, class T, class Tol>
+std::pair<T, T>
+ toms748_solve(
+ F f,
+ const T& a,
+ const T& b,
+ const T& fa,
+ const T& fb,
+ Tol tol,
+ boost::uintmax_t& max_iter);
+
+template <class F, class T, class Tol, class Policy>
+std::pair<T, T>
+ toms748_solve(
+ F f,
+ const T& a,
+ const T& b,
+ const T& fa,
+ const T& fb,
+ Tol tol,
+ boost::uintmax_t& max_iter,
+ const Policy&);
+</pre>
+
+ These two functions implement TOMS Algorithm 748: it uses a mixture of
+ cubic, quadratic and linear (secant) interpolation to locate the root of
+ f(x). The two functions differ only by whether values
+ for f(a) and f(b) are already
+ available. The parameters are:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>f</dt>
+<dd>
+ A unary functor that is the function whose root is to be solved. f(x)
+ need not be uniformly increasing or decreasing on x
+ and may have multiple roots.
+ </dd>
+<dt>a</dt>
+<dd>
+ The lower bound for the initial bracket of the root.
+ </dd>
+<dt>b</dt>
+<dd>
+ The upper bound for the initial bracket of the root. It is a precondition
+ that a < b and that a
+ and b bracket the root to find so that f(a)*f(b)
+ < 0.
+ </dd>
+<dt>fa</dt>
+<dd>
+ Optional: the value of f(a).
+ </dd>
+<dt>fb</dt>
+<dd>
+ Optional: the value of f(b).
+ </dd>
+<dt>tol</dt>
+<dd>
+ A binary functor that determines the termination condition for the
+ search for the root. tol is passed the current
+ brackets at each step, when it returns true then the current brackets
+ are returned as the result.
+ </dd>
+<dt>max_iter</dt>
+<dd>
+ The maximum number of function invocations to perform in the search
+ for the root. On exit max_iter is set to actual
+ number of function invocations used.
+ </dd>
+</dl>
+</div>
+
+ 
+
+ 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.
+ 
+
+ 
+
+ Returns: a pair of values r that bracket the root
+ so that:
+ 
+<pre class="programlisting">
+f(r.first) * f(r.second) <= 0
+</pre>
+
+ and either
+ 
+<pre class="programlisting">
+tol(r.first, r.second) == true
+</pre>
+
+ or
+ 
+<pre class="programlisting">
+max_iter >= m
+</pre>
+
+ where m is the initial value of max_iter
+ passed to the function.
+ 
+
+ In other words, it's up to the caller to verify whether termination occurred
+ as a result of exceeding max_iter function invocations
+ (easily done by checking the value of max_iter), rather
+ than because the termination condition tol was satisfied.
+ 
+<pre class="programlisting">
+template <class T>
+struct eps_tolerance
+{
+ eps_tolerance(int bits);
+ bool operator()(const T& a, const T& b)const;
+};
+</pre>
+
+ This is the usual termination condition used with these root finding functions.
+ Its operator() will return true when the relative distance between a
+ and b is less than twice the machine epsilon for T,
+ or 21-bits, whichever is the larger. In other words you set bits
+ 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.
+ 
+<pre class="programlisting">
+struct equal_floor
+{
+ equal_floor();
+ template <class T> bool operator()(const T& a, const T& b)const;
+};
+</pre>
+
+ This termination condition is used when you want to find an integer result
+ that is the floor of the true root. It will terminate
+ as soon as both ends of the interval have the same floor.
+ 
+<pre class="programlisting">
+struct equal_ceil
+{
+ equal_ceil();
+ template <class T> bool operator()(const T& a, const T& b)const;
+};
+</pre>
+
+ This termination condition is used when you want to find an integer result
+ that is the ceil of the true root. It will terminate
+ as soon as both ends of the interval have the same ceil.
+ 
+<pre class="programlisting">
+struct equal_nearest_integer
+{
+ equal_nearest_integer();
+ template <class T> bool operator()(const T& a, const T& b)const;
+};
+</pre>
+
+ This termination condition is used when you want to find an integer result
+ that is the closest to the true root. It will terminate
+ as soon as both ends of the interval round to the same nearest integer.
+ 
+<a name="math_toolkit.toolkit.internals1.roots2.implementation"></a><h5>
+<a name="id717509"></a>
+ Implementation
+ </h5>
+
+ The implementation of the bisection algorithm is extremely straightforward
+ and not detailed here. TOMS algorithm 748 is described in detail in:
+ 
+
+ 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.
+ 
+
+ The implementation here is a faithful translation of this paper into C++.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/tools/series.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{ namespace tools{
+
+template <class Functor>
+typename Functor::result_type sum_series(Functor& func, int bits);
+
+template <class Functor>
+typename Functor::result_type sum_series(Functor& func, int bits, boost::uintmax_t& max_terms);
+
+template <class Functor, class U>
+typename Functor::result_type sum_series(Functor& func, int bits, U init_value);
+
+template <class Functor, class U>
+typename Functor::result_type sum_series(Functor& func, int bits, boost::uintmax_t& max_terms, U init_value);
+
+template <class Functor>
+typename Functor::result_type kahan_sum_series(Functor& func, int bits);
+
+template <class Functor>
+typename Functor::result_type kahan_sum_series(Functor& func, int bits, boost::uintmax_t& max_terms);
+
+}}} // namespaces
+</pre>
+<a name="math_toolkit.toolkit.internals1.series_evaluation.description"></a><h5>
+<a name="id698908"></a>
+ Description
+ </h5>
+
+ These algorithms are intended for the <a href="http://en.wikipedia.org/wiki/Series_%28mathematics%29" target="_top">summation
+ of infinite series</a>.
+ 
+
+ 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.
+ 
+
+ 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 bits bits of the result.
+ 
+
+ The optional third argument max_terms sets an upper
+ limit on the number of terms of the series to evaluate. In addition, on
+ exit the function will set max_terms 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.
+ 
+
+ The final optional argument init_value is the initial
+ value of the sum to which the terms of the series should be added. This
+ is useful in two situations:
+ 
+<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 1 - S(z) 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 1
+ - S(z).
+ </li>
+</ul></div>
+
+ The two kahan_sum_series 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">Kahan
+ Summation Formula</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.
+ 
+<a name="math_toolkit.toolkit.internals1.series_evaluation.example"></a><h5>
+<a name="id699056"></a>
+ Example
+ </h5>
+
+ Let's suppose we want to implement log(1+x) via its
+ infinite series,
+ 
+
+ <img src="../../../../equations/log1pseries.png">
+ 
+
+ We begin by writing a small function object to return successive terms
+ of the series:
+ 
+<pre class="programlisting">
+template <class T>
+struct log1p_series
+{
+ // we must define a result_type typedef:
+ typedef T result_type;
+
+ log1p_series(T x)
+ : k(0), m_mult(-x), m_prod(-1){}
+
+ T operator()()
+ {
+ // This is the function operator invoked by the summation
+ // algorithm, the first call to this operator should return
+ // the first term of the series, the second call the second
+ // term and so on.
+ m_prod *= m_mult;
+ return m_prod / ++k;
+ }
+
+private:
+ int k;
+ const T m_mult;
+ T m_prod;
+};
+</pre>
+
+ Implementing log(1+x) is now fairly trivial:
+ 
+<pre class="programlisting">
+template <class T>
+T log1p(T x)
+{
+ // We really should add some error checking on x here!
+ assert(std::fabs(x) < 1);
+
+ // construct the series functor:
+ log1p_series<T> s(x);
+ // and add it up, with enough digits for full machine precision
+ // plus a couple more for luck.... !
+ return tools::sum_series(s, tools::digits(x) + 2);
+}
+</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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> Polynomials</dt>
+<dt><a href="internals2/minimax.html"> Minimax Approximations
+ and the Remez Algorithm</a></dt>
+<dt><a href="internals2/error_test.html"> Relative
+ Error and Testing</a></dt>
+<dt><a href="internals2/test_data.html"> Graphing,
+ Profiling, and Generating Test Data for Special Functions</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/tools/test.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+template <class T>
+T relative_error(T a, T b);
+
+template <class A, class F1, class F2>
+test_result<see-below> test(const A& a, F1 test_func, F2 expect_func);
+</pre>
+<a name="math_toolkit.toolkit.internals2.error_test.description"></a><h5>
+<a name="id722468"></a>
+ Description
+ </h5>
+<pre class="programlisting">
+template <class T>
+T relative_error(T a, T v);
+</pre>
+
+ Returns the relative error between a and v
+ using the usual formula:
+ 
+
+ <img src="../../../../equations/error1.png">
+ 
+
+ In addition the value returned is zero if:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Both a and v are infinite.
+ </li>
+<li>
+ Both a and v are denormalised
+ numbers or zero.
+ </li>
+</ul></div>
+
+ Otherwise if only one of a and v
+ is zero then the value returned is 1.
+ 
+<pre class="programlisting">
+template <class A, class F1, class F2>
+test_result<see-below> test(const A& a, F1 test_func, F2 expect_func);
+</pre>
+
+ This function is used for testing a function against tabulated test data.
+ 
+
+ 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:
+ 
+<div class="variablelist">
+
+<dl>
+<dt><code class="computeroutput">unsigned
+ worst()const;</code></dt>
+<dd>
+ Returns the row at which the worst error occurred.
+ </dd>
+<dt><code class="computeroutput">T
+ min()const;</code></dt>
+<dd>
+ Returns the smallest relative error found.
+ </dd>
+<dt><code class="computeroutput">T
+ max()const;</code></dt>
+<dd>
+ Returns the largest relative error found.
+ </dd>
+<dt><code class="computeroutput">T
+ mean()const;</code></dt>
+<dd>
+ Returns the mean error found.
+ </dd>
+<dt><code class="computeroutput">boost::uintmax_t
+ count()const;</code></dt>
+<dd>
+ Returns the number of test cases.
+ </dd>
+<dt><code class="computeroutput">T
+ variance()const;</code></dt>
+<dd>
+ Returns the variance of the errors found.
+ </dd>
+<dt><code class="computeroutput">T
+ variance1()const;</code></dt>
+<dd>
+ Returns the unbiased variance of the errors found.
+ </dd>
+<dt><code class="computeroutput">T
+ rms()const</code></dt>
+<dd>
+ Returns the Root Mean Square, or quadratic mean of the errors.
+ </dd>
+<dt><code class="computeroutput">test_result& operator+=(const test_result&
+ t)</code></dt>
+<dd>
+ Combines two test_result's into a single result.
+ </dd>
+</dl>
+</div>
+
+ The template parameter of test_result, is the same type as the values in
+ the two dimensional array passed to function test,
+ roughly that's <code class="computeroutput">A::value_type::value_type</code>.
+ 
+
+ Parameter a 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 a should contain all the parameters that
+ are passed to the function under test as well as the expected result.
+ 
+
+ Parameter test_func is the function under test, it
+ is invoked with each row of test data in a. Typically
+ type F1 is created with Boost.Lambda: see the example below.
+ 
+
+ Parameter expect_func is a functor that extracts the
+ expected result from a row of test data in a. Typically
+ type F2 is created with Boost.Lambda: see the example below.
+ 
+
+ 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">std::cerr</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).
+ 
+<a name="math_toolkit.toolkit.internals2.error_test.example"></a><h5>
+<a name="id723422"></a>
+ Example
+ </h5>
+
+ 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.
+ 
+<pre class="programlisting">
+static const boost::array<boost::array<TestType, 3>, NumberOfTests>
+ factorials = {
+ /* big array of test data goes here */
+ };
+</pre>
+
+ Now we can invoke the test function to test tgamma:
+ 
+<pre class="programlisting">
+using namespace boost::math::tools;
+using namespace boost::lambda;
+
+// get a pointer to the function under test:
+TestType (*funcp)(TestType) = boost::math::tgamma;
+
+// declare something to hold the result:
+test_result<TestType> result;
+//
+// and test tgamma against data:
+//
+result = test(
+ factorials,
+ bind(funcp, ret<TestType>(_1[0])), // calls tgamma with factorials[row][0]
+ ret<TestType>(_1[1]) // extracts the expected result from factorials[row][1]
+);
+//
+// Print out some results:
+//
+std::cout << "The Mean was " << result.mean() << std::endl;
+std::cout << "The worst error was " << (result.max)() << std::endl;
+std::cout << "The worst error was at row " << result.worst_case() << std::endl;
+//
+// same again with lgamma this time:
+//
+funcp = boost::math::lgamma;
+result = test(
+ factorials,
+ bind(funcp, ret<TestType>(_1[0])), // calls tgamma with factorials[row][0]
+ ret<TestType>(_1[2]) // extracts the expected result from factorials[row][2]
+);
+//
+// etc ...
+//
+</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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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.
+ 
+
+ 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.
+ 
+
+ 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>.
+ 
+
+ The program consists of two parts:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>main.cpp</dt>
+<dd>
+ Contains the command line parser, and all the calls to the Remez code.
+ </dd>
+<dt>f.cpp</dt>
+<dd>
+ Contains the function to approximate.
+ </dd>
+</dl>
+</div>
+
+ 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:
+ 
+<pre class="programlisting">
+NTL::RR f(const NTL::RR& x, int variant);
+</pre>
+
+ Returns the value of the function variant at point
+ x. So if you wish you can just add the function to
+ approximate as a new variant after the existing examples.
+ 
+
+ In addition to those two files, the program needs to be linked to a patched NTL library to compile.
+ 
+
+ Note that the function f must return the rational
+ part of the approximation: for example if you are approximating a function
+ f(x) then it is quite common to use:
+ 
+<pre class="programlisting">
+f(x) = g(x)(Y + R(x))
+</pre>
+
+ where g(x) is the dominant part of f(x),
+ Y is some constant, and R(x)
+ is the rational approximation part, usually optimised for a low absolute
+ error compared to |Y|.
+ 
+
+ In this case you would define f to return f(x)/g(x)
+ and then set the y-offset of the approximation to Y
+ (see command line options below).
+ 
+
+ Many other forms are possible, but in all cases the objective is to split
+ f(x) 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.
+ 
+
+ Command line options for the program are as follows:
+ 
+<div class="variablelist">
+
+<dl>
+<dt>variant N</dt>
+<dd>
+ 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.
+ </dd>
+<dt>range a b</dt>
+<dd>
+ Sets the domain for the approximation to the range [a,b], defaults
+ to [0,1].
+ </dd>
+<dt>relative</dt>
+<dd>
+ 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.
+ </dd>
+<dt>absolute</dt>
+<dd>
+ Sets the Remez code to optimise for absolute error.
+ </dd>
+<dt>pin [true|false]</dt>
+<dd>
+ "Pins" the code so that the rational approximation passes
+ through the origin. Obviously only set this to true
+ 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.
+ </dd>
+<dt>order N D</dt>
+<dd>
+ Sets the order of the approximation to N in the
+ numerator and D in the denominator. If D
+ 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 pin was set to true, and the first
+ coefficient of the denominator is always one.
+ </dd>
+<dt>working-precision N</dt>
+<dd>
+ Sets the working precision of NTL::RR to N binary
+ digits. Defaults to 250.
+ </dd>
+<dt>target-precision N</dt>
+<dd>
+ Sets the precision of printed output to N 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).
+ </dd>
+<dt>skew val</dt>
+<dd>
+ "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. val should
+ be in the range [-100,+100], the default is zero.
+ </dd>
+<dt>brake val</dt>
+<dd>
+ Sets a brake on each step so that the change in the control points
+ is braked by val%. Defaults to 50, try a higher
+ value if an approximation won't converge, or a lower value to get speedier
+ convergence.
+ </dd>
+<dt>x-offset val</dt>
+<dd>
+ Sets the x-offset to val: the approximation will
+ be generated for <code class="computeroutput">f(x + X) + Y</code> where X is
+ the x-offset and Y 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.
+ </dd>
+<dt>y-offset val</dt>
+<dd>
+ Sets the y-offset to val: the approximation will
+ be generated for <code class="computeroutput">f(x + X) + Y</code> where X is
+ the x-offset and Y 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.
+ </dd>
+<dt>y-offset auto</dt>
+<dd>
+ 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 float precision
+ (and should be stored as a float in your code).
+ The approximation will be generated for <code class="computeroutput">f(x + X) + Y</code> where X is
+ the x-offset and Y is the y-offset. Defaults to
+ zero.
+ </dd>
+<dt>graph N</dt>
+<dd>
+ Prints N evaluations of f(x) at evenly spaced points over the range
+ being optimised. If unspecified then N defaults
+ to 3. Use to check that f(x) is indeed smooth over the range of interest.
+ </dd>
+<dt>step N</dt>
+<dd>
+ Performs N steps, or one step if N
+ 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.
+ </dd>
+<dt>test [float|double|long]</dt>
+<dd>
+ 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.
+ </dd>
+<dt>test [float|double|long] N</dt>
+<dd>
+ 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.
+ </dd>
+<dt>rescale a b</dt>
+<dd>
+ 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.
+ </dd>
+<dt>rotate</dt>
+<dd>
+ 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.
+ </dd>
+<dt>info</dt>
+<dd>
+ 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.
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+
+
+<pre class="programlisting">
+#include <boost/math/tools/polynomial.hpp>
+</pre>
+
+ 
+<pre class="programlisting">
+namespace boost{ namespace math{ namespace tools{
+
+template <class T>
+class polynomial
+{
+public:
+ // typedefs:
+ typedef typename std::vector<T>::value_type value_type;
+ typedef typename std::vector<T>::size_type size_type;
+
+ // construct:
+ polynomial(){}
+ template <class U>
+ polynomial(const U* data, unsigned order);
+ template <class U>
+ polynomial(const U& point);
+
+ // access:
+ size_type size()const;
+ size_type degree()const;
+ value_type& operator[](size_type i);
+ const value_type& operator[](size_type i)const;
+
+ // operators:
+ template <class U>
+ polynomial& operator +=(const U& value);
+ template <class U>
+ polynomial& operator -=(const U& value);
+ template <class U>
+ polynomial& operator *=(const U& value);
+ template <class U>
+ polynomial& operator +=(const polynomial<U>& value);
+ template <class U>
+ polynomial& operator -=(const polynomial<U>& value);
+ template <class U>
+ polynomial& operator *=(const polynomial<U>& value);
+};
+
+template <class T>
+polynomial<T> operator + (const polynomial<T>& a, const polynomial<T>& b);
+template <class T>
+polynomial<T> operator - (const polynomial<T>& a, const polynomial<T>& b);
+template <class T>
+polynomial<T> operator * (const polynomial<T>& a, const polynomial<T>& b);
+
+template <class T, class U>
+polynomial<T> operator + (const polynomial<T>& a, const U& b);
+template <class T, class U>
+polynomial<T> operator - (const polynomial<T>& a, const U& b);
+template <class T, class U>
+polynomial<T> operator * (const polynomial<T>& a, const U& b);
+
+template <class U, class T>
+polynomial<T> operator + (const U& a, const polynomial<T>& b);
+template <class U, class T>
+polynomial<T> operator - (const U& a, const polynomial<T>& b);
+template <class U, class T>
+polynomial<T> operator * (const U& a, const polynomial<T>& b);
+
+template <class charT, class traits, class T>
+std::basic_ostream<charT, traits>& operator <<
+ (std::basic_ostream<charT, traits>& os, const polynomial<T>& poly);
+
+}}} // namespaces
+</pre>
+<a name="math_toolkit.toolkit.internals2.polynomials.description"></a><h5>
+<a name="id721052"></a>
+ Description
+ </h5>
+
+ This is a fairly trivial class for polynomial manipulation.
+ 
+
+ 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.
+ 
+
+ Advanced manipulations: the FFT, division, GCD, factorisation etc are not
+ currently provided. Submissions for these are of course welcome :-)
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ The class <code class="computeroutput">test_data</code> and
+ associated helper functions are designed so that in just a few lines of
+ code you should be able to:
+ 
+<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">
+namespace boost{ namespace math{ namespace tools{
+
+enum parameter_type
+{
+ random_in_range = 0,
+ periodic_in_range = 1,
+ power_series = 2,
+ dummy_param = 0x80,
+};
+
+template <class T>
+struct parameter_info;
+
+template <class T>
+parameter_info<T> make_random_param(T start_range, T end_range, int n_points);
+
+template <class T>
+parameter_info<T> make_periodic_param(T start_range, T end_range, int n_points);
+
+template <class T>
+parameter_info<T> make_power_param(T basis, int start_exponent, int end_exponent);
+
+template <class T>
+bool get_user_parameter_info(parameter_info<T>& info, const char* param_name);
+
+template <class T>
+class test_data
+{
+public:
+ typedef std::vector<T> row_type;
+ typedef row_type value_type;
+private:
+ typedef std::set<row_type> container_type;
+public:
+ typedef typename container_type::reference reference;
+ typedef typename container_type::const_reference const_reference;
+ typedef typename container_type::iterator iterator;
+ typedef typename container_type::const_iterator const_iterator;
+ typedef typename container_type::difference_type difference_type;
+ typedef typename container_type::size_type size_type;
+
+ // creation:
+ test_data(){}
+ template <class F>
+ test_data(F func, const parameter_info<T>& arg1);
+
+ // insertion:
+ template <class F>
+ test_data& insert(F func, const parameter_info<T>& arg1);
+
+ template <class F>
+ test_data& insert(F func, const parameter_info<T>& arg1,
+ const parameter_info<T>& arg2);
+
+ template <class F>
+ test_data& insert(F func, const parameter_info<T>& arg1,
+ const parameter_info<T>& arg2,
+ const parameter_info<T>& arg3);
+
+ void clear();
+
+ // access:
+ iterator begin();
+ iterator end();
+ const_iterator begin()const;
+ const_iterator end()const;
+ bool operator==(const test_data& d)const;
+ bool operator!=(const test_data& d)const;
+ void swap(test_data& other);
+ size_type size()const;
+ size_type max_size()const;
+ bool empty()const;
+
+ bool operator < (const test_data& dat)const;
+ bool operator <= (const test_data& dat)const;
+ bool operator > (const test_data& dat)const;
+ bool operator >= (const test_data& dat)const;
+};
+
+template <class charT, class traits, class T>
+std::basic_ostream<charT, traits>& write_csv(
+ std::basic_ostream<charT, traits>& os,
+ const test_data<T>& data);
+
+template <class charT, class traits, class T>
+std::basic_ostream<charT, traits>& write_csv(
+ std::basic_ostream<charT, traits>& os,
+ const test_data<T>& data,
+ const charT* separator);
+
+template <class T>
+std::ostream& write_code(std::ostream& os,
+ const test_data<T>& data,
+ const char* name);
+
+}}} // namespaces
+</pre>
+<a name="math_toolkit.toolkit.internals2.test_data.description"></a><h5>
+<a name="id727446"></a>
+ Description
+ </h5>
+
+ This tool is best illustrated with the following series of examples.
+ 
+
+ The functionality of test_data is split into the following parts:
+ 
+<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
+ this 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>
+
+ For example, lets say we want to graph the lgamma function between -3 and
+ 100, one could do this like so:
+ 
+<pre class="programlisting">
+#include <boost/math/tools/test_data.hpp>
+#include <boost/math/special_functions/gamma.hpp>
+
+int main()
+{
+ using namespace boost::math::tools;
+
+ // create an object to hold the data:
+ test_data<double> data;
+
+ // insert 500 points at uniform intervals between just after -3 and 100:
+ double (*pf)(double) = boost::math::lgamma;
+ data.insert(pf, make_periodic_param(-3.0 + 0.00001, 100.0, 500));
+
+ // print out in csv format:
+ write_csv(std::cout, data, ", ");
+ return 0;
+}
+</pre>
+
+ Which, when plotted, results in:
+ 
+
+ <img src="../../../../graphs/lgamma.png" alt="lgamma">
+ 
+<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>
+
+ 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.
+ 
+
+ 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.
+ 
+
+ To start with then, here's the function object that creates the test data:
+ 
+<pre class="programlisting">
+#include <boost/math/tools/ntl.hpp>
+#include <boost/math/special_functions/gamma.hpp>
+#include <boost/math/tools/test_data.hpp>
+#include <fstream>
+
+#include <boost/math/tools/test_data.hpp>
+
+using namespace boost::math::tools;
+
+struct beta_data_generator
+{
+ NTL::RR operator()(NTL::RR a, NTL::RR b)
+ {
+ //
+ // If we throw a domain error then test_data will
+ // ignore this input point. We'll use this to filter
+ // out all cases where a // is symmetrical in a and b:
+ //
+ if(a < b)
+ throw std::domain_error("");
+
+ // very naively calculate spots with lgamma:
+ NTL::RR g1, g2, g3;
+ int s1, s2, s3;
+ g1 = boost::math::lgamma(a, &s1);
+ g2 = boost::math::lgamma(b, &s2);
+ g3 = boost::math::lgamma(a+b, &s3);
+ g1 += g2 - g3;
+ g1 = exp(g1);
+ g1 *= s1 * s2 * s3;
+ return g1;
+ }
+};
+</pre>
+
+ 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">get_user_parameter_info</code>
+ is designed for just that purpose. The start of main will look something
+ like:
+ 
+<pre class="programlisting">
+// Set the precision on RR:
+NTL::RR::SetPrecision(1000); // bits.
+NTL::RR::SetOutputPrecision(40); // decimal digits.
+
+parameter_info<NTL::RR> arg1, arg2;
+test_data<NTL::RR> data;
+
+std::cout << "Welcome.\n"
+ "This program will generate spot tests for the beta function:\n"
+ " beta(a, b)\n\n";
+
+bool cont;
+std::string line;
+
+do{
+ // prompt the user for the domain of a and b to test:
+ get_user_parameter_info(arg1, "a");
+ get_user_parameter_info(arg2, "b");
+
+ // create the data:
+ data.insert(beta_data_generator(), arg1, arg2);
+
+ // see if the user want's any more domains tested:
+ std::cout << "Any more data [y/n]?";
+ std::getline(std::cin, line);
+ boost::algorithm::trim(line);
+ cont = (line == "y");
+}while(cont);
+</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">
+ At this point one potential stumbling block should be mentioned: test_data<>::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 million test points in total. Don't
+ say you weren't warned!
+ </td></tr>
+</table></div>
+
+ There's just one final step now, and that's to write the test data to file:
+ 
+<pre class="programlisting">
+std::cout << "Enter name of test data file [default=beta_data.ipp]";
+std::getline(std::cin, line);
+boost::algorithm::trim(line);
+if(line == "")
+ line = "beta_data.ipp";
+std::ofstream ofs(line.c_str());
+write_code(ofs, data, "beta_data");
+</pre>
+
+ The format of the test data looks something like:
+ 
+<pre class="programlisting">
+#define SC_(x) static_cast<T>(BOOST_JOIN(x, L))
+ static const boost::array<boost::array<T, 3>, 1830>
+ beta_med_data = {
+ SC_(0.4883005917072296142578125),
+ SC_(0.4883005917072296142578125),
+ SC_(3.245912809500479157065104747353807392371),
+ SC_(3.5808107852935791015625),
+ SC_(0.4883005917072296142578125),
+ SC_(1.007653173802923954909901438393379243537),
+ /* ... lots of rows skipped */
+};
+</pre>
+
+ 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.
+ 
+
+ The first #define serves two purposes:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ It reduces the file sizes considerably: all those <code class="computeroutput">static_cast</code>'s
+ add up to a lot of bytes otherwise (they are needed to suppress compiler
+ warnings when <code class="computeroutput">T</code> is narrower
+ than a <code class="computeroutput">long double</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">long
+ double</code> we could change it to:
+ </li>
+</ul></div>
+
+ <code class="literal">#define SC_(x) lexical_cast<T>(BOOST_STRINGIZE(x))</code>
+ 
+
+ in order to ensure that no truncation of the values occurs prior to conversion
+ to <code class="computeroutput">T</code>. Note that this isn't
+ used by default as it's rather hard on the compiler when the table is large.
+ 
+<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>
+
+ 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
+ aN and bN of the continued fraction each time it's invoked:
+ 
+<pre class="programlisting">
+template <class T>
+struct upper_incomplete_gamma_fract
+{
+private:
+ T z, a;
+ int k;
+public:
+ typedef std::pair<T,T> result_type;
+
+ upper_incomplete_gamma_fract(T a1, T z1)
+ : z(z1-a1+1), a(a1), k(0)
+ {
+ }
+
+ result_type operator()()
+ {
+ ++k;
+ z += 2;
+ return result_type(k * (a - k), z);
+ }
+};
+</pre>
+
+ 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):
+ 
+<pre class="programlisting">
+#include <boost/math/tools/test_data.hpp>
+#include <boost/math/tools/test.hpp>
+#include <boost/math/special_functions/gamma.hpp>
+#include <boost/math/tools/ntl.hpp>
+#include <boost/tr1/tuple.hpp>
+
+template <class T>
+struct profile_gamma_fraction
+{
+ typedef std::tr1::tuple<T, T> result_type;
+
+ result_type operator()(T val)
+ {
+ using namespace boost::math::tools;
+ // estimate the true value, using arbitary precision
+ // arithmetic and NTL::RR:
+ NTL::RR rval(val);
+ upper_incomplete_gamma_fract<NTL::RR> f1(rval, rval);
+ NTL::RR true_val = continued_fraction_a(f1, 1000);
+ //
+ // Now get the aproximation at double precision, along with the number of
+ // iterations required:
+ boost::uintmax_t iters = std::numeric_limits<boost::uintmax_t>::max();
+ upper_incomplete_gamma_fract<T> f2(val, val);
+ T found_val = continued_fraction_a(f2, std::numeric_limits<T>::digits, iters);
+ //
+ // Work out the relative error, as measured in units of epsilon:
+ T err = real_cast<T>(relative_error(true_val, NTL::RR(found_val)) / std::numeric_limits<T>::epsilon());
+ //
+ // now just return the results as a tuple:
+ return std::tr1::make_tuple(err, iters);
+ }
+};
+</pre>
+
+ Feeding that functor into test_data allows rapid output of csv data, for
+ whatever type <code class="computeroutput">T</code> we may
+ be interested in:
+ 
+<pre class="programlisting">
+int main()
+{
+ using namespace boost::math::tools;
+ // create an object to hold the data:
+ test_data<double> data;
+ // insert 500 points at uniform intervals between just after 0 and 100:
+ data.insert(profile_gamma_fraction<double>(), make_periodic_param(0.01, 100.0, 100));
+ // print out in csv format:
+ write_csv(std::cout, data, ", ");
+ return 0;
+}
+</pre>
+
+ This time there's no need to plot a graph, the first few rows are:
+ 
+<pre class="programlisting">
+a and z, Error/epsilon, Iterations required
+
+0.01, 9723.14, 4726
+1.0099, 9.54818, 87
+2.0098, 3.84777, 40
+3.0097, 0.728358, 25
+4.0096, 2.39712, 21
+5.0095, 0.233263, 16
+</pre>
+
+ So it's pretty clear that this fraction shouldn't be used for small values
+ of a and z.
+ 
+<a name="math_toolkit.toolkit.internals2.test_data.reference"></a><h5>
+<a name="id732799"></a>
+ reference
+ </h5>
+<a name="test_data_reference"></a>
+ 
+
+ Most of this tool has been described already in the examples above, we'll
+ just add the following notes on the non-member functions:
+ 
+<pre class="programlisting">
+template <class T>
+parameter_info<T> make_random_param(T start_range, T end_range, int n_points);
+</pre>
+
+ Tells class test_data to test n_points random values
+ in the range [start_range,end_range].
+ 
+<pre class="programlisting">
+template <class T>
+parameter_info<T> make_periodic_param(T start_range, T end_range, int n_points);
+</pre>
+
+ Tells class test_data to test n_points evenly spaced
+ values in the range [start_range,end_range].
+ 
+<pre class="programlisting">
+template <class T>
+parameter_info<T> make_power_param(T basis, int start_exponent, int end_exponent);
+</pre>
+
+ Tells class test_data to test points of the form basis + R *
+ 2expon for each expon in the range [start_exponent,
+ end_exponent], and R a random number in [0.5, 1].
+ 
+<pre class="programlisting">
+template <class T>
+bool get_user_parameter_info(parameter_info<T>& info, const char* param_name);
+</pre>
+
+ Prompts the user for the parameter range and form to use.
+ 
+
+ 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":
+ 
+<pre class="programlisting">
+parameter_info<double> p = make_random_param(2.0, 5.0, 10);
+p.type |= dummy_param;
+</pre>
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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 do not have stable interfaces.
+ 
+
+ There is no doubt that these components can be improved, but they are also
+ largely incidental to the main purpose of this library.
+ 
+
+ 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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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><a href="using_udt/use_ntl.html"> Using With NTL - a High-Precision
+ Floating-Point Library</a></dt>
+<dt><a href="using_udt/concepts.html"> Conceptual Requirements
+ for Real Number Types</a></dt>
+<dt><a href="using_udt/dist_concept.html"> Conceptual Requirements
+ for Distribution Types</a></dt>
+<dt><a href="using_udt/archetypes.html"> Conceptual Archetypes
+ and Testing</a></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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ There are several concept archetypes available:
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/concepts/std_real_concept.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{
+namespace math{
+namespace concepts{
+
+class std_real_concept;
+
+}}} // namespaces
+</pre>
+
+ <code class="computeroutput">std_real_concept</code> is an archetype
+ for the built-in Real types.
+ 
+
+ 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.
+ 
+
+ In order to ensure that a call to say <code class="computeroutput">pow</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.
+ 
+
+ 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 only compile if the all the standard
+ library functions used have been brought into the current scope with a using
+ declaration.
+ 
+
+ 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">std_real_concept</code> to verify it's usage of
+ standard library functions.
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/concepts/real_concept.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{
+namespace math{
+namespace concepts{
+
+class real_concept;
+
+}}} // namespaces
+</pre>
+
+ <code class="computeroutput">real_concept</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<> support
+ for this type, since this is not a conceptual requirement for RealType's.
+ 
+
+ 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>.
+ 
+
+ There is no specific test case for type <code class="computeroutput">real_concept</code>,
+ instead, since this type is usable at runtime, each individual test case
+ as well as testing <code class="computeroutput">float</code>, <code class="computeroutput">double</code> and <code class="computeroutput">long
+ double</code>, also tests <code class="computeroutput">real_concept</code>.
+ 
+
+
+
+<pre class="programlisting">
+#include <boost/math/concepts/distribution.hpp></pre>
+
+ 
+<pre class="programlisting">
+namespace boost{
+namespace math{
+namespace concepts{
+
+template <class RealType>
+class distribution_archetype;
+
+template <class Distribution>
+struct DistributionConcept;
+
+}}} // namespaces
+</pre>
+
+ The class template <code class="computeroutput">distribution_archetype</code>
+ is a model of the <a href="dist_concept.html" title="Conceptual Requirements for Distribution Types">Distribution
+ concept</a>.
+ 
+
+ The class template <code class="computeroutput">DistributionConcept</code>
+ is a <a href="../../../../../../../libs/concept_check/index.html" target="_top">concept checking
+ class</a> for distribution types.
+ 
+
+ The test program distribution_concept_check.cpp
+ is responsible for using <code class="computeroutput">DistributionConcept</code>
+ to verify that all the distributions in this library conform to the Distribution concept.
+ 
+
+ The class template <code class="computeroutput">DistributionConcept</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
+ 
+
+ v = pdf(dist, x); // (Result v is ignored).
+ 
+
+ 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.)
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ The functions, and statistical distributions in this library can be used
+ with any type RealType 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!
+ 
+
+ The guiding principal behind these requirements, is that a RealType
+ behaves just like a built in floating point type.
+ 
+<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>
+
+ These requirements are common to all of the functions in this library.
+ 
+
+ In the following table r is an object of type <code class="computeroutput">RealType</code>, cr and
+ cr2 are objects of type <code class="computeroutput">const
+ RealType</code>, and ca
+ is an object of type <code class="computeroutput">const arithmetic-type</code> (arithmetic types include all the
+ built in integers and floating point types).
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Expression
+ 
+ </th>
+<th>
+ 
+ Result Type
+ 
+ </th>
+<th>
+ 
+ Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ <code class="computeroutput">RealType(cr)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ RealType is copy constructible.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">RealType(ca)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ RealType is copy constructible from the arithmetic types.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">r =
+ cr</code>
+ 
+ </td>
+<td>
+ 
+ RealType&
+ 
+ </td>
+<td>
+ 
+ Assignment operator.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">r =
+ ca</code>
+ 
+ </td>
+<td>
+ 
+ RealType&
+ 
+ </td>
+<td>
+ 
+ Assignment operator from the arithmetic types.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">r +=
+ cr</code>
+ 
+ </td>
+<td>
+ 
+ RealType&
+ 
+ </td>
+<td>
+ 
+ Adds cr to r.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">r +=
+ ca</code>
+ 
+ </td>
+<td>
+ 
+ RealType&
+ 
+ </td>
+<td>
+ 
+ Adds ar to r.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">r -=
+ cr</code>
+ 
+ </td>
+<td>
+ 
+ RealType&
+ 
+ </td>
+<td>
+ 
+ Subtracts cr from r.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">r -=
+ ca</code>
+ 
+ </td>
+<td>
+ 
+ RealType&
+ 
+ </td>
+<td>
+ 
+ Subtracts ca from r.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">r *=
+ cr</code>
+ 
+ </td>
+<td>
+ 
+ RealType&
+ 
+ </td>
+<td>
+ 
+ Multiplies r by cr.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">r *=
+ ca</code>
+ 
+ </td>
+<td>
+ 
+ RealType&
+ 
+ </td>
+<td>
+ 
+ Multiplies r by ca.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">r /=
+ cr</code>
+ 
+ </td>
+<td>
+ 
+ RealType&
+ 
+ </td>
+<td>
+ 
+ Divides r by cr.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">r /=
+ ca</code>
+ 
+ </td>
+<td>
+ 
+ RealType&
+ 
+ </td>
+<td>
+ 
+ Divides r by ca.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">-r</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Unary Negation.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">+r</code>
+ 
+ </td>
+<td>
+ 
+ RealType&
+ 
+ </td>
+<td>
+ 
+ Identity Operation.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr +
+ cr2</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Binary Addition
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr +
+ ca</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Binary Addition
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">ca +
+ cr</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Binary Addition
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr -
+ cr2</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Binary Subtraction
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr -
+ ca</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Binary Subtraction
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">ca -
+ cr</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Binary Subtraction
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr *
+ cr2</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Binary Multiplication
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr *
+ ca</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Binary Multiplication
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">ca *
+ cr</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Binary Multiplication
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr /
+ cr2</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Binary Subtraction
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr /
+ ca</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Binary Subtraction
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">ca /
+ cr</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Binary Subtraction
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr ==
+ cr2</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Equality Comparison
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr ==
+ ca</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Equality Comparison
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">ca ==
+ cr</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Equality Comparison
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr !=
+ cr2</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Inequality Comparison
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr !=
+ ca</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Inequality Comparison
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">ca !=
+ cr</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Inequality Comparison
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr <=
+ cr2</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Less than equal to.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr <=
+ ca</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Less than equal to.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">ca <=
+ cr</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Less than equal to.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr >=
+ cr2</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Greater than equal to.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr >=
+ ca</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Greater than equal to.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">ca >=
+ cr</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Greater than equal to.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr <
+ cr2</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Less than comparison.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr <
+ ca</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Less than comparison.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">ca <
+ cr</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Less than comparison.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr >
+ cr2</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Greater than comparison.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cr >
+ ca</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Greater than comparison.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">ca >
+ cr</code>
+ 
+ </td>
+<td>
+ 
+ bool
+ 
+ </td>
+<td>
+ 
+ Greater than comparison.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">boost::math::tools::digits<RealType>()</code>
+ 
+ </td>
+<td>
+ 
+ int
+ 
+ </td>
+<td>
+ 
+ The number of digits in the significand of RealType.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">boost::math::tools::max_value<RealType>()</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ The largest representable number by type RealType.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">boost::math::tools::min_value<RealType>()</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ The smallest representable number by type RealType.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">boost::math::tools::log_max_value<RealType>()</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ The natural logarithm of the largest representable number by type
+ RealType.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">boost::math::tools::log_min_value<RealType>()</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ The natural logarithm of the smallest representable number by type
+ RealType.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">boost::math::tools::epsilon<RealType>()</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ The machine epsilon of RealType.
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+
+ Note that:
+ 
+<div class="orderedlist"><ol type="1">
+<li>
+ The functions <code class="computeroutput">log_max_value</code>
+ and <code class="computeroutput">log_min_value</code> can be
+ synthesised from the others, and so no explicit specialisation is required.
+ </li>
+<li>
+ The function <code class="computeroutput">epsilon</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">digits</code>,
+ <code class="computeroutput">max_value</code> and <code class="computeroutput">min_value</code>, all get synthesised automatically
+ from <code class="computeroutput">std::numeric_limits</code>. However, if <code class="computeroutput">numeric_limits</code> is not specialised for
+ type RealType, then you will get a compiler error when code tries to use
+ these functions, unless you explicitly specialise
+ them. For example if the precision of RealType varies at runtime, then
+ <code class="computeroutput">numeric_limits</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">
+
+ If <code class="computeroutput">std::numeric_limits<></code>
+ is not specialized for type RealType
+ then the default float precision of 6 decimal digits will be used by other
+ Boost programs including:
+ 
+
+ Boost.Test: giving misleading error messages like
+ 
+
+ "difference between {9.79796} and {9.79796} exceeds 5.42101e-19%".
+ 
+
+ Boost.LexicalCast and Boost.Serialization when converting the number to
+ a string, causing potentially serious loss of accuracy on output.
+ 
+
+ Although it might seem obvious that RealType should require <code class="computeroutput">std::numeric_limits</code> to be specialized, this
+ is not sensible for <code class="computeroutput">NTL::RR</code>
+ and similar classes where the number of digits is a runtime parameter (where
+ as for <code class="computeroutput">numeric_limits</code> it
+ has to be fixed at compile time).
+ 
+</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>
+
+ 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!
+ 
+
+ In the following table r is an object of type <code class="computeroutput">RealType</code>, cr1 and
+ cr2 are objects of type <code class="computeroutput">const
+ RealType</code>, and i
+ is an object of type <code class="computeroutput">int</code>.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Expression
+ 
+ </th>
+<th>
+ 
+ Result Type
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ <code class="computeroutput">fabs(cr1)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">abs(cr1)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">ceil(cr1)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">floor(cr1)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">exp(cr1)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">pow(cr1,
+ cr2)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">sqrt(cr1)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">log(cr1)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">frexp(cr1,
+ &i)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">ldexp(cr1,
+ i)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">cos(cr1)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">sin(cr1)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">asin(cr1)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">tan(cr1)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">atan(cr1)</code>
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+
+ 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">acos</code>,
+ <code class="computeroutput">atan2</code>, <code class="computeroutput">fmod</code>,
+ <code class="computeroutput">cosh</code>, <code class="computeroutput">sinh</code>,
+ <code class="computeroutput">tanh</code>, <code class="computeroutput">modf</code>
+ and <code class="computeroutput">log10</code> are not currently
+ used, but may be if further special functions are added.
+ 
+
+ 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
+ strings (in order to ensure the coefficients aren't
+ truncated to long double) and then specialise <code class="computeroutput">lanczos_traits</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.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ A DistributionType is a type that implements the following
+ conceptual requirements, and encapsulates a statistical distribution.
+ 
+
+ Please note that this documentation should not be used as a substitute for
+ the reference documentation,
+ and tutorial of the statistical
+ distributions.
+ 
+
+ In the following table, d is an object of type <code class="computeroutput">DistributionType</code>, cd
+ is an object of type <code class="computeroutput">const DistributionType</code> and cr
+ is an object of a type convertible to <code class="computeroutput">RealType</code>.
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Expression
+ 
+ </th>
+<th>
+ 
+ Result Type
+ 
+ </th>
+<th>
+ 
+ Notes
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ DistributionType::value_type
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ The real-number type RealType upon which the
+ distribution operates.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ DistributionType::policy_type
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ The Policy to use when
+ evaluating functions that depend on this distribution.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ d = cd
+ 
+ </td>
+<td>
+ 
+ Distribution&
+ 
+ </td>
+<td>
+ 
+ Distribution types are assignable.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Distribution(cd)
+ 
+ </td>
+<td>
+ 
+ Distribution
+ 
+ </td>
+<td>
+ 
+ Distribution types are copy constructible.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ pdf(cd, cr)
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Returns the PDF of the distribution.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf(cd, cr)
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Returns the CDF of the distribution.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ cdf(complement(cd, cr))
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Returns the complement of the CDF of the distribution, the same as:
+ <code class="computeroutput">1-cdf(cd, cr)</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile(cd, cr)
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Returns the quantile of the distribution.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ quantile(complement(cd, cr))
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Returns the quantile of the distribution, starting from the complement
+ of the probability, the same as: <code class="computeroutput">quantile(cd, 1-cr)</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ chf(cd, cr)
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Returns the cumulative hazard function of the distribution.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ hazard(cd, cr)
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Returns the hazard function of the distribution.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis(cd)
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Returns the kurtosis of the distribution.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ kurtosis_excess(cd)
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Returns the kurtosis excess of the distribution.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mean(cd)
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Returns the mean of the distribution.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ mode(cd)
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Returns the mode of the distribution.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ skewness(cd)
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Returns the skewness of the distribution.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ standard_deviation(cd)
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Returns the standard deviation of the distribution.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ variance(cd)
+ 
+ </td>
+<td>
+ 
+ RealType
+ 
+ </td>
+<td>
+ 
+ Returns the variance of the distribution.
+ 
+ </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">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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>
+
+ 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>
+ 
+
+ Unfortunately <code class="computeroutput">NTL::RR</code> doesn't quite satisfy our conceptual
+ requirements, so there is a very thin wrapper class <code class="computeroutput">boost::math::ntl::RR</code> defined in boost/math/bindings/rr.hpp
+ that you should use in place of <code class="computeroutput">NTL::RR</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.
+ 
+
+ 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">boost::math::ntl::RR</code>, used at 1000-bit precision in libs/math/tools/ntl_rr_lanczos.hpp.
+ The approximation has a theoretical precision of > 90 decimal digits,
+ and an experimental precision of > 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).
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2006 -2007 John Maddock, Paul A. Bristow, Hubert Holin
+ and Xiaogang Zhang</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.

Next message: anthony_at_[hidden]: "[Boost-commit] svn:boost r39836 - trunk/boost/thread/pthread"
Previous message: john_at_[hidden]: "[Boost-commit] svn:boost r39834 - in trunk/boost/math: concepts special_functions tools"

Date view	Thread view	Subject view	Author view