libs/math/doc/html/math_toolkit/expint/expint_n.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Exponential Integral En</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.11.0">
   8 <link rel="up" href="../expint.html" title="Exponential Integrals">
   9 <link rel="prev" href="../expint.html" title="Exponential Integrals">
  10 <link rel="next" href="expint_i.html" title="Exponential Integral Ei">
  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="../expint.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../expint.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="expint_i.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.expint.expint_n"></a><a class="link" href="expint_n.html" title="Exponential Integral En">Exponential Integral En</a>
  28 </h3></div></div></div>
  29 <h5>
  30 <a name="math_toolkit.expint.expint_n.h0"></a>
  31         <span class="phrase"><a name="math_toolkit.expint.expint_n.synopsis"></a></span><a class="link" href="expint_n.html#math_toolkit.expint.expint_n.synopsis">Synopsis</a>
  32       </h5>
  33 <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">expint</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  34 </pre>
  35 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
  36
  37 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
  38 <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">expint</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">z</span><span class="special">);</span>
  39
  40 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><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">expint</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&amp;);</span>
  42
  43 <span class="special">}}</span> <span class="comment">// namespaces</span>
  44 </pre>
  45 <p>
  46         The return type of these functions is computed using the <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
  47         type calculation rules</em></span></a>: the return type is <code class="computeroutput"><span class="keyword">double</span></code> if T is an integer type, and T otherwise.
  48       </p>
  49 <p>
  50         The final <a class="link" href="../../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can
  51         be used to control the behaviour of the function: how it handles errors,
  52         what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">policy
  53         documentation for more details</a>.
  54       </p>
  55 <h5>
  56 <a name="math_toolkit.expint.expint_n.h1"></a>
  57         <span class="phrase"><a name="math_toolkit.expint.expint_n.description"></a></span><a class="link" href="expint_n.html#math_toolkit.expint.expint_n.description">Description</a>
  58       </h5>
  59 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
  60 <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">expint</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">z</span><span class="special">);</span>
  61
  62 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&gt;</span>
  63 <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">expint</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&amp;);</span>
  64 </pre>
  65 <p>
  66         Returns the <a href="http://mathworld.wolfram.com/En-Function.html" target="_top">exponential
  67         integral En</a> of z:
  68       </p>
  69 <div class="blockquote"><blockquote class="blockquote"><p>
  70           <span class="inlinemediaobject"><img src="../../../equations/expint_n_1.svg"></span>
  71
  72         </p></blockquote></div>
  73 <div class="blockquote"><blockquote class="blockquote"><p>
  74           <span class="inlinemediaobject"><img src="../../../graphs/expint2.svg" align="middle"></span>
  75
  76         </p></blockquote></div>
  77 <h5>
  78 <a name="math_toolkit.expint.expint_n.h2"></a>
  79         <span class="phrase"><a name="math_toolkit.expint.expint_n.accuracy"></a></span><a class="link" href="expint_n.html#math_toolkit.expint.expint_n.accuracy">Accuracy</a>
  80       </h5>
  81 <p>
  82         The following table shows the peak errors (in units of epsilon) found on
  83         various platforms with various floating point types, along with comparisons
  84         to other libraries. Unless otherwise specified any floating point type that
  85         is narrower than the one shown will have <a class="link" href="../relative_error.html#math_toolkit.relative_error.zero_error">effectively
  86         zero error</a>.
  87       </p>
  88 <div class="table">
  89 <a name="math_toolkit.expint.expint_n.table_expint_En_"></a><p class="title"><b>Table&#160;8.77.&#160;Error rates for expint (En)</b></p>
  90 <div class="table-contents"><table class="table" summary="Error rates for expint (En)">
  91 <colgroup>
  92 <col>
  93 <col>
  94 <col>
  95 <col>
  96 <col>
  97 </colgroup>
  98 <thead><tr>
  99 <th>
 100               </th>
 101 <th>
 102                 <p>
 103                   GNU C++ version 7.1.0<br> linux<br> double
 104                 </p>
 105               </th>
 106 <th>
 107                 <p>
 108                   GNU C++ version 7.1.0<br> linux<br> long double
 109                 </p>
 110               </th>
 111 <th>
 112                 <p>
 113                   Sun compiler version 0x5150<br> Sun Solaris<br> long double
 114                 </p>
 115               </th>
 116 <th>
 117                 <p>
 118                   Microsoft Visual C++ version 14.1<br> Win32<br> double
 119                 </p>
 120               </th>
 121 </tr></thead>
 122 <tbody>
 123 <tr>
 124 <td>
 125                 <p>
 126                   Exponential Integral En
 127                 </p>
 128               </td>
 129 <td>
 130                 <p>
 131                   <span class="blue">Max = 0.589&#949; (Mean = 0.0331&#949;)</span><br>
 132                   <br> (<span class="emphasis"><em>GSL 2.1:</em></span> Max = 58.5&#949; (Mean = 17.1&#949;))
 133                 </p>
 134               </td>
 135 <td>
 136                 <p>
 137                   <span class="blue">Max = 9.97&#949; (Mean = 2.13&#949;)</span>
 138                 </p>
 139               </td>
 140 <td>
 141                 <p>
 142                   <span class="blue">Max = 9.97&#949; (Mean = 2.13&#949;)</span>
 143                 </p>
 144               </td>
 145 <td>
 146                 <p>
 147                   <span class="blue">Max = 7.16&#949; (Mean = 1.85&#949;)</span>
 148                 </p>
 149               </td>
 150 </tr>
 151 <tr>
 152 <td>
 153                 <p>
 154                   Exponential Integral En: small z values
 155                 </p>
 156               </td>
 157 <td>
 158                 <p>
 159                   <span class="blue">Max = 0&#949; (Mean = 0&#949;)</span><br> <br> (<span class="emphasis"><em>GSL
 160                   2.1:</em></span> Max = 115&#949; (Mean = 23.6&#949;))
 161                 </p>
 162               </td>
 163 <td>
 164                 <p>
 165                   <span class="blue">Max = 1.99&#949; (Mean = 0.559&#949;)</span>
 166                 </p>
 167               </td>
 168 <td>
 169                 <p>
 170                   <span class="blue">Max = 1.99&#949; (Mean = 0.559&#949;)</span>
 171                 </p>
 172               </td>
 173 <td>
 174                 <p>
 175                   <span class="blue">Max = 2.62&#949; (Mean = 0.531&#949;)</span>
 176                 </p>
 177               </td>
 178 </tr>
 179 <tr>
 180 <td>
 181                 <p>
 182                   Exponential Integral E1
 183                 </p>
 184               </td>
 185 <td>
 186                 <p>
 187                   <span class="blue">Max = 0.556&#949; (Mean = 0.0625&#949;)</span><br>
 188                   <br> (<span class="emphasis"><em>GSL 2.1:</em></span> Max = 0.988&#949; (Mean = 0.469&#949;))
 189                 </p>
 190               </td>
 191 <td>
 192                 <p>
 193                   <span class="blue">Max = 0.965&#949; (Mean = 0.414&#949;)</span>
 194                 </p>
 195               </td>
 196 <td>
 197                 <p>
 198                   <span class="blue">Max = 0.965&#949; (Mean = 0.408&#949;)</span>
 199                 </p>
 200               </td>
 201 <td>
 202                 <p>
 203                   <span class="blue">Max = 0.988&#949; (Mean = 0.486&#949;)</span>
 204                 </p>
 205               </td>
 206 </tr>
 207 </tbody>
 208 </table></div>
 209 </div>
 210 <br class="table-break"><h5>
 211 <a name="math_toolkit.expint.expint_n.h3"></a>
 212         <span class="phrase"><a name="math_toolkit.expint.expint_n.testing"></a></span><a class="link" href="expint_n.html#math_toolkit.expint.expint_n.testing">Testing</a>
 213       </h5>
 214 <p>
 215         The tests for these functions come in two parts: basic sanity checks use
 216         spot values calculated using <a href="http://functions.wolfram.com/webMathematica/FunctionEvaluation.jsp?name=ExpIntegralE" target="_top">Mathworld's
 217         online evaluator</a>, while accuracy checks use high-precision test values
 218         calculated at 1000-bit precision with <a href="http://shoup.net/ntl/doc/RR.txt" target="_top">NTL::RR</a>
 219         and this implementation. Note that the generic and type-specific versions
 220         of these functions use differing implementations internally, so this gives
 221         us reasonably independent test data. Using our test data to test other "known
 222         good" implementations also provides an additional sanity check.
 223       </p>
 224 <h5>
 225 <a name="math_toolkit.expint.expint_n.h4"></a>
 226         <span class="phrase"><a name="math_toolkit.expint.expint_n.implementation"></a></span><a class="link" href="expint_n.html#math_toolkit.expint.expint_n.implementation">Implementation</a>
 227       </h5>
 228 <p>
 229         The generic version of this function uses the continued fraction:
 230       </p>
 231 <div class="blockquote"><blockquote class="blockquote"><p>
 232           <span class="inlinemediaobject"><img src="../../../equations/expint_n_3.svg"></span>
 233
 234         </p></blockquote></div>
 235 <p>
 236         for large <span class="emphasis"><em>x</em></span> and the infinite series:
 237       </p>
 238 <div class="blockquote"><blockquote class="blockquote"><p>
 239           <span class="inlinemediaobject"><img src="../../../equations/expint_n_2.svg"></span>
 240
 241         </p></blockquote></div>
 242 <p>
 243         for small <span class="emphasis"><em>x</em></span>.
 244       </p>
 245 <p>
 246         Where the precision of <span class="emphasis"><em>x</em></span> is known at compile time and
 247         is 113 bits or fewer in precision, then rational approximations <a class="link" href="../sf_implementation.html#math_toolkit.sf_implementation.rational_approximations_used">devised
 248         by JM</a> are used for the <code class="computeroutput"><span class="identifier">n</span>
 249         <span class="special">==</span> <span class="number">1</span></code>
 250         case.
 251       </p>
 252 <p>
 253         For <code class="computeroutput"><span class="identifier">x</span> <span class="special">&lt;</span>
 254         <span class="number">1</span></code> the approximating form is a minimax
 255         approximation:
 256       </p>
 257 <div class="blockquote"><blockquote class="blockquote"><p>
 258           <span class="inlinemediaobject"><img src="../../../equations/expint_n_4.svg"></span>
 259
 260         </p></blockquote></div>
 261 <p>
 262         and for <code class="computeroutput"><span class="identifier">x</span> <span class="special">&gt;</span>
 263         <span class="number">1</span></code> a Chebyshev interpolated approximation
 264         of the form:
 265       </p>
 266 <div class="blockquote"><blockquote class="blockquote"><p>
 267           <span class="inlinemediaobject"><img src="../../../equations/expint_n_5.svg"></span>
 268
 269         </p></blockquote></div>
 270 <p>
 271         is used.
 272       </p>
 273 </div>
 274 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 275 <td align="left"></td>
 276 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2019 Nikhar
 277       Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
 278       Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
 279       R&#229;de, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
 280       Daryle Walker and Xiaogang Zhang<p>
 281         Distributed under the Boost Software License, Version 1.0. (See accompanying
 282         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>)
 283       </p>
 284 </div></td>
 285 </tr></table>
 286 <hr>
 287 <div class="spirit-nav">
 288 <a accesskey="p" href="../expint.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../expint.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="expint_i.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 289 </div>
 290 </body>
 291 </html>