<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Beta</title>
<link rel="stylesheet" href="../../../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
<link rel="home" 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"><a href="../../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<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>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="math_toolkit.special.sf_beta.beta_function"></a><a class="link" href="beta_function.html" title="Beta"> Beta</a>
</h4></div></div></div>
<a name="math_toolkit.special.sf_beta.beta_function.synopsis"></a><h5>
<a name="id1092600"></a>
<a class="link" href="beta_function.html#math_toolkit.special.sf_beta.beta_function.synopsis">Synopsis</a>
</h5>
<p>
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">beta</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
</pre>
<p>
</p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
<span class="keyword">template</span> <span class="special"><</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>
<a class="link" href="../../main_overview/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">template</span> <span class="special"><</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="Policies">Policy</a><span class="special">></span>
<a class="link" href="../../main_overview/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="Policies">Policy</a><span class="special">&);</span>
<span class="special">}}</span> <span class="comment">// namespaces
</span></pre>
<a name="math_toolkit.special.sf_beta.beta_function.description"></a><h5>
<a name="id1092880"></a>
<a class="link" href="beta_function.html#math_toolkit.special.sf_beta.beta_function.description">Description</a>
</h5>
<p>
The beta function is defined by:
</p>
<p>
<span class="inlinemediaobject"><img src="../../../../equations/beta1.png"></span>
</p>
<p>
<span class="inlinemediaobject"><img src="../../../../graphs/beta.png" align="middle"></span>
</p>
<p>
</p>
<p>
The final <a class="link" href="../../policy.html" title="Policies">Policy</a> 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
<a class="link" href="../../policy.html" title="Policies">policy documentation for more details</a>.
</p>
<p>
</p>
<p>
There are effectively two versions of this function internally: a fully
generic version that is slow, but reasonably accurate, and a much more
efficient approximation that is used where the number of digits in the
significand of T correspond to a certain <a class="link" 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 class="link" 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 class="link" href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
approximation</a>'s using the program libs/math/tools/lanczos_generator.cpp.
</p>
<p>
The return type of these functions is computed using the <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
type calculation rules</em></span></a> when T1 and T2 are different types.
</p>
<a name="math_toolkit.special.sf_beta.beta_function.accuracy"></a><h5>
<a name="id1092991"></a>
<a class="link" href="beta_function.html#math_toolkit.special.sf_beta.beta_function.accuracy">Accuracy</a>
</h5>
<p>
The following table shows peak errors for various domains of input arguments,
along with comparisons to the <a href="http://www.gnu.org/software/gsl/" target="_top">GSL-1.9</a>
and <a href="http://www.netlib.org/cephes/" target="_top">Cephes</a> libraries.
Note that only results for the widest floating point type on the system
are given as narrower types have <a class="link" href="../../backgrounders/relative_error.html#zero_error">effectively
zero error</a>.
</p>
<div class="table">
<a name="id1093019"></a><p class="title"><b>Table 22. Peak Errors In the Beta Function</b></p>
<div class="table-contents"><table class="table" summary="Peak Errors In the Beta Function">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Significand Size
</p>
</th>
<th>
<p>
Platform and Compiler
</p>
</th>
<th>
<p>
Errors in range
</p>
<p>
0.4 < a,b < 100
</p>
</th>
<th>
<p>
Errors in range
</p>
<p>
1e-6 < a,b < 36
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
53
</p>
</td>
<td>
<p>
Win32, Visual C++ 8
</p>
</td>
<td>
<p>
Peak=99 Mean=22
</p>
<p>
(GSL Peak=1178 Mean=238)
</p>
<p>
(<a href="http://www.netlib.org/cephes/" target="_top">Cephes</a>=1612)
</p>
</td>
<td>
<p>
Peak=10.7 Mean=2.6
</p>
<p>
(GSL Peak=12 Mean=2.0)
</p>
<p>
(<a href="http://www.netlib.org/cephes/" target="_top">Cephes</a>=174)
</p>
</td>
</tr>
<tr>
<td>
<p>
64
</p>
</td>
<td>
<p>
Red Hat Linux IA32, g++ 3.4.4
</p>
</td>
<td>
<p>
Peak=112.1 Mean=26.9
</p>
</td>
<td>
<p>
Peak=15.8 Mean=3.6
</p>
</td>
</tr>
<tr>
<td>
<p>
64
</p>
</td>
<td>
<p>
Red Hat Linux IA64, g++ 3.4.4
</p>
</td>
<td>
<p>
Peak=61.4 Mean=19.5
</p>
</td>
<td>
<p>
Peak=12.2 Mean=3.6
</p>
</td>
</tr>
<tr>
<td>
<p>
113
</p>
</td>
<td>
<p>
HPUX IA64, aCC A.06.06
</p>
</td>
<td>
<p>
Peak=42.03 Mean=13.94
</p>
</td>
<td>
<p>
Peak=9.8 Mean=3.1
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
Note that the worst errors occur when a or b are large, and that when this
is the case the result is very close to zero, so absolute errors will be
very small.
</p>
<a name="math_toolkit.special.sf_beta.beta_function.testing"></a><h5>
<a name="id1093254"></a>
<a class="link" href="beta_function.html#math_toolkit.special.sf_beta.beta_function.testing">Testing</a>
</h5>
<p>
A mixture of spot tests of exact values, and randomly generated test data
are used: the test data was computed using <a href="http://shoup.net/ntl/doc/RR.txt" target="_top">NTL::RR</a>
at 1000-bit precision.
</p>
<a name="math_toolkit.special.sf_beta.beta_function.implementation"></a><h5>
<a name="id1093278"></a>
<a class="link" href="beta_function.html#math_toolkit.special.sf_beta.beta_function.implementation">Implementation</a>
</h5>
<p>
Traditional methods of evaluating the beta function either involve evaluating
the gamma functions directly, or taking logarithms and then exponentiating
the result. However, the former is prone to overflows for even very modest
arguments, while the latter is prone to cancellation errors. As an alternative,
if we regard the gamma function as a white-box containing the <a class="link" href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
approximation</a>, then we can combine the power terms:
</p>
<p>
<span class="inlinemediaobject"><img src="../../../../equations/beta2.png"></span>
</p>
<p>
which is almost the ideal solution, however almost all of the error occurs
in evaluating the power terms when <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span>
are large. If we assume that <span class="emphasis"><em>a > b</em></span> then the larger
of the two power terms can be reduced by a factor of <span class="emphasis"><em>b</em></span>,
which immediately cuts the maximum error in half:
</p>
<p>
<span class="inlinemediaobject"><img src="../../../../equations/beta3.png"></span>
</p>
<p>
This may not be the final solution, but it is very competitive compared
to other implementation methods.
</p>
<p>
The generic implementation - where no <a class="link" href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
approximation</a> approximation is available - is implemented in a very
similar way to the generic version of the gamma function. Again in order
to avoid numerical overflow the power terms that prefix the series and
continued fraction parts are collected together into:
</p>
<p>
<span class="inlinemediaobject"><img src="../../../../equations/beta8.png"></span>
</p>
<p>
where la, lb and lc are the integration limits used for a, b, and a+b.
</p>
<p>
There are a few special cases worth mentioning:
</p>
<p>
When <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span> are less than one,
we can use the recurrence relations:
</p>
<p>
<span class="inlinemediaobject"><img src="../../../../equations/beta4.png"></span>
</p>
<p>
<span class="inlinemediaobject"><img src="../../../../equations/beta5.png"></span>
</p>
<p>
to move to a more favorable region where they are both greater than 1.
</p>
<p>
In addition:
</p>
<p>
<span class="inlinemediaobject"><img src="../../../../equations/beta7.png"></span>
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2006 , 2007, 2008, 2009 John Maddock, Paul A. Bristow,
Hubert Holin, Xiaogang Zhang, Bruno Lalande, Johan Råde, Gautam Sewani
and Thijs van den Berg<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<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>
</div>
</body>
</html>
