ceph/src/boost/libs/math/doc/html/math_toolkit/sf_beta/beta_function.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Beta</title>
   5 <link rel="stylesheet" href="../../math.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
   7 <link rel="home" href="../../index.html" title="Math Toolkit 2.5.1">
   8 <link rel="up" href="../sf_beta.html" title="Beta Functions">
   9 <link rel="prev" href="../sf_beta.html" title="Beta Functions">
  10 <link rel="next" href="ibeta_function.html" title="Incomplete Beta Functions">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="../sf_beta.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_beta.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="ibeta_function.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="math_toolkit.sf_beta.beta_function"></a><a class="link" href="beta_function.html" title="Beta">Beta</a>
  28 </h3></div></div></div>
  29 <h5>
  30 <a name="math_toolkit.sf_beta.beta_function.h0"></a>
  31         <span class="phrase"><a name="math_toolkit.sf_beta.beta_function.synopsis"></a></span><a class="link" href="beta_function.html#math_toolkit.sf_beta.beta_function.synopsis">Synopsis</a>
  32       </h5>
  33 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">beta</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  34 </pre>
  35 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
  36
  37 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">&gt;</span>
  38 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">beta</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">);</span>
  39
  40 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&gt;</span>
  41 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">beta</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">b</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&amp;);</span>
  42
  43 <span class="special">}}</span> <span class="comment">// namespaces</span>
  44 </pre>
  45 <h5>
  46 <a name="math_toolkit.sf_beta.beta_function.h1"></a>
  47         <span class="phrase"><a name="math_toolkit.sf_beta.beta_function.description"></a></span><a class="link" href="beta_function.html#math_toolkit.sf_beta.beta_function.description">Description</a>
  48       </h5>
  49 <p>
  50         The beta function is defined by:
  51       </p>
  52 <p>
  53         <span class="inlinemediaobject"><img src="../../../equations/beta1.svg"></span>
  54       </p>
  55 <p>
  56         <span class="inlinemediaobject"><img src="../../../graphs/beta.svg" align="middle"></span>
  57       </p>
  58 <p>
  59         The final <a class="link" href="../../policy.html" title="Chapter&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can
  60         be used to control the behaviour of the function: how it handles errors,
  61         what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">policy
  62         documentation for more details</a>.
  63       </p>
  64 <p>
  65         There are effectively two versions of this function internally: a fully generic
  66         version that is slow, but reasonably accurate, and a much more efficient
  67         approximation that is used where the number of digits in the significand
  68         of T correspond to a certain <a class="link" href="../lanczos.html" title="The Lanczos Approximation">Lanczos
  69         approximation</a>. In practice any built-in floating-point type you will
  70         encounter has an appropriate <a class="link" href="../lanczos.html" title="The Lanczos Approximation">Lanczos
  71         approximation</a> defined for it. It is also possible, given enough machine
  72         time, to generate further <a class="link" href="../lanczos.html" title="The Lanczos Approximation">Lanczos approximation</a>'s
  73         using the program libs/math/tools/lanczos_generator.cpp.
  74       </p>
  75 <p>
  76         The return type of these functions is computed using the <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
  77         type calculation rules</em></span></a> when T1 and T2 are different types.
  78       </p>
  79 <h5>
  80 <a name="math_toolkit.sf_beta.beta_function.h2"></a>
  81         <span class="phrase"><a name="math_toolkit.sf_beta.beta_function.accuracy"></a></span><a class="link" href="beta_function.html#math_toolkit.sf_beta.beta_function.accuracy">Accuracy</a>
  82       </h5>
  83 <p>
  84         The following table shows peak errors for various domains of input arguments,
  85         along with comparisons to the <a href="http://www.gnu.org/software/gsl/" target="_top">GSL-1.9</a>
  86         and <a href="http://www.netlib.org/cephes/" target="_top">Cephes</a> libraries.
  87         Note that only results for the widest floating point type on the system are
  88         given as narrower types have <a class="link" href="../relative_error.html#math_toolkit.relative_error.zero_error">effectively
  89         zero error</a>.
  90       </p>
  91 <div class="table">
  92 <a name="math_toolkit.sf_beta.beta_function.table_beta"></a><p class="title"><b>Table&#160;6.17.&#160;Error rates for beta</b></p>
  93 <div class="table-contents"><table class="table" summary="Error rates for beta">
  94 <colgroup>
  95 <col>
  96 <col>
  97 <col>
  98 <col>
  99 <col>
 100 </colgroup>
 101 <thead><tr>
 102 <th>
 103               </th>
 104 <th>
 105                 <p>
 106                   Microsoft Visual C++ version 12.0<br> Win32<br> double
 107                 </p>
 108               </th>
 109 <th>
 110                 <p>
 111                   GNU C++ version 5.1.0<br> linux<br> long double
 112                 </p>
 113               </th>
 114 <th>
 115                 <p>
 116                   GNU C++ version 5.1.0<br> linux<br> double
 117                 </p>
 118               </th>
 119 <th>
 120                 <p>
 121                   Sun compiler version 0x5130<br> Sun Solaris<br> long double
 122                 </p>
 123               </th>
 124 </tr></thead>
 125 <tbody>
 126 <tr>
 127 <td>
 128                 <p>
 129                   Beta Function: Small Values
 130                 </p>
 131               </td>
 132 <td>
 133                 <p>
 134                   <span class="blue">Max = 1.75&#949; (Mean = 0.828&#949;)</span>
 135                 </p>
 136               </td>
 137 <td>
 138                 <p>
 139                   <span class="blue">Max = 2.65&#949; (Mean = 1.22&#949;)</span><br> <br>
 140                   (<span class="emphasis"><em>&lt;tr1/cmath&gt;:</em></span> Max = 11.9&#949; (Mean = 7.03&#949;))
 141                 </p>
 142               </td>
 143 <td>
 144                 <p>
 145                   <span class="blue">Max = 0&#949; (Mean = 0&#949;)</span><br> <br> (<span class="emphasis"><em>GSL
 146                   1.16:</em></span> Max = 3.94&#949; (Mean = 1.44&#949;))<br> (<span class="emphasis"><em>Rmath
 147                   3.0.2:</em></span> Max = 1.14&#949; (Mean = 0.601&#949;))<br> (<span class="emphasis"><em>Cephes:</em></span>
 148                   Max = 1.97&#949; (Mean = 0.934&#949;))
 149                 </p>
 150               </td>
 151 <td>
 152                 <p>
 153                   <span class="blue">Max = 2.86&#949; (Mean = 1.31&#949;)</span>
 154                 </p>
 155               </td>
 156 </tr>
 157 <tr>
 158 <td>
 159                 <p>
 160                   Beta Function: Medium Values
 161                 </p>
 162               </td>
 163 <td>
 164                 <p>
 165                   <span class="blue">Max = 99.1&#949; (Mean = 22.4&#949;)</span>
 166                 </p>
 167               </td>
 168 <td>
 169                 <p>
 170                   <span class="blue">Max = 60.4&#949; (Mean = 19.4&#949;)</span><br> <br>
 171                   (<span class="emphasis"><em>&lt;tr1/cmath&gt;:</em></span> Max = 1.07e+03&#949; (Mean =
 172                   264&#949;))
 173                 </p>
 174               </td>
 175 <td>
 176                 <p>
 177                   <span class="blue">Max = 0.978&#949; (Mean = 0.0578&#949;)</span><br>
 178                   <br> (<span class="emphasis"><em>GSL 1.16:</em></span> Max = 1.18e+03&#949; (Mean = 238&#949;))<br>
 179                   (<span class="emphasis"><em>Rmath 3.0.2:</em></span> Max = 1.09e+03&#949; (Mean = 265&#949;))<br>
 180                   (<span class="emphasis"><em>Cephes:</em></span> Max = 1.5e+03&#949; (Mean = 329&#949;))
 181                 </p>
 182               </td>
 183 <td>
 184                 <p>
 185                   <span class="blue">Max = 107&#949; (Mean = 24.5&#949;)</span>
 186                 </p>
 187               </td>
 188 </tr>
 189 <tr>
 190 <td>
 191                 <p>
 192                   Beta Function: Divergent Values
 193                 </p>
 194               </td>
 195 <td>
 196                 <p>
 197                   <span class="blue">Max = 10.7&#949; (Mean = 2.22&#949;)</span>
 198                 </p>
 199               </td>
 200 <td>
 201                 <p>
 202                   <span class="blue">Max = 10.3&#949; (Mean = 2.41&#949;)</span><br> <br>
 203                   (<span class="emphasis"><em>&lt;tr1/cmath&gt;:</em></span> Max = 128&#949; (Mean = 23.8&#949;))
 204                 </p>
 205               </td>
 206 <td>
 207                 <p>
 208                   <span class="blue">Max = 0&#949; (Mean = 0&#949;)</span><br> <br> (<span class="emphasis"><em>GSL
 209                   1.16:</em></span> Max = 12.1&#949; (Mean = 1.99&#949;))<br> (<span class="emphasis"><em>Rmath
 210                   3.0.2:</em></span> Max = 176&#949; (Mean = 28&#949;))<br> (<span class="emphasis"><em>Cephes:</em></span>
 211                   Max = 175&#949; (Mean = 22&#949;))
 212                 </p>
 213               </td>
 214 <td>
 215                 <p>
 216                   <span class="blue">Max = 19.7&#949; (Mean = 2.75&#949;)</span>
 217                 </p>
 218               </td>
 219 </tr>
 220 </tbody>
 221 </table></div>
 222 </div>
 223 <br class="table-break"><p>
 224         Note that the worst errors occur when a or b are large, and that when this
 225         is the case the result is very close to zero, so absolute errors will be
 226         very small.
 227       </p>
 228 <h5>
 229 <a name="math_toolkit.sf_beta.beta_function.h3"></a>
 230         <span class="phrase"><a name="math_toolkit.sf_beta.beta_function.testing"></a></span><a class="link" href="beta_function.html#math_toolkit.sf_beta.beta_function.testing">Testing</a>
 231       </h5>
 232 <p>
 233         A mixture of spot tests of exact values, and randomly generated test data
 234         are used: the test data was computed using <a href="http://shoup.net/ntl/doc/RR.txt" target="_top">NTL::RR</a>
 235         at 1000-bit precision.
 236       </p>
 237 <h5>
 238 <a name="math_toolkit.sf_beta.beta_function.h4"></a>
 239         <span class="phrase"><a name="math_toolkit.sf_beta.beta_function.implementation"></a></span><a class="link" href="beta_function.html#math_toolkit.sf_beta.beta_function.implementation">Implementation</a>
 240       </h5>
 241 <p>
 242         Traditional methods of evaluating the beta function either involve evaluating
 243         the gamma functions directly, or taking logarithms and then exponentiating
 244         the result. However, the former is prone to overflows for even very modest
 245         arguments, while the latter is prone to cancellation errors. As an alternative,
 246         if we regard the gamma function as a white-box containing the <a class="link" href="../lanczos.html" title="The Lanczos Approximation">Lanczos
 247         approximation</a>, then we can combine the power terms:
 248       </p>
 249 <p>
 250         <span class="inlinemediaobject"><img src="../../../equations/beta2.svg"></span>
 251       </p>
 252 <p>
 253         which is almost the ideal solution, however almost all of the error occurs
 254         in evaluating the power terms when <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span>
 255         are large. If we assume that <span class="emphasis"><em>a &gt; b</em></span> then the larger
 256         of the two power terms can be reduced by a factor of <span class="emphasis"><em>b</em></span>,
 257         which immediately cuts the maximum error in half:
 258       </p>
 259 <p>
 260         <span class="inlinemediaobject"><img src="../../../equations/beta3.svg"></span>
 261       </p>
 262 <p>
 263         This may not be the final solution, but it is very competitive compared to
 264         other implementation methods.
 265       </p>
 266 <p>
 267         The generic implementation - where no <a class="link" href="../lanczos.html" title="The Lanczos Approximation">Lanczos
 268         approximation</a> approximation is available - is implemented in a very
 269         similar way to the generic version of the gamma function. Again in order
 270         to avoid numerical overflow the power terms that prefix the series and continued
 271         fraction parts are collected together into:
 272       </p>
 273 <p>
 274         <span class="inlinemediaobject"><img src="../../../equations/beta8.svg"></span>
 275       </p>
 276 <p>
 277         where la, lb and lc are the integration limits used for a, b, and a+b.
 278       </p>
 279 <p>
 280         There are a few special cases worth mentioning:
 281       </p>
 282 <p>
 283         When <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span> are less than one,
 284         we can use the recurrence relations:
 285       </p>
 286 <p>
 287         <span class="inlinemediaobject"><img src="../../../equations/beta4.svg"></span>
 288       </p>
 289 <p>
 290         <span class="inlinemediaobject"><img src="../../../equations/beta5.svg"></span>
 291       </p>
 292 <p>
 293         to move to a more favorable region where they are both greater than 1.
 294       </p>
 295 <p>
 296         In addition:
 297       </p>
 298 <p>
 299         <span class="inlinemediaobject"><img src="../../../equations/beta7.svg"></span>
 300       </p>
 301 </div>
 302 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 303 <td align="left"></td>
 304 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2010, 2012-2014 Nikhar Agrawal,
 305       Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
 306       Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Johan R&#229;de, Gautam Sewani,
 307       Benjamin Sobotta, Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
 308         Distributed under the Boost Software License, Version 1.0. (See accompanying
 309         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 310       </p>
 311 </div></td>
 312 </tr></table>
 313 <hr>
 314 <div class="spirit-nav">
 315 <a accesskey="p" href="../sf_beta.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_beta.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="ibeta_function.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 316 </div>
 317 </body>
 318 </html>