• 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 1F1</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_2f0.html" title="Hypergeometric 2F0">
10<link rel="next" href="hypergeometric_pfq.html" title="Hypergeometric pFq">
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_2f0.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_pfq.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_1f1"></a><a class="link" href="hypergeometric_1f1.html" title="Hypergeometric 1F1">Hypergeometric
28      <sub>1</sub><span class="emphasis"><em>F</em></span><sub>1</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_1F1</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">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> <span class="identifier">T3</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_1F1</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="identifier">T3</span> <span class="identifier">z</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">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 21. Policies: Controlling Precision, Error Handling etc">Policy</a><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_1F1</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="identifier">T3</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 21. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&amp;);</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> <span class="identifier">T3</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_1F1_regularized</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="identifier">T3</span> <span class="identifier">z</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">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> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 21. Policies: Controlling Precision, Error Handling etc">Policy</a><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_1F1_regularized</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="identifier">T3</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 21. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&amp;);</span>
45
46<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> <span class="identifier">T3</span><span class="special">&gt;</span>
47<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">log_hypergeometric_1F1</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="identifier">T3</span> <span class="identifier">z</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">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> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 21. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&gt;</span>
50<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">log_hypergeometric_1F1</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="identifier">T3</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 21. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&amp;);</span>
51
52<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> <span class="identifier">T3</span><span class="special">&gt;</span>
53<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">log_hypergeometric_1F1</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="identifier">T3</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">int</span><span class="special">*</span> <span class="identifier">sign</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">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> <span class="identifier">T3</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 21. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&gt;</span>
56<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">log_hypergeometric_1F1</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="identifier">T3</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">int</span><span class="special">*</span> <span class="identifier">sign</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 21. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&amp;);</span>
57
58<span class="special">}}</span> <span class="comment">// namespaces</span>
59</pre>
60<h5>
61<a name="math_toolkit.hypergeometric.hypergeometric_1f1.h0"></a>
62        <span class="phrase"><a name="math_toolkit.hypergeometric.hypergeometric_1f1.description"></a></span><a class="link" href="hypergeometric_1f1.html#math_toolkit.hypergeometric.hypergeometric_1f1.description">Description</a>
63      </h5>
64<p>
65        </p>
66<div>
67   <script type="text/javascript" src="../../../graphs/hypergeometric_1f1/plotlyjs-bundle.js"></script>
68</div>
69<p>
70      </p>
71<p>
72        The function <code class="computeroutput"><span class="identifier">hypergeometric_1F1</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span>
73        <span class="identifier">b</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span></code> returns
74        the non-singular solution to <a href="https://en.wikipedia.org/wiki/Confluent_hypergeometric_function" target="_top">Kummer's
75        equation</a>
76      </p>
77<div class="blockquote"><blockquote class="blockquote"><p>
78          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_2.svg" width="181" height="34"></object></span>
79        </p></blockquote></div>
80<p>
81        which for |<span class="emphasis"><em>z</em></span>| &lt; 1 has the hypergeometric series expansion
82      </p>
83<div class="blockquote"><blockquote class="blockquote"><p>
84          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_1.svg" width="234" height="38"></object></span>
85        </p></blockquote></div>
86<p>
87        where (<span class="emphasis"><em>a</em></span>)<sub><span class="emphasis"><em>n</em></span></sub> denotes rising factorial.
88        This function has the same definition as Mathematica's <code class="computeroutput"><span class="identifier">Hypergeometric1F1</span><span class="special">[</span><span class="identifier">a</span><span class="special">,</span>
89        <span class="identifier">b</span><span class="special">,</span> <span class="identifier">z</span><span class="special">]</span></code> and
90        Maple's <code class="computeroutput"><span class="identifier">KummerM</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">z</span><span class="special">)</span></code>.
91      </p>
92<p>
93        The "regularized" versions of the function return:
94      </p>
95<div class="blockquote"><blockquote class="blockquote"><p>
96          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_17.svg" width="313" height="44"></object></span>
97        </p></blockquote></div>
98<p>
99        The "log" versions of the function return:
100      </p>
101<div class="blockquote"><blockquote class="blockquote"><p>
102          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_18.svg" width="119" height="20"></object></span>
103        </p></blockquote></div>
104<p>
105        When the optional <code class="computeroutput"><span class="identifier">sign</span></code> argument
106        is supplied it is set on exit to either +1 or -1 depending on the sign of
107        <sub>1</sub><span class="emphasis"><em>F</em></span><sub>1</sub>(<span class="emphasis"><em>a</em></span>, <span class="emphasis"><em>b</em></span>,
108        <span class="emphasis"><em>z</em></span>).
109      </p>
110<p>
111        Both the regularized and the logarithmic versions of these functions return
112        results without the spurious under/overflow that plague naive implementations.
113      </p>
114<h5>
115<a name="math_toolkit.hypergeometric.hypergeometric_1f1.h1"></a>
116        <span class="phrase"><a name="math_toolkit.hypergeometric.hypergeometric_1f1.known_issues"></a></span><a class="link" href="hypergeometric_1f1.html#math_toolkit.hypergeometric.hypergeometric_1f1.known_issues">Known
117        Issues</a>
118      </h5>
119<p>
120        This function is still very much the subject of active research, and a full
121        range of methods capable of calculating the function over its entire domain
122        are not yet available. We have worked extremely hard to ensure that problem
123        domains result in an exception being thrown (an <a class="link" href="../error_handling.html#math_toolkit.error_handling.evaluation_error">evaluation_error</a>)
124        rather than return a garbage result. Domains that are still unsolved include:
125      </p>
126<div class="informaltable"><table class="table">
127<colgroup>
128<col>
129<col>
130<col>
131</colgroup>
132<thead><tr>
133<th>
134                <p>
135                  domain
136                </p>
137              </th>
138<th>
139                <p>
140                  comment
141                </p>
142              </th>
143<th>
144                <p>
145                  example
146                </p>
147              </th>
148</tr></thead>
149<tbody>
150<tr>
151<td>
152                <p>
153                  <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_13.svg" width="101" height="16"></object></span>
154                </p>
155              </td>
156<td>
157                <p>
158                  <span class="emphasis"><em>a, b</em></span> and <span class="emphasis"><em>z</em></span> all large.
159                </p>
160              </td>
161<td>
162                <p>
163                  <sub>1</sub>F<sub>1</sub>(-814723.75, -13586.87890625, -15.87335205078125)
164                </p>
165              </td>
166</tr>
167<tr>
168<td>
169                <p>
170                  <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_14.svg" width="89" height="16"></object></span>
171                </p>
172              </td>
173<td>
174                <p>
175                  <span class="emphasis"><em>a &lt; b</em></span>, <span class="emphasis"><em>b &gt; z</em></span>, this
176                  is really the same domain as above.
177                </p>
178              </td>
179<td>
180              </td>
181</tr>
182<tr>
183<td>
184                <p>
185                  <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_15.svg" width="78" height="16"></object></span>
186                </p>
187              </td>
188<td>
189                <p>
190                  There is a gap in between methods where no reliable implementation
191                  is possible, the issue becomes much worse for <span class="emphasis"><em>a</em></span>,
192                  <span class="emphasis"><em>b</em></span> and <span class="emphasis"><em>z</em></span> all large.
193                </p>
194              </td>
195<td>
196                <p>
197                  <sub>1</sub>F<sub>1</sub>(9057.91796875, -1252.51318359375, 15.87335205078125)
198                </p>
199              </td>
200</tr>
201<tr>
202<td>
203                <p>
204                  <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_16.svg" width="98" height="18"></object></span>
205                </p>
206              </td>
207<td>
208                <p>
209                  This domain is mostly handled by A&amp;S 13.3.6 (see implementation
210                  notes below), but there are some values where either that series
211                  is non-convergent (most particularly for <span class="emphasis"><em>b</em></span>
212                  &lt; 0) or where the series becomes divergent after a few terms
213                  limiting the precision that can be achieved.
214                </p>
215              </td>
216<td>
217                <p>
218                  <sub>1</sub>F<sub>1</sub>(-5.9981750131794866e-15, 0.499999999999994, -240.42092034220695)
219                </p>
220              </td>
221</tr>
222</tbody>
223</table></div>
224<p>
225        The following graph illustrates the problem area for <span class="emphasis"><em>b &lt; 0</em></span>
226        and <span class="emphasis"><em>a,z &gt; 0</em></span>:
227      </p>
228<p>
229        </p>
230<div>
231        <script type="text/javascript" src="../../../graphs/hypergeometric_1f1/negative_b_incalculable.js"></script>
232
233        <div id="fce5fa05-942c-4973-941f-2f3d25bcecb3" style="width: 800px; height: 600px;" class="plotly-graph-div"></div>
234        <script type="text/javascript">
235            (function(){
236                window.PLOTLYENV={'BASE_URL': 'https://plot.ly'};
237
238                var gd = document.getElementById('fce5fa05-942c-4973-941f-2f3d25bcecb3')
239                var resizeDebounce = null;
240
241                function resizePlot() {
242                    var bb = gd.getBoundingClientRect();
243                    Plotly.relayout(gd, {
244                        width: bb.width,
245                        height: bb.height
246                    });
247                }
248
249
250                window.addEventListener('resize', function() {
251                    if (resizeDebounce) {
252                        window.clearTimeout(resizeDebounce);
253                    }
254                    resizeDebounce = window.setTimeout(resizePlot, 100);
255                });
256
257
258
259                Plotly.plot(gd,  {
260                   data: negative_b_incalculable.data,
261                   layout: negative_b_incalculable.layout,
262                   frames: negative_b_incalculable.frames,
263                    config: {"showLink": true, "linkText": "Export to plot.ly", "mapboxAccessToken": "pk.eyJ1IjoiY2hyaWRkeXAiLCJhIjoiY2lxMnVvdm5iMDA4dnhsbTQ5aHJzcGs0MyJ9.X9o_rzNLNesDxdra4neC_A"}
264                });
265
266           }());
267        </script>
268    </div>
269<p>
270
271      </p>
272<h5>
273<a name="math_toolkit.hypergeometric.hypergeometric_1f1.h2"></a>
274        <span class="phrase"><a name="math_toolkit.hypergeometric.hypergeometric_1f1.testing"></a></span><a class="link" href="hypergeometric_1f1.html#math_toolkit.hypergeometric.hypergeometric_1f1.testing">Testing</a>
275      </h5>
276<p>
277        There are 3 main groups of tests:
278      </p>
279<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
280<li class="listitem">
281            Spot tests for special inputs with known values.
282          </li>
283<li class="listitem">
284            Sanity checks which use integrals of hypergeometric functions of known
285            value. These are particularly useful since for fixed <span class="emphasis"><em>a</em></span>
286            and <span class="emphasis"><em>b</em></span> they evaluate <span class="emphasis"><em><sub>1</sub>F<sub>1</sub>(a,b,z)</em></span>
287            for all <span class="emphasis"><em>z</em></span>.
288          </li>
289<li class="listitem">
290            Testing against values precomputed using arbitrary precision arithmetic
291            and the <span class="emphasis"><em>pFq</em></span> series.
292          </li>
293</ul></div>
294<p>
295        We also have a <a href="../../../../tools/hypergeometric_1F1_error_plot.cpp" target="_top">small
296        program</a> for testing random values over a user-specified domain of
297        <span class="emphasis"><em>a</em></span>, <span class="emphasis"><em>b</em></span> and <span class="emphasis"><em>z</em></span>,
298        this program is also used for the error rate plots below and has been extremely
299        useful in fine-tuning the implementation.
300      </p>
301<p>
302        It should be noted however, that there are some domains for large negative
303        <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span> that have poor test coverage
304        as we were simply unable to compute test values in reasonable time: it is
305        not uncommon for the <span class="emphasis"><em>pFq</em></span> series to cancel many hundreds
306        of digits and sometimes into the thousands of digits.
307      </p>
308<h5>
309<a name="math_toolkit.hypergeometric.hypergeometric_1f1.h3"></a>
310        <span class="phrase"><a name="math_toolkit.hypergeometric.hypergeometric_1f1.errors"></a></span><a class="link" href="hypergeometric_1f1.html#math_toolkit.hypergeometric.hypergeometric_1f1.errors">Errors</a>
311      </h5>
312<p>
313        We divide the domain of <sub>1</sub><span class="emphasis"><em>F</em></span><sub>1</sub> up into several domains to
314        explain the error rates.
315      </p>
316<p>
317        In the following graphs we ran 100000 random test cases over each domain,
318        note that the scatter plots show only the very worst errors as otherwise
319        the graphs are both incomprehensible and virtually unplottable (as in sudden
320        browser death).
321      </p>
322<p>
323        For 0 &lt; a,b,z the error rates are trivially small unless we are forced
324        to take steps to avoid very-slow convergence and use a method other than
325        direct evaluation of the series for performance reasons. Even so the errors
326        rates are broadly acceptable, while the scatter graph shows where the worst
327        errors are located:
328      </p>
329<p>
330        <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../graphs/hypergeometric_1f1/positive_abz_bins.svg" width="567" height="320"></object></span>
331        </p>
332<div>
333   <script type="text/javascript" src="../../../graphs/hypergeometric_1f1/positive_abz.js"></script>
334
335   <div id="87d8c26d-c743-4b69-8576-64f861bb7262" style="width: 800px; height: 600px;" class="plotly-graph-div"></div>
336   <script type="text/javascript">
337      (function () {
338         window.PLOTLYENV = { 'BASE_URL': 'https://plot.ly' };
339
340         var gd = document.getElementById('87d8c26d-c743-4b69-8576-64f861bb7262')
341         var resizeDebounce = null;
342
343         function resizePlot() {
344            var bb = gd.getBoundingClientRect();
345            Plotly.relayout(gd, {
346               width: bb.width,
347               height: bb.height
348            });
349         }
350
351
352         window.addEventListener('resize', function () {
353            if (resizeDebounce) {
354               window.clearTimeout(resizeDebounce);
355            }
356            resizeDebounce = window.setTimeout(resizePlot, 100);
357         });
358
359
360
361         Plotly.plot(gd, {
362            data: positive_abz.data,
363            layout: positive_abz.layout,
364            frames: positive_abz.frames,
365            config: { "showLink": true, "linkText": "Export to plot.ly", "mapboxAccessToken": "pk.eyJ1IjoiY2hyaWRkeXAiLCJhIjoiY2lxMnVvdm5iMDA4dnhsbTQ5aHJzcGs0MyJ9.X9o_rzNLNesDxdra4neC_A" }
366         });
367
368      }());
369   </script>
370</div>
371<p>
372
373      </p>
374<p>
375        For -1000 &lt; a &lt; 0 and 0 &lt; b,z &lt; 1000 the maximum error rates
376        are higher, but most are still low, and the worst errors are fairly evenly
377        distributed:
378      </p>
379<p>
380        <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../graphs/hypergeometric_1f1/negative_a_bins.svg" width="567" height="331"></object></span>
381        </p>
382<div>
383   <script type="text/javascript" src="../../../graphs/hypergeometric_1f1/negative_a.js"></script>
384
385   <div id="cc677464-acba-4deb-b026-ef0ea03f1259" style="width: 800px; height: 600px;" class="plotly-graph-div"></div>
386   <script type="text/javascript">
387      (function () {
388         window.PLOTLYENV = { 'BASE_URL': 'https://plot.ly' };
389
390         var gd = document.getElementById('cc677464-acba-4deb-b026-ef0ea03f1259')
391         var resizeDebounce = null;
392
393         function resizePlot() {
394            var bb = gd.getBoundingClientRect();
395            Plotly.relayout(gd, {
396               width: bb.width,
397               height: bb.height
398            });
399         }
400
401
402         window.addEventListener('resize', function () {
403            if (resizeDebounce) {
404               window.clearTimeout(resizeDebounce);
405            }
406            resizeDebounce = window.setTimeout(resizePlot, 100);
407         });
408
409
410
411         Plotly.plot(gd, {
412            data: negative_a.data,
413            layout: negative_a.layout,
414            frames: negative_a.frames,
415            config: { "showLink": true, "linkText": "Export to plot.ly", "mapboxAccessToken": "pk.eyJ1IjoiY2hyaWRkeXAiLCJhIjoiY2lxMnVvdm5iMDA4dnhsbTQ5aHJzcGs0MyJ9.X9o_rzNLNesDxdra4neC_A" }
416         });
417
418      }());
419   </script>
420</div>
421<p>
422
423      </p>
424<p>
425        For -1000 &lt; <span class="emphasis"><em>b</em></span> &lt; 0 and <span class="emphasis"><em>a</em></span>,<span class="emphasis"><em>z</em></span>
426        &gt; 0 the errors are mostly low at double precision except near the "unimplementable
427        zone". Note however, that the some of the methods used here fail to
428        converge to much better than double precision.
429      </p>
430<p>
431        <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../graphs/hypergeometric_1f1/negative_b_bins.svg" width="567" height="319"></object></span>
432        </p>
433<div>
434
435        <script type="text/javascript" src="../../../graphs/hypergeometric_1f1/negative_b.js"></script>
436
437        <div id="49ba2424-47a3-454d-ba72-b46ded00693f" style="width: 800px; height: 600px;" class="plotly-graph-div"></div>
438        <script type="text/javascript">
439            (function(){
440                window.PLOTLYENV={'BASE_URL': 'https://plot.ly'};
441
442                var gd = document.getElementById('49ba2424-47a3-454d-ba72-b46ded00693f')
443                var resizeDebounce = null;
444
445                function resizePlot() {
446                    var bb = gd.getBoundingClientRect();
447                    Plotly.relayout(gd, {
448                        width: bb.width,
449                        height: bb.height
450                    });
451                }
452
453
454                window.addEventListener('resize', function() {
455                    if (resizeDebounce) {
456                        window.clearTimeout(resizeDebounce);
457                    }
458                    resizeDebounce = window.setTimeout(resizePlot, 100);
459                });
460
461
462
463                Plotly.plot(gd,  {
464                   data: negative_b.data,
465                   layout: negative_b.layout,
466                   frames: negative_b.frames,
467                    config: {"showLink": true, "linkText": "Export to plot.ly", "mapboxAccessToken": "pk.eyJ1IjoiY2hyaWRkeXAiLCJhIjoiY2lxMnVvdm5iMDA4dnhsbTQ5aHJzcGs0MyJ9.X9o_rzNLNesDxdra4neC_A"}
468                });
469
470           }());
471        </script>
472    </div>
473<p>
474
475      </p>
476<p>
477        For both <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span> less than zero,
478        the errors the worst errors are clustered in a "difficult zone"
479        with <span class="emphasis"><em>b &lt; a</em></span> and <span class="emphasis"><em>z</em></span> ≈ <span class="emphasis"><em>a</em></span>:
480      </p>
481<p>
482        <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../graphs/hypergeometric_1f1/negative_ab_bins.svg" width="461" height="280"></object></span>
483        <body>
484        <script type="text/javascript" src="../../../graphs/hypergeometric_1f1/negative_ab.js"></script>
485
486        <div id="2867e84a-7d1d-4110-b28a-fb718dbd65ca" style="width: 800px; height: 600px;" class="plotly-graph-div"></div>
487        <script type="text/javascript">
488            (function(){
489                window.PLOTLYENV={'BASE_URL': 'https://plot.ly'};
490
491                var gd = document.getElementById('2867e84a-7d1d-4110-b28a-fb718dbd65ca')
492                var resizeDebounce = null;
493
494                function resizePlot() {
495                    var bb = gd.getBoundingClientRect();
496                    Plotly.relayout(gd, {
497                        width: bb.width,
498                        height: bb.height
499                    });
500                }
501
502
503                window.addEventListener('resize', function() {
504                    if (resizeDebounce) {
505                        window.clearTimeout(resizeDebounce);
506                    }
507                    resizeDebounce = window.setTimeout(resizePlot, 100);
508                });
509
510
511
512                Plotly.plot(gd,  {
513                   data: negative_ab.data,
514                   layout: negative_ab.layout,
515                   frames: negative_ab.frames,
516                    config: {"showLink": true, "linkText": "Export to plot.ly", "mapboxAccessToken": "pk.eyJ1IjoiY2hyaWRkeXAiLCJhIjoiY2lxMnVvdm5iMDA4dnhsbTQ5aHJzcGs0MyJ9.X9o_rzNLNesDxdra4neC_A"}
517                });
518
519           }());
520        </script>
521    </body>
522
523      </p>
524<h5>
525<a name="math_toolkit.hypergeometric.hypergeometric_1f1.h4"></a>
526        <span class="phrase"><a name="math_toolkit.hypergeometric.hypergeometric_1f1.implementation"></a></span><a class="link" href="hypergeometric_1f1.html#math_toolkit.hypergeometric.hypergeometric_1f1.implementation">Implementation</a>
527      </h5>
528<p>
529        The implementation for this function is remarkably complex; readers will
530        have to refer to the code for the transitions between methods, as we can
531        only give an overview here.
532      </p>
533<p>
534        In almost all cases where <span class="emphasis"><em>z &lt; 0</em></span> we use <a href="https://en.wikipedia.org/wiki/Confluent_hypergeometric_function" target="_top">Kummer's
535        relation</a> to make <span class="emphasis"><em>z</em></span> positive:
536      </p>
537<div class="blockquote"><blockquote class="blockquote"><p>
538          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_12.svg" width="189" height="16"></object></span>
539        </p></blockquote></div>
540<p>
541        The main series representation
542      </p>
543<div class="blockquote"><blockquote class="blockquote"><p>
544          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_1.svg" width="234" height="38"></object></span>
545        </p></blockquote></div>
546<p>
547        is used only when
548      </p>
549<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
550<li class="listitem">
551            we are sure that it is convergent and not subject to excessive cancellation,
552            and
553          </li>
554<li class="listitem">
555            there is no other better method available.
556          </li>
557</ul></div>
558<p>
559        The implementation of this series is complicated by the fact that for <span class="emphasis"><em>b</em></span>
560        &lt; 0 then what appears to be a fully converged series can in fact suddenly
561        jump back to life again as <span class="emphasis"><em>b</em></span> crosses the origin.
562      </p>
563<p>
564        A&amp;S 13.3.6 gives
565      </p>
566<div class="blockquote"><blockquote class="blockquote"><p>
567          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_3.svg" width="614" height="39"></object></span>
568        </p></blockquote></div>
569<p>
570        which is particularly useful for <span class="emphasis"><em>a ≅ b</em></span> and <span class="emphasis"><em>z
571        &gt; 0</em></span>, or <span class="emphasis"><em>a</em></span> ≪ 1, and <span class="emphasis"><em>z
572        &lt; 0</em></span>.
573      </p>
574<p>
575        Then we have Tricomi's approximation (given in simplified form in A&amp;S
576        13.3.7) <a class="link" href="hypergeometric_refs.html" title="Hypergeometric References">(7)</a>
577      </p>
578<div class="blockquote"><blockquote class="blockquote"><p>
579          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_4.svg" width="356" height="38"></object></span>
580        </p></blockquote></div>
581<p>
582        with
583      </p>
584<div class="blockquote"><blockquote class="blockquote"><p>
585          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_5.svg" width="390" height="33"></object></span>
586        </p></blockquote></div>
587<p>
588        and
589      </p>
590<div class="blockquote"><blockquote class="blockquote"><p>
591          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_6.svg" width="370" height="16"></object></span>
592        </p></blockquote></div>
593<p>
594        With <span class="emphasis"><em>E<sub>v</sub></em></span> defined as:
595      </p>
596<div class="blockquote"><blockquote class="blockquote"><p>
597          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_7.svg" width="149" height="86"></object></span>
598        </p></blockquote></div>
599<p>
600        This approximation is especially effective when <span class="emphasis"><em>a &lt; 0</em></span>.
601      </p>
602<p>
603        For <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span> both large and positive
604        and somewhat similar in size then an expansion in terms of gamma functions
605        can be used <a class="link" href="hypergeometric_refs.html" title="Hypergeometric References">(6)</a>:
606      </p>
607<div class="blockquote"><blockquote class="blockquote"><p>
608          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_8.svg" width="349" height="43"></object></span>
609        </p></blockquote></div>
610<p>
611        For <span class="emphasis"><em>z</em></span> large we have the asymptotic expansion:
612      </p>
613<div class="blockquote"><blockquote class="blockquote"><p>
614          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_9.svg" width="261" height="43"></object></span>
615        </p></blockquote></div>
616<p>
617        which is a special case of the gamma function expansion above.
618      </p>
619<p>
620        In the situation where <code class="computeroutput"><span class="identifier">ab</span><span class="special">/</span><span class="identifier">z</span></code> is reasonably
621        small then Luke's rational approximation is used - this is too complex to
622        document here, refer either to the code or the original paper <a class="link" href="hypergeometric_refs.html" title="Hypergeometric References">(3)</a>.
623      </p>
624<p>
625        The special case <sub>1</sub><span class="emphasis"><em>F</em></span><sub>1</sub>(1, <span class="emphasis"><em>b</em></span>, -<span class="emphasis"><em>z</em></span>)
626        is treated via Luke's Pade approximation <a class="link" href="hypergeometric_refs.html" title="Hypergeometric References">(3)</a>.
627      </p>
628<p>
629        That effectively completes the "direct" methods used, the remaining
630        areas are treated indirectly via recurrence relations. These require extreme
631        care in their use, as they often change the direction of stability, or else
632        are not stable at all. Sometimes this is a well defined and characterized
633        change in direction: for example with <span class="emphasis"><em>a,b</em></span> and <span class="emphasis"><em>z</em></span>
634        all positive recurrence on <span class="emphasis"><em>a</em></span> via
635      </p>
636<div class="blockquote"><blockquote class="blockquote"><p>
637          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_10.svg" width="429" height="16"></object></span>
638        </p></blockquote></div>
639<p>
640        abruptly changes from stable forwards recursion to stable backwards if <span class="emphasis"><em>2a-b+z</em></span>
641        changes sign. Thus recurrence on <span class="emphasis"><em>a</em></span>, even when <sub>1</sub><span class="emphasis"><em>F</em></span><sub>1</sub>(<span class="emphasis"><em>a</em></span>+<span class="emphasis"><em>N</em></span>,
642        <span class="emphasis"><em>b</em></span>, <span class="emphasis"><em>z</em></span>) is strictly increasing, needs
643        careful handling as <span class="emphasis"><em>a</em></span> → 0.
644      </p>
645<p>
646        The transitory nature of the stable recurrence relations is well documented
647        in the literature, for example <a class="link" href="hypergeometric_refs.html" title="Hypergeometric References">(10)</a>
648        gives many examples, including the anomalous behaviour of recurrence on
649        <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span> for large <span class="emphasis"><em>z</em></span>
650        as first documented by Gauchi <a class="link" href="hypergeometric_refs.html" title="Hypergeometric References">(12)</a>.
651        Gauchi also provides the definitive reference on 3-term recurrence relations
652        in general in <a class="link" href="hypergeometric_refs.html" title="Hypergeometric References">(11)</a>.
653      </p>
654<p>
655        Unfortunately, not all recurrence stabilities are so well defined. For example,
656        when considering <sub>1</sub>F<sub>1</sub>(<span class="emphasis"><em>a</em></span>, -<span class="emphasis"><em>b</em></span>, <span class="emphasis"><em>z</em></span>)
657        it would be convenient to use the continued fractions associated with the
658        recurrence relations to calculate <sub>1</sub>F<sub>1</sub>(<span class="emphasis"><em>a</em></span>, -<span class="emphasis"><em>b</em></span>,
659        <span class="emphasis"><em>z</em></span>) / <sub>1</sub>F<sub>1</sub>(<span class="emphasis"><em>a</em></span>, 1-<span class="emphasis"><em>b</em></span>,
660        <span class="emphasis"><em>z</em></span>) and then normalize either by iterating forwards on
661        <span class="emphasis"><em>b</em></span> until <span class="emphasis"><em>b &gt; 0</em></span> and comparison
662        with a reference value, or by using the Wronskian
663      </p>
664<div class="blockquote"><blockquote class="blockquote"><p>
665          <span class="inlinemediaobject"><object type="image/svg+xml" data="../../../equations/hypergeometric_1f1_11.svg" width="564" height="33"></object></span>
666        </p></blockquote></div>
667<p>
668        which is of course the well known Miller's method <a class="link" href="hypergeometric_refs.html" title="Hypergeometric References">(12)</a>.
669      </p>
670<p>
671        Unfortunately, stable forwards recursion on <span class="emphasis"><em>b</em></span> is stable
672        only for <span class="emphasis"><em>|b| &lt;&lt; |z|</em></span>, as <span class="emphasis"><em>|b|</em></span>
673        increases in magnitude it passes through a region where recursion is unstable
674        in both directions before eventually becoming stable in the backwards direction
675        (at least for a while!). This transition is moderated not by a change of
676        sign in the recurrence coefficients themselves, but by a change in the behaviour
677        of the <span class="emphasis"><em>values</em></span> of <sub>1</sub>F<sub>1</sub> - from alternating in sign when
678        <span class="emphasis"><em>|b|</em></span> is small to having the same sign when <span class="emphasis"><em>b</em></span>
679        is larger. During the actual transition, <sub>1</sub>F<sub>1</sub> will either pass through a zero
680        or a minima depending on whether b is even or odd (if there is a minima at
681        <sub>1</sub>F<sub>1</sub>(a, b, z) then there is necessarily a zero at <sub>1</sub>F<sub>1</sub>(a+1, b+1, z) as per
682        the <a href="https://dlmf.nist.gov/13.3#E15" target="_top">derivative of the function</a>).
683        As a result the behaviour of the recurrence relations is almost impossible
684        to reason about in this area, and we are left to using heuristic based approaches
685        to "guess" which region we are in.
686      </p>
687<p>
688        In this implementation we use recurrence relations as follows:
689      </p>
690<p>
691        For <span class="emphasis"><em>a,b,z &gt; 0</em></span> and large we can either:
692      </p>
693<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
694<li class="listitem">
695            Make <span class="emphasis"><em>0 &lt; a &lt; 1</em></span> and <span class="emphasis"><em>b &gt; z</em></span>
696            and evaluate the defining series directly, or
697          </li>
698<li class="listitem">
699            The gamma function approximation has decent convergence and accuracy
700            for <span class="emphasis"><em>2b - 1 &lt; a &lt; 2b &lt; z</em></span>, so we can move
701            <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span> into this region, or
702          </li>
703<li class="listitem">
704            We can recurse on <span class="emphasis"><em>b</em></span> alone so that <span class="emphasis"><em>b-1
705            &lt; a &lt; b</em></span> and use A&amp;S 13.3.6 as long as <span class="emphasis"><em>z</em></span>
706            is not too large.
707          </li>
708</ul></div>
709<p>
710        For <span class="emphasis"><em>b &lt; 0</em></span> and <span class="emphasis"><em>a</em></span> tiny we would
711        normally use A&amp;S 13.3.6, but when that is non-convergent for some inputs
712        we can use the forward recurrence relation on <span class="emphasis"><em>b</em></span> to calculate
713        the ratio <span class="emphasis"><em><sub>1</sub>F<sub>1</sub>(a, -b, z)/<sub>1</sub>F<sub>1</sub>(a, 1-b, z)</em></span> and then iterate
714        forwards until <span class="emphasis"><em>b &gt; 0</em></span> and compute a reference value
715        and normalize (Millers Method). In the same domain when <span class="emphasis"><em>b</em></span>
716        is near -1 we can use a single backwards recursion on <span class="emphasis"><em>b</em></span>
717        to compute <span class="emphasis"><em><sub>1</sub>F<sub>1</sub>(a, -b, z)</em></span> from <span class="emphasis"><em><sub>1</sub>F<sub>1</sub>(a, 2-b,
718        z)</em></span> and <span class="emphasis"><em><sub>1</sub>F<sub>1</sub>(<span class="emphasis"><em>a</em></span>, 1-<span class="emphasis"><em>b</em></span>,
719        <span class="emphasis"><em>z</em></span>)</em></span> even though technically we are recursing
720        in the unstable direction.
721      </p>
722<p>
723        For <span class="emphasis"><em><sub>1</sub>F<sub>1</sub>(-N, b, z)</em></span> and integer <span class="emphasis"><em>N</em></span>
724        then backwards recursion from <span class="emphasis"><em><sub>1</sub>F<sub>1</sub>(0, b, z)</em></span> and <span class="emphasis"><em><sub>1</sub>F<sub>1</sub>(-1,
725        b, z)</em></span> works well.
726      </p>
727<p>
728        For <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span> &lt; 0 and if all the
729        direct methods have failed, then we use various fallbacks:
730      </p>
731<p>
732        For <span class="emphasis"><em><sub>1</sub>F<sub>1</sub>(-a, b, z)</em></span> we can use backwards recursion on
733        <span class="emphasis"><em>a</em></span> as long as <span class="emphasis"><em>b &gt; z</em></span>, otherwise
734        a more complex scheme is required which starts from <span class="emphasis"><em><sub>1</sub>F<sub>1</sub>(-a + N,
735        b + M, z)</em></span>, and recurses backwards in up to 3 stages: first on
736        <span class="emphasis"><em>a</em></span>, then on <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span>
737        together, and finally on <span class="emphasis"><em>b</em></span> alone.
738      </p>
739<p>
740        For <span class="emphasis"><em>b &lt; 0</em></span> we have no good methods in some domains
741        (see the unsolved issues above). However in some circumstances we can either
742        use:
743      </p>
744<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
745<li class="listitem">
746            3-stage backwards recursion on both <span class="emphasis"><em>a</em></span>, <span class="emphasis"><em>a</em></span>
747            and <span class="emphasis"><em>b</em></span> and then <span class="emphasis"><em>b</em></span> as above.
748          </li>
749<li class="listitem">
750            Calculate the ratio <span class="emphasis"><em><sub>1</sub>F<sub>1</sub>(a, b, z) / <span class="emphasis"><em><sub>1</sub>F<sub>1</sub>(a-1, b-1,
751            z)</em></span></em></span> via backwards recurrence when z is small, and
752            then normalize via the Wronskian above (Miller's method).
753          </li>
754<li class="listitem">
755            Calculate the ratio <span class="emphasis"><em><sub>1</sub>F<sub>1</sub>(a, b, z) / <span class="emphasis"><em><sub>1</sub>F<sub>1</sub>(a+1, b+1,
756            z)</em></span></em></span> via forwards recurrence when z is large, and
757            then normalize by iterating until b &gt; 1 and comparing to a reference
758            value.
759          </li>
760</ul></div>
761<p>
762        The latter two methods use a lookup table to determine whether inputs are
763        in either of the domains or neither. Unfortunately the methods are basically
764        limited to double precision: calculation of the ratios require iteration
765        <span class="emphasis"><em>towards</em></span> the no-mans-land between the two methods where
766        iteration is unstable in both directions. As a result, only low-precision
767        results which require few iterations to calculate the ratio are available.
768      </p>
769<p>
770        If all else fails, then we use a checked series summation which will raise
771        an <a class="link" href="../error_handling.html#math_toolkit.error_handling.evaluation_error">evaluation_error</a>
772        if more than half the digits are destroyed by cancellation.
773      </p>
774</div>
775<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
776<td align="left"></td>
777<td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar
778      Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
779      Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
780      Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
781      Daryle Walker and Xiaogang Zhang<p>
782        Distributed under the Boost Software License, Version 1.0. (See accompanying
783        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>)
784      </p>
785</div></td>
786</tr></table>
787<hr>
788<div class="spirit-nav">
789<a accesskey="p" href="hypergeometric_2f0.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_pfq.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
790</div>
791</body>
792</html>
793