libs/math/doc/sf_and_dist/beta.qbk

   1 [section:beta_function Beta]
   2
   3 [h4 Synopsis]
   4
   5 ``
   6 #include <boost/math/special_functions/beta.hpp>
   7 ``
   8
   9    namespace boost{ namespace math{
  10
  11    template <class T1, class T2>
  12    ``__sf_result`` beta(T1 a, T2 b);
  13
  14    template <class T1, class T2, class ``__Policy``>
  15    ``__sf_result`` beta(T1 a, T2 b, const ``__Policy``&);
  16
  17    }} // namespaces
  18
  19 [h4 Description]
  20
  21 The beta function is defined by:
  22
  23 [equation beta1]
  24
  25 [graph beta]
  26
  27 [optional_policy]
  28
  29 There are effectively two versions of this function internally: a fully
  30 generic version that is slow, but reasonably accurate, and a much more
  31 efficient approximation that is used where the number of digits in the significand
  32 of T correspond to a certain __lanczos.  In practice any built-in
  33 floating-point type you will encounter has an appropriate __lanczos
  34 defined for it.  It is also possible, given enough machine time, to generate
  35 further __lanczos's using the program libs/math/tools/lanczos_generator.cpp.
  36
  37 The return type of these functions is computed using the __arg_pomotion_rules
  38 when T1 and T2 are different types.
  39
  40 [h4 Accuracy]
  41
  42 The following table shows peak errors for various domains of input arguments,
  43 along with comparisons to the __gsl and __cephes libraries.  Note that
  44 only results for the widest floating point type on the system are given as
  45 narrower types have __zero_error.
  46
  47 [table Peak Errors In the Beta Function
  48 [[Significand Size] [Platform and Compiler] [Errors in range
  49
  50 0.4 < a,b < 100]  [Errors in range
  51
  52 1e-6 < a,b < 36]]
  53 [[53] [Win32, Visual C++ 8] [Peak=99 Mean=22
  54
  55 (GSL Peak=1178 Mean=238)
  56
  57 (__cephes=1612)]  [Peak=10.7 Mean=2.6
  58
  59 (GSL Peak=12 Mean=2.0)
  60
  61 (__cephes=174)]]
  62 [[64] [Red Hat Linux IA32, g++ 3.4.4] [Peak=112.1 Mean=26.9]  [Peak=15.8 Mean=3.6]]
  63 [[64] [Red Hat Linux IA64, g++ 3.4.4] [Peak=61.4 Mean=19.5]  [Peak=12.2 Mean=3.6]]
  64 [[113] [HPUX IA64, aCC A.06.06] [Peak=42.03 Mean=13.94]  [Peak=9.8 Mean=3.1]]
  65 ]
  66
  67 Note that the worst errors occur when a or b are large, and that
  68 when this is the case the result is very close to zero, so absolute
  69 errors will be very small.
  70
  71 [h4 Testing]
  72
  73 A mixture of spot tests of exact values, and randomly generated test data are
  74 used: the test data was computed using
  75 [@http://shoup.net/ntl/doc/RR.txt NTL::RR] at 1000-bit precision.
  76
  77 [h4 Implementation]
  78
  79 Traditional methods of evaluating the beta function either involve evaluating
  80 the gamma functions directly, or taking logarithms and then
  81 exponentiating the result.  However, the former is prone to overflows
  82 for even very modest arguments, while the latter is prone to cancellation
  83 errors.  As an alternative, if we regard the gamma function as a white-box
  84 containing the __lanczos, then we can combine the power terms:
  85
  86 [equation beta2]
  87
  88 which is almost the ideal solution, however almost all of the error occurs
  89 in evaluating the power terms when /a/ or /b/ are large.  If we assume that /a > b/
  90 then the larger of the two power terms can be reduced by a factor of /b/, which
  91 immediately cuts the maximum error in half:
  92
  93 [equation beta3]
  94
  95 This may not be the final solution, but it is very competitive compared to
  96 other implementation methods.
  97
  98 The generic implementation - where no __lanczos approximation is available - is
  99 implemented in a very similar way to the generic version of the gamma function.
 100 Again in order to avoid numerical overflow the power terms that prefix the series and
 101 continued fraction parts are collected together into:
 102
 103 [equation beta8]
 104
 105 where la, lb and lc are the integration limits used for a, b, and a+b.
 106
 107 There are a few special cases worth mentioning:
 108
 109 When /a/ or /b/ are less than one, we can use the recurrence relations:
 110
 111 [equation beta4]
 112
 113 [equation beta5]
 114
 115 to move to a more favorable region where they are both greater than 1.
 116
 117 In addition:
 118
 119 [equation beta7]
 120
 121 [endsect][/section:beta_function The Beta Function]
 122 [/
 123   Copyright 2006 John Maddock and Paul A. Bristow.
 124   Distributed under the Boost Software License, Version 1.0.
 125   (See accompanying file LICENSE_1_0.txt or copy at
 126   http://www.boost.org/LICENSE_1_0.txt).
 127 ]
 128