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.79.1">
   7 <link rel="home" href="../../index.html" title="Math Toolkit 2.11.0">
   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;20.&#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;20.&#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 <div class="blockquote"><blockquote class="blockquote"><p>
  53           <span class="inlinemediaobject"><img src="../../../equations/beta1.svg"></span>
  54
  55         </p></blockquote></div>
  56 <div class="blockquote"><blockquote class="blockquote"><p>
  57           <span class="inlinemediaobject"><img src="../../../graphs/beta.svg" align="middle"></span>
  58
  59         </p></blockquote></div>
  60 <p>
  61         The final <a class="link" href="../../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can
  62         be used to control the behaviour of the function: how it handles errors,
  63         what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">policy
  64         documentation for more details</a>.
  65       </p>
  66 <p>
  67         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
  68         type calculation rules</em></span></a> when T1 and T2 are different types.
  69       </p>
  70 <h5>
  71 <a name="math_toolkit.sf_beta.beta_function.h2"></a>
  72         <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>
  73       </h5>
  74 <p>
  75         The following table shows peak errors for various domains of input arguments,
  76         along with comparisons to the <a href="http://www.gnu.org/software/gsl/" target="_top">GSL-1.9</a>
  77         and <a href="http://www.netlib.org/cephes/" target="_top">Cephes</a> libraries.
  78         Note that only results for the widest floating point type on the system are
  79         given as narrower types have <a class="link" href="../relative_error.html#math_toolkit.relative_error.zero_error">effectively
  80         zero error</a>.
  81       </p>
  82 <div class="table">
  83 <a name="math_toolkit.sf_beta.beta_function.table_beta"></a><p class="title"><b>Table&#160;8.17.&#160;Error rates for beta</b></p>
  84 <div class="table-contents"><table class="table" summary="Error rates for beta">
  85 <colgroup>
  86 <col>
  87 <col>
  88 <col>
  89 <col>
  90 <col>
  91 </colgroup>
  92 <thead><tr>
  93 <th>
  94               </th>
  95 <th>
  96                 <p>
  97                   GNU C++ version 7.1.0<br> linux<br> double
  98                 </p>
  99               </th>
 100 <th>
 101                 <p>
 102                   GNU C++ version 7.1.0<br> linux<br> long double
 103                 </p>
 104               </th>
 105 <th>
 106                 <p>
 107                   Sun compiler version 0x5150<br> Sun Solaris<br> long double
 108                 </p>
 109               </th>
 110 <th>
 111                 <p>
 112                   Microsoft Visual C++ version 14.1<br> Win32<br> double
 113                 </p>
 114               </th>
 115 </tr></thead>
 116 <tbody>
 117 <tr>
 118 <td>
 119                 <p>
 120                   Beta Function: Small Values
 121                 </p>
 122               </td>
 123 <td>
 124                 <p>
 125                   <span class="blue">Max = 0&#949; (Mean = 0&#949;)</span><br> <br> (<span class="emphasis"><em>GSL
 126                   2.1:</em></span> <span class="red">Max = +INF&#949; (Mean = +INF&#949;) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_7_1_0_linux_double_beta_GSL_2_1_Beta_Function_Small_Values">And
 127                   other failures.</a>)</span><br> (<span class="emphasis"><em>Rmath 3.2.3:</em></span>
 128                   Max = 1.14&#949; (Mean = 0.574&#949;))
 129                 </p>
 130               </td>
 131 <td>
 132                 <p>
 133                   <span class="blue">Max = 2.86&#949; (Mean = 1.22&#949;)</span><br> <br>
 134                   (<span class="emphasis"><em>&lt;cmath&gt;:</em></span> Max = 364&#949; (Mean = 76.2&#949;))
 135                 </p>
 136               </td>
 137 <td>
 138                 <p>
 139                   <span class="blue">Max = 2.86&#949; (Mean = 1.22&#949;)</span>
 140                 </p>
 141               </td>
 142 <td>
 143                 <p>
 144                   <span class="blue">Max = 2.23&#949; (Mean = 1.14&#949;)</span>
 145                 </p>
 146               </td>
 147 </tr>
 148 <tr>
 149 <td>
 150                 <p>
 151                   Beta Function: Medium Values
 152                 </p>
 153               </td>
 154 <td>
 155                 <p>
 156                   <span class="blue">Max = 0.978&#949; (Mean = 0.0595&#949;)</span><br>
 157                   <br> (<span class="emphasis"><em>GSL 2.1:</em></span> Max = 1.18e+03&#949; (Mean = 238&#949;))<br>
 158                   (<span class="emphasis"><em>Rmath 3.2.3:</em></span> Max = 1.09e+03&#949; (Mean = 265&#949;))
 159                 </p>
 160               </td>
 161 <td>
 162                 <p>
 163                   <span class="blue">Max = 61.4&#949; (Mean = 19.4&#949;)</span><br> <br>
 164                   (<span class="emphasis"><em>&lt;cmath&gt;:</em></span> Max = 1.07e+03&#949; (Mean = 264&#949;))
 165                 </p>
 166               </td>
 167 <td>
 168                 <p>
 169                   <span class="blue">Max = 107&#949; (Mean = 24.5&#949;)</span>
 170                 </p>
 171               </td>
 172 <td>
 173                 <p>
 174                   <span class="blue">Max = 96.5&#949; (Mean = 22.4&#949;)</span>
 175                 </p>
 176               </td>
 177 </tr>
 178 <tr>
 179 <td>
 180                 <p>
 181                   Beta Function: Divergent Values
 182                 </p>
 183               </td>
 184 <td>
 185                 <p>
 186                   <span class="blue">Max = 0&#949; (Mean = 0&#949;)</span><br> <br> (<span class="emphasis"><em>GSL
 187                   2.1:</em></span> Max = 12.1&#949; (Mean = 1.99&#949;))<br> (<span class="emphasis"><em>Rmath
 188                   3.2.3:</em></span> Max = 176&#949; (Mean = 28&#949;))
 189                 </p>
 190               </td>
 191 <td>
 192                 <p>
 193                   <span class="blue">Max = 8.99&#949; (Mean = 2.44&#949;)</span><br> <br>
 194                   (<span class="emphasis"><em>&lt;cmath&gt;:</em></span> Max = 128&#949; (Mean = 23.8&#949;))
 195                 </p>
 196               </td>
 197 <td>
 198                 <p>
 199                   <span class="blue">Max = 18.8&#949; (Mean = 2.71&#949;)</span>
 200                 </p>
 201               </td>
 202 <td>
 203                 <p>
 204                   <span class="blue">Max = 11.4&#949; (Mean = 2.19&#949;)</span>
 205                 </p>
 206               </td>
 207 </tr>
 208 </tbody>
 209 </table></div>
 210 </div>
 211 <br class="table-break"><p>
 212         Note that the worst errors occur when a or b are large, and that when this
 213         is the case the result is very close to zero, so absolute errors will be
 214         very small.
 215       </p>
 216 <h5>
 217 <a name="math_toolkit.sf_beta.beta_function.h3"></a>
 218         <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>
 219       </h5>
 220 <p>
 221         A mixture of spot tests of exact values, and randomly generated test data
 222         are used: the test data was computed using <a href="http://shoup.net/ntl/doc/RR.txt" target="_top">NTL::RR</a>
 223         at 1000-bit precision.
 224       </p>
 225 <h5>
 226 <a name="math_toolkit.sf_beta.beta_function.h4"></a>
 227         <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>
 228       </h5>
 229 <p>
 230         Traditional methods of evaluating the beta function either involve evaluating
 231         the gamma functions directly, or taking logarithms and then exponentiating
 232         the result. However, the former is prone to overflows for even very modest
 233         arguments, while the latter is prone to cancellation errors. As an alternative,
 234         if we regard the gamma function as a white-box containing the <a class="link" href="../lanczos.html" title="The Lanczos Approximation">Lanczos
 235         approximation</a>, then we can combine the power terms:
 236       </p>
 237 <div class="blockquote"><blockquote class="blockquote"><p>
 238           <span class="inlinemediaobject"><img src="../../../equations/beta2.svg"></span>
 239
 240         </p></blockquote></div>
 241 <p>
 242         which is almost the ideal solution, however almost all of the error occurs
 243         in evaluating the power terms when <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span>
 244         are large. If we assume that <span class="emphasis"><em>a &gt; b</em></span> then the larger
 245         of the two power terms can be reduced by a factor of <span class="emphasis"><em>b</em></span>,
 246         which immediately cuts the maximum error in half:
 247       </p>
 248 <div class="blockquote"><blockquote class="blockquote"><p>
 249           <span class="inlinemediaobject"><img src="../../../equations/beta3.svg"></span>
 250
 251         </p></blockquote></div>
 252 <p>
 253         This may not be the final solution, but it is very competitive compared to
 254         other implementation methods.
 255       </p>
 256 <p>
 257         The generic implementation - where no <a class="link" href="../lanczos.html" title="The Lanczos Approximation">Lanczos
 258         approximation</a> approximation is available - is implemented in a very
 259         similar way to the generic version of the gamma function by means of Sterling's
 260         approximation. Again in order to avoid numerical overflow the power terms
 261         that prefix the series are collected together
 262       </p>
 263 <p>
 264         There are a few special cases worth mentioning:
 265       </p>
 266 <p>
 267         When <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span> are less than one,
 268         we can use the recurrence relations:
 269       </p>
 270 <div class="blockquote"><blockquote class="blockquote"><p>
 271           <span class="inlinemediaobject"><img src="../../../equations/beta4.svg"></span>
 272
 273         </p></blockquote></div>
 274 <div class="blockquote"><blockquote class="blockquote"><p>
 275           <span class="inlinemediaobject"><img src="../../../equations/beta5.svg"></span>
 276
 277         </p></blockquote></div>
 278 <p>
 279         to move to a more favorable region where they are both greater than 1.
 280       </p>
 281 <p>
 282         In addition:
 283       </p>
 284 <div class="blockquote"><blockquote class="blockquote"><p>
 285           <span class="inlinemediaobject"><img src="../../../equations/beta7.svg"></span>
 286
 287         </p></blockquote></div>
 288 </div>
 289 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 290 <td align="left"></td>
 291 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2019 Nikhar
 292       Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
 293       Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
 294       R&#229;de, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
 295       Daryle Walker and Xiaogang Zhang<p>
 296         Distributed under the Boost Software License, Version 1.0. (See accompanying
 297         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>)
 298       </p>
 299 </div></td>
 300 </tr></table>
 301 <hr>
 302 <div class="spirit-nav">
 303 <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>
 304 </div>
 305 </body>
 306 </html>