• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
4<title>Hypergeometric pFq</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.12.0">
8<link rel="up" href="../hypergeometric.html" title="Hypergeometric Functions">
9<link rel="prev" href="hypergeometric_1f1.html" title="Hypergeometric 1F1">
10<link rel="next" href="hypergeometric_refs.html" title="Hypergeometric References">
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="hypergeometric_1f1.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../hypergeometric.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="hypergeometric_refs.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.hypergeometric.hypergeometric_pfq"></a><a class="link" href="hypergeometric_pfq.html" title="Hypergeometric pFq">Hypergeometric
28      <sub>p</sub>F<sub>q</sub></a>
29</h3></div></div></div>
30<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">hypergeometric_pFq</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
31
32<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>
33
34<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Seq</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Real</span><span class="special">&gt;</span>
35<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">hypergeometric_pFq</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&amp;</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&amp;</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">Real</span><span class="special">*</span> <span class="identifier">p_abs_error</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Policy</span><span class="special">&amp;</span> <span class="identifier">pol</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">Seq</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Real</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">hypergeometric_pFq</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&amp;</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&amp;</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">Real</span><span class="special">*</span> <span class="identifier">p_abs_error</span> <span class="special">=</span> <span class="number">0</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">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Real</span><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">hypergeometric_pFq</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">initializer_list</span><span class="special">&lt;</span><span class="identifier">R</span><span class="special">&gt;&amp;</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">initializer_list</span><span class="special">&lt;</span><span class="identifier">R</span><span class="special">&gt;&amp;</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">Real</span><span class="special">*</span> <span class="identifier">p_abs_error</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Policy</span><span class="special">&amp;</span> <span class="identifier">pol</span><span class="special">);</span>
42
43<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Real</span><span class="special">&gt;</span>
44<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">hypergeometric_pFq</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">initializer_list</span><span class="special">&lt;</span><span class="identifier">R</span><span class="special">&gt;&amp;</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">initializer_list</span><span class="special">&lt;</span><span class="identifier">R</span><span class="special">&gt;&amp;</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">,</span> <span class="identifier">Real</span><span class="special">*</span> <span class="identifier">p_abs_error</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>
45
46<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Seq</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Real</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policy</span><span class="special">&gt;</span>
47<span class="identifier">Real</span> <span class="identifier">hypergeometric_pFq_precision</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&amp;</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&amp;</span> <span class="identifier">bj</span><span class="special">,</span> <span class="identifier">Real</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">digits10</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">timeout</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Policy</span><span class="special">&amp;</span> <span class="identifier">pol</span><span class="special">);</span>
48
49<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Seq</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Real</span><span class="special">&gt;</span>
50<span class="identifier">Real</span> <span class="identifier">hypergeometric_pFq_precision</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&amp;</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&amp;</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">digits10</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">timeout</span> <span class="special">=</span> <span class="number">0.5</span><span class="special">);</span>
51
52<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Real</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policy</span><span class="special">&gt;</span>
53<span class="identifier">Real</span> <span class="identifier">hypergeometric_pFq_precision</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">initializer_list</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">&gt;&amp;</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">initializer_list</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">&gt;&amp;</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">digits10</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">timeout</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Policy</span><span class="special">&amp;</span> <span class="identifier">pol</span><span class="special">);</span>
54
55<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Real</span><span class="special">&gt;</span>
56<span class="identifier">Real</span> <span class="identifier">hypergeometric_pFq_precision</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">initializer_list</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">&gt;&amp;</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">initializer_list</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">&gt;&amp;</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&amp;</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">digits10</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">timeout</span> <span class="special">=</span> <span class="number">0.5</span><span class="special">);</span>
57
58<span class="special">}}</span> <span class="comment">// namespaces</span>
59</pre>
60<h5>
61<a name="math_toolkit.hypergeometric.hypergeometric_pfq.h0"></a>
62        <span class="phrase"><a name="math_toolkit.hypergeometric.hypergeometric_pfq.description"></a></span><a class="link" href="hypergeometric_pfq.html#math_toolkit.hypergeometric.hypergeometric_pfq.description">Description</a>
63      </h5>
64<p>
65        The function <code class="computeroutput"><span class="identifier">hypergeometric_pFq</span></code>
66        returns the result of:
67      </p>
68<div class="blockquote"><blockquote class="blockquote"><p>
69          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_pfq_1.svg" width="409" height="53"></object></span>
70        </p></blockquote></div>
71<p>
72        It is most naturally used via initializer lists as in:
73      </p>
74<pre class="programlisting"><span class="keyword">double</span> <span class="identifier">h</span> <span class="special">=</span> <span class="identifier">hypergeometric_pFq</span><span class="special">({</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">4</span><span class="special">},</span> <span class="special">{</span><span class="number">5</span><span class="special">,</span><span class="number">6</span><span class="special">,</span><span class="number">7</span><span class="special">,</span><span class="number">8</span><span class="special">},</span> <span class="identifier">z</span><span class="special">);</span>  <span class="comment">// Calculate 3F4</span>
75</pre>
76<p>
77        The optional <span class="emphasis"><em>p_abs_error</em></span> argument calculates an estimate
78        of the absolute error in the result from the L1 norm of the sum, plus some
79        other factors (see implementation below).
80      </p>
81<p>
82        You should divide this value by the result to get an estimate of <span class="emphasis"><em>relative
83        error</em></span>.
84      </p>
85<p>
86        It should be noted that the error estimates are rather crude - the error
87        can be significantly underestimated in some circumstances, and over-estimated
88        in others.
89      </p>
90<p>
91        The <code class="computeroutput"><span class="identifier">hypergeometric_pFq_precision</span></code>
92        functions will calculate <code class="computeroutput"><span class="identifier">pFq</span></code>
93        to a specified number of decimal places, and if <code class="computeroutput"><span class="identifier">timeout</span></code>
94        is reached then they raise an <a class="link" href="../error_handling.html#math_toolkit.error_handling.evaluation_error">evaluation_error</a>.
95        Note that while these functions are defined as templates, they require type
96        <code class="computeroutput"><span class="identifier">Real</span></code> to be a <span class="bold"><strong>variable-precision</strong></span>
97        floating-point type: in practice the only type currently supported (as of
98        July 2019) is <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">mpfr_float</span></code>. Typical usage would be:
99      </p>
100<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">mpfr_float</span> <span class="identifier">mp_type</span><span class="special">;</span>
101<span class="comment">//</span>
102<span class="comment">// Calculate 2F2 to 20 decimal places using a 10 second timeout:</span>
103<span class="comment">//</span>
104<span class="identifier">mp_type</span> <span class="identifier">result</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">hypergeometric_pFq_precision</span><span class="special">(</span>
105  <span class="special">{</span> <span class="identifier">mp_type</span><span class="special">(</span><span class="identifier">a1</span><span class="special">),</span> <span class="identifier">mp_type</span><span class="special">(</span><span class="identifier">a2</span><span class="special">)</span> <span class="special">},</span> <span class="special">{</span> <span class="identifier">mp_type</span><span class="special">(</span><span class="identifier">b1</span><span class="special">),</span> <span class="identifier">mp_type</span><span class="special">(</span><span class="identifier">b2</span><span class="special">)</span> <span class="special">},</span> <span class="identifier">mp_type</span><span class="special">(</span><span class="identifier">z</span><span class="special">),</span> <span class="number">20</span><span class="special">,</span> <span class="number">10.0</span>
106  <span class="special">);</span>
107<span class="comment">//</span>
108<span class="comment">// Convert the result back to a double:</span>
109<span class="comment">//</span>
110<span class="keyword">double</span> <span class="identifier">d_result</span> <span class="special">=</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;(</span><span class="identifier">result</span><span class="special">);</span>
111</pre>
112<h5>
113<a name="math_toolkit.hypergeometric.hypergeometric_pfq.h1"></a>
114        <span class="phrase"><a name="math_toolkit.hypergeometric.hypergeometric_pfq.implementation"></a></span><a class="link" href="hypergeometric_pfq.html#math_toolkit.hypergeometric.hypergeometric_pfq.implementation">Implementation</a>
115      </h5>
116<p>
117        This function is implemented by direct summation of the series; summation
118        normally starts with the zeroth term, but will skip forward and sum outward
119        (ie in both forward and backward directions) from some term <span class="emphasis"><em>N</em></span>
120        when required. This is particularly important when some of the <span class="emphasis"><em>b</em></span>
121        arguments are negative, as in this situation the sum undergoes "false-convergence",
122        and then diverges again as each b<sub>j</sub> passes the origin. Consequently, were you
123        to plot the magnitude of the terms in the sum, you would see them pass through
124        a series of minima and maxima before finally converging to zero at infinity.
125        For some values of <span class="emphasis"><em>p</em></span> and <span class="emphasis"><em>q</em></span> we can
126        compute where the maxima occur, and therefore sum only the terms that will
127        have an impact on the result. For other <span class="emphasis"><em>p</em></span> and <span class="emphasis"><em>q</em></span>
128        values, predicting the exact locations of the maxima is not so easy, and
129        we simply restart summation at the point where each b<sub>j</sub> passes the origin:
130        this will eventually reach all the significant terms of the sum, but the
131        key word may well be "eventually".
132      </p>
133<p>
134        The error term <span class="emphasis"><em>p_abs_error</em></span> is normally simply the sum
135        of the absolute values of each term multiplied by machine epsilon for type
136        <code class="computeroutput"><span class="identifier">Real</span></code>. However, if it was
137        necessary for the summation to skip forward, then <span class="emphasis"><em>p_abs_error</em></span>
138        is adjusted to account for the error inherent in calculating the N'th term
139        via logarithms.
140      </p>
141</div>
142<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
143<td align="left"></td>
144<td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar
145      Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
146      Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
147      Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
148      Daryle Walker and Xiaogang Zhang<p>
149        Distributed under the Boost Software License, Version 1.0. (See accompanying
150        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>)
151      </p>
152</div></td>
153</tr></table>
154<hr>
155<div class="spirit-nav">
156<a accesskey="p" href="hypergeometric_1f1.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../hypergeometric.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="hypergeometric_refs.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
157</div>
158</body>
159</html>
160