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"><</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">></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">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> 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"><</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">></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">&);</span> 39 40<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</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_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"><</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">></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">&);</span> 45 46<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></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"><</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">></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">&);</span> 51 52<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T3</span><span class="special">></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"><</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">></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">&);</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>| < 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 < b</em></span>, <span class="emphasis"><em>b > 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&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 < 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 < 0</em></span> 226 and <span class="emphasis"><em>a,z > 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 < 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 < a < 0 and 0 < b,z < 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 < <span class="emphasis"><em>b</em></span> < 0 and <span class="emphasis"><em>a</em></span>,<span class="emphasis"><em>z</em></span> 426 > 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 < 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 < 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 < 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&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 > 0</em></span>, or <span class="emphasis"><em>a</em></span> ≪ 1, and <span class="emphasis"><em>z 572 < 0</em></span>. 573 </p> 574<p> 575 Then we have Tricomi's approximation (given in simplified form in A&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 < 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 > 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| << |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 > 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 < a < 1</em></span> and <span class="emphasis"><em>b > 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 < a < 2b < 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 < a < b</em></span> and use A&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 < 0</em></span> and <span class="emphasis"><em>a</em></span> tiny we would 711 normally use A&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 > 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> < 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 > 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 < 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 > 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