blob: 5cf52dd7da5bce656443647cde76b46d64f06127 [file] [log] [blame]
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Incomplete Gamma Function Inverses</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_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"><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="igamma.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.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="gamma_derivatives.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_gamma.igamma_inv"></a><a class="link" 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="id1081175"></a>
<a class="link" href="igamma_inv.html#math_toolkit.special.sf_gamma.igamma_inv.synopsis">Synopsis</a>
</h5>
<p>
</p>
<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">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</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">&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>
<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">gamma_q_inv</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">q</span><span class="special">);</span>
<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="Policies">Policy</a><span class="special">&gt;</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">gamma_q_inv</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">q</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">&amp;);</span>
<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>
<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">gamma_p_inv</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">p</span><span class="special">);</span>
<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="Policies">Policy</a><span class="special">&gt;</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">gamma_p_inv</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">p</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">&amp;);</span>
<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>
<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">gamma_q_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">q</span><span class="special">);</span>
<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="Policies">Policy</a><span class="special">&gt;</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">gamma_q_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">q</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">&amp;);</span>
<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>
<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">gamma_p_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">p</span><span class="special">);</span>
<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="Policies">Policy</a><span class="special">&gt;</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">gamma_p_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">&amp;);</span>
<span class="special">}}</span> <span class="comment">// namespaces
</span></pre>
<a name="math_toolkit.special.sf_gamma.igamma_inv.description"></a><h5>
<a name="id1081980"></a>
<a class="link" href="igamma_inv.html#math_toolkit.special.sf_gamma.igamma_inv.description">Description</a>
</h5>
<p>
There are four <a href="http://mathworld.wolfram.com/IncompleteGammaFunction.html" target="_top">incomplete
gamma function</a> inverses which either compute <span class="emphasis"><em>x</em></span>
given <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>p</em></span> or <span class="emphasis"><em>q</em></span>,
or else compute <span class="emphasis"><em>a</em></span> given <span class="emphasis"><em>x</em></span> and
either <span class="emphasis"><em>p</em></span> or <span class="emphasis"><em>q</em></span>.
</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,
otherwise the return type is simply T1.
</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>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top">
<p>
When people normally talk about the inverse of the incomplete gamma function,
they are talking about inverting on parameter <span class="emphasis"><em>x</em></span>.
These are implemented here as gamma_p_inv and gamma_q_inv, and are by
far the most efficient of the inverses presented here.
</p>
<p>
The inverse on the <span class="emphasis"><em>a</em></span> 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.
</p>
</td></tr>
</table></div>
<pre class="programlisting"><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>
<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">gamma_q_inv</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">q</span><span class="special">);</span>
<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="Policies">Policy</a><span class="special">&gt;</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">gamma_q_inv</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">q</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">&amp;);</span>
</pre>
<p>
Returns a value x such that: <code class="computeroutput"><span class="identifier">q</span>
<span class="special">=</span> <span class="identifier">gamma_q</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
<span class="identifier">x</span><span class="special">);</span></code>
</p>
<p>
Requires: <span class="emphasis"><em>a &gt; 0</em></span> and <span class="emphasis"><em>1 &gt;= p,q &gt;=
0</em></span>.
</p>
<pre class="programlisting"><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>
<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">gamma_p_inv</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">p</span><span class="special">);</span>
<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="Policies">Policy</a><span class="special">&gt;</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">gamma_p_inv</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">p</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">&amp;);</span>
</pre>
<p>
Returns a value x such that: <code class="computeroutput"><span class="identifier">p</span>
<span class="special">=</span> <span class="identifier">gamma_p</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
<span class="identifier">x</span><span class="special">);</span></code>
</p>
<p>
Requires: <span class="emphasis"><em>a &gt; 0</em></span> and <span class="emphasis"><em>1 &gt;= p,q &gt;=
0</em></span>.
</p>
<pre class="programlisting"><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>
<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">gamma_q_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">q</span><span class="special">);</span>
<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="Policies">Policy</a><span class="special">&gt;</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">gamma_q_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">q</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">&amp;);</span>
</pre>
<p>
Returns a value a such that: <code class="computeroutput"><span class="identifier">q</span>
<span class="special">=</span> <span class="identifier">gamma_q</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
<span class="identifier">x</span><span class="special">);</span></code>
</p>
<p>
Requires: <span class="emphasis"><em>x &gt; 0</em></span> and <span class="emphasis"><em>1 &gt;= p,q &gt;=
0</em></span>.
</p>
<pre class="programlisting"><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>
<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">gamma_p_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">p</span><span class="special">);</span>
<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="Policies">Policy</a><span class="special">&gt;</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">gamma_p_inva</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">p</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">&amp;);</span>
</pre>
<p>
Returns a value a such that: <code class="computeroutput"><span class="identifier">p</span>
<span class="special">=</span> <span class="identifier">gamma_p</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
<span class="identifier">x</span><span class="special">);</span></code>
</p>
<p>
Requires: <span class="emphasis"><em>x &gt; 0</em></span> and <span class="emphasis"><em>1 &gt;= p,q &gt;=
0</em></span>.
</p>
<a name="math_toolkit.special.sf_gamma.igamma_inv.accuracy"></a><h5>
<a name="id1082993"></a>
<a class="link" href="igamma_inv.html#math_toolkit.special.sf_gamma.igamma_inv.accuracy">Accuracy</a>
</h5>
<p>
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 <a class="link" href="igamma.html" title="Incomplete Gamma Functions">gamma_p</a>
and <a class="link" href="igamma.html" title="Incomplete Gamma Functions">gamma_q</a>
functions.
</p>
<a name="math_toolkit.special.sf_gamma.igamma_inv.testing"></a><h5>
<a name="id1083019"></a>
<a class="link" href="igamma_inv.html#math_toolkit.special.sf_gamma.igamma_inv.testing">Testing</a>
</h5>
<p>
There are two sets of tests:
</p>
<div class="itemizedlist"><ul type="disc">
<li>
Basic sanity checks attempt to "round-trip" from <span class="emphasis"><em>a</em></span>
and <span class="emphasis"><em>x</em></span> to <span class="emphasis"><em>p</em></span> or <span class="emphasis"><em>q</em></span>
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 <span class="emphasis"><em>p</em></span> or <span class="emphasis"><em>q</em></span>
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="id1083638"></a>
<a class="link" href="igamma_inv.html#math_toolkit.special.sf_gamma.igamma_inv.implementation">Implementation</a>
</h5>
<p>
The functions gamma_p_inv and <a href="http://functions.wolfram.com/GammaBetaErf/InverseGammaRegularized/" target="_top">gamma_q_inv</a>
share a common implementation.
</p>
<p>
First an initial approximation is computed using the methodology described
in:
</p>
<p>
<a href="http://portal.acm.org/citation.cfm?id=23109&amp;coll=portal&amp;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>
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
An initial approximation for <span class="emphasis"><em>a</em></span> is computed very crudely
so that <span class="emphasis"><em>gamma_p(a, x) ~ 0.5</em></span>, 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.
</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 &#169; 2006 , 2007, 2008, 2009, 2010 John Maddock, Paul A. Bristow,
Hubert Holin, Xiaogang Zhang, Bruno Lalande, Johan R&#229;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="igamma.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.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="gamma_derivatives.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>