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"><</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">></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"><</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> 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">&</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&</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">&</span> <span class="identifier">pol</span><span class="special">);</span> 36 37<span class="keyword">template</span> <span class="special"><</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> 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">&</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&</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"><</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">></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"><</span><span class="identifier">R</span><span class="special">>&</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"><</span><span class="identifier">R</span><span class="special">>&</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&</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">&</span> <span class="identifier">pol</span><span class="special">);</span> 42 43<span class="keyword">template</span> <span class="special"><</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">></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"><</span><span class="identifier">R</span><span class="special">>&</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"><</span><span class="identifier">R</span><span class="special">>&</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&</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"><</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">></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">&</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&</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">&</span> <span class="identifier">pol</span><span class="special">);</span> 48 49<span class="keyword">template</span> <span class="special"><</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> 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">&</span> <span class="identifier">aj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Seq</span><span class="special">&</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&</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"><</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">></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"><</span><span class="identifier">Real</span><span class="special">>&</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"><</span><span class="identifier">Real</span><span class="special">>&</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&</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">&</span> <span class="identifier">pol</span><span class="special">);</span> 54 55<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Real</span><span class="special">></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"><</span><span class="identifier">Real</span><span class="special">>&</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"><</span><span class="identifier">Real</span><span class="special">>&</span> <span class="identifier">bj</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Real</span><span class="special">&</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"><</span><span class="keyword">double</span><span class="special">>(</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