libs/math/doc/html/math_toolkit/gauss.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Gauss-Legendre quadrature</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="../quadrature.html" title="Chapter&#160;13.&#160;Quadrature and Differentiation">
   9 <link rel="prev" href="trapezoidal.html" title="Trapezoidal Quadrature">
  10 <link rel="next" href="gauss_kronrod.html" title="Gauss-Kronrod Quadrature">
  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="trapezoidal.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quadrature.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="gauss_kronrod.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="math_toolkit.gauss"></a><a class="link" href="gauss.html" title="Gauss-Legendre quadrature">Gauss-Legendre quadrature</a>
  28 </h2></div></div></div>
  29 <h4>
  30 <a name="math_toolkit.gauss.h0"></a>
  31       <span class="phrase"><a name="math_toolkit.gauss.synopsis"></a></span><a class="link" href="gauss.html#math_toolkit.gauss.synopsis">Synopsis</a>
  32     </h4>
  33 <p>
  34       <code class="computeroutput"><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">quadrature</span><span class="special">/</span><span class="identifier">gauss</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>
  35     </p>
  36 <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> <span class="keyword">namespace</span> <span class="identifier">quadrature</span><span class="special">{</span>
  37
  38 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Real</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">Points</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">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">&lt;&gt;</span> <span class="special">&gt;</span>
  39 <span class="keyword">struct</span> <span class="identifier">gauss</span>
  40 <span class="special">{</span>
  41    <span class="keyword">static</span> <span class="keyword">const</span> <span class="identifier">RandomAccessContainer</span><span class="special">&amp;</span> <span class="identifier">abscissa</span><span class="special">();</span>
  42    <span class="keyword">static</span> <span class="keyword">const</span> <span class="identifier">RandomAccessContainer</span><span class="special">&amp;</span> <span class="identifier">weights</span><span class="special">();</span>
  43
  44    <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">&gt;</span>
  45    <span class="keyword">static</span> <span class="keyword">auto</span> <span class="identifier">integrate</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">Real</span><span class="special">*</span> <span class="identifier">pL1</span> <span class="special">=</span> <span class="keyword">nullptr</span><span class="special">)-&gt;</span><span class="keyword">decltype</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">declval</span><span class="special">&lt;</span><span class="identifier">F</span><span class="special">&gt;()(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">declval</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">&gt;()))</span>
  46
  47    <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">&gt;</span>
  48    <span class="keyword">static</span> <span class="keyword">auto</span> <span class="identifier">integrate</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">Real</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">Real</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">Real</span><span class="special">*</span> <span class="identifier">pL1</span> <span class="special">=</span> <span class="keyword">nullptr</span><span class="special">)-&gt;</span><span class="keyword">decltype</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">declval</span><span class="special">&lt;</span><span class="identifier">F</span><span class="special">&gt;()(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">declval</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">&gt;()))</span>
  49 <span class="special">};</span>
  50
  51 <span class="special">}}}</span> <span class="comment">// namespaces</span>
  52 </pre>
  53 <h4>
  54 <a name="math_toolkit.gauss.h1"></a>
  55       <span class="phrase"><a name="math_toolkit.gauss.description"></a></span><a class="link" href="gauss.html#math_toolkit.gauss.description">description</a>
  56     </h4>
  57 <p>
  58       The <code class="computeroutput"><span class="identifier">gauss</span></code> class template performs
  59       "one shot" non-adaptive Gauss-Legendre integration on some arbitrary
  60       function <span class="emphasis"><em>f</em></span> using the number of evaluation points as specified
  61       by <span class="emphasis"><em>Points</em></span>.
  62     </p>
  63 <p>
  64       This is intentionally a very simple quadrature routine, it obtains no estimate
  65       of the error, and is not adaptive, but is very efficient in simple cases that
  66       involve integrating smooth "bell like" functions and functions with
  67       rapidly convergent power series.
  68     </p>
  69 <pre class="programlisting"><span class="keyword">static</span> <span class="keyword">const</span> <span class="identifier">RandomAccessContainer</span><span class="special">&amp;</span> <span class="identifier">abscissa</span><span class="special">();</span>
  70 <span class="keyword">static</span> <span class="keyword">const</span> <span class="identifier">RandomAccessContainer</span><span class="special">&amp;</span> <span class="identifier">weights</span><span class="special">();</span>
  71 </pre>
  72 <p>
  73       These functions provide direct access to the abscissa and weights used to perform
  74       the quadrature: the return type depends on the <span class="emphasis"><em>Points</em></span>
  75       template parameter, but is always a RandomAccessContainer type. Note that only
  76       positive (or zero) abscissa and weights are stored.
  77     </p>
  78 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">&gt;</span>
  79 <span class="keyword">static</span> <span class="keyword">auto</span> <span class="identifier">integrate</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">Real</span><span class="special">*</span> <span class="identifier">pL1</span> <span class="special">=</span> <span class="keyword">nullptr</span><span class="special">)-&gt;</span><span class="keyword">decltype</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">declval</span><span class="special">&lt;</span><span class="identifier">F</span><span class="special">&gt;()(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">declval</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">&gt;()))</span>
  80 </pre>
  81 <p>
  82       Integrates <span class="emphasis"><em>f</em></span> over (-1,1), and optionally sets <code class="computeroutput"><span class="special">*</span><span class="identifier">pL1</span></code> to the
  83       L1 norm of the returned value: if this is substantially larger than the return
  84       value, then the sum was ill-conditioned. Note however, that no error estimate
  85       is available.
  86     </p>
  87 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">F</span><span class="special">&gt;</span>
  88 <span class="keyword">static</span> <span class="keyword">auto</span> <span class="identifier">integrate</span><span class="special">(</span><span class="identifier">F</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">Real</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">Real</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">Real</span><span class="special">*</span> <span class="identifier">pL1</span> <span class="special">=</span> <span class="keyword">nullptr</span><span class="special">)-&gt;</span><span class="keyword">decltype</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">declval</span><span class="special">&lt;</span><span class="identifier">F</span><span class="special">&gt;()(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">declval</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">&gt;()))</span>
  89 </pre>
  90 <p>
  91       Integrates <span class="emphasis"><em>f</em></span> over (a,b), and optionally sets <code class="computeroutput"><span class="special">*</span><span class="identifier">pL1</span></code> to the
  92       L1 norm of the returned value: if this is substantially larger than the return
  93       value, then the sum was ill-conditioned. Note however, that no error estimate
  94       is available. This function supports both finite and infinite <span class="emphasis"><em>a</em></span>
  95       and <span class="emphasis"><em>b</em></span>, as long as <code class="computeroutput"><span class="identifier">a</span>
  96       <span class="special">&lt;</span> <span class="identifier">b</span></code>.
  97     </p>
  98 <p>
  99       The Gaussian quadrature routine support both real and complex-valued quadrature.
 100       For example, the Lambert-W function admits the integral representation
 101     </p>
 102 <div class="blockquote"><blockquote class="blockquote"><p>
 103         <span class="serif_italic"><span class="emphasis"><em>W(z) = 1/2&#928; &#8747;<sub>-&#928;</sub><sup>&#928;</sup>  ((1-
 104         v cot(v) )^2 + v^2)/(z + v csc(v) exp(-v cot(v))) dv</em></span></span>
 105       </p></blockquote></div>
 106 <p>
 107       so it can be effectively computed via Gaussian quadrature using the following
 108       code:
 109     </p>
 110 <pre class="programlisting"><span class="identifier">Complex</span> <span class="identifier">z</span><span class="special">{</span><span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span>
 111 <span class="keyword">auto</span> <span class="identifier">lw</span> <span class="special">=</span> <span class="special">[&amp;</span><span class="identifier">z</span><span class="special">](</span><span class="identifier">Real</span> <span class="identifier">v</span><span class="special">)-&gt;</span><span class="identifier">Complex</span> <span class="special">{</span>
 112   <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cos</span><span class="special">;</span>
 113   <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">sin</span><span class="special">;</span>
 114   <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exp</span><span class="special">;</span>
 115   <span class="identifier">Real</span> <span class="identifier">sinv</span> <span class="special">=</span> <span class="identifier">sin</span><span class="special">(</span><span class="identifier">v</span><span class="special">);</span>
 116   <span class="identifier">Real</span> <span class="identifier">cosv</span> <span class="special">=</span> <span class="identifier">cos</span><span class="special">(</span><span class="identifier">v</span><span class="special">);</span>
 117
 118   <span class="identifier">Real</span> <span class="identifier">cotv</span> <span class="special">=</span> <span class="identifier">cosv</span><span class="special">/</span><span class="identifier">sinv</span><span class="special">;</span>
 119   <span class="identifier">Real</span> <span class="identifier">cscv</span> <span class="special">=</span> <span class="number">1</span><span class="special">/</span><span class="identifier">sinv</span><span class="special">;</span>
 120   <span class="identifier">Real</span> <span class="identifier">t</span> <span class="special">=</span> <span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">v</span><span class="special">*</span><span class="identifier">cotv</span><span class="special">)*(</span><span class="number">1</span><span class="special">-</span><span class="identifier">v</span><span class="special">*</span><span class="identifier">cotv</span><span class="special">)</span> <span class="special">+</span> <span class="identifier">v</span><span class="special">*</span><span class="identifier">v</span><span class="special">;</span>
 121   <span class="identifier">Real</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">v</span><span class="special">*</span><span class="identifier">cscv</span><span class="special">*</span><span class="identifier">exp</span><span class="special">(-</span><span class="identifier">v</span><span class="special">*</span><span class="identifier">cotv</span><span class="special">);</span>
 122   <span class="identifier">Complex</span> <span class="identifier">den</span> <span class="special">=</span> <span class="identifier">z</span> <span class="special">+</span> <span class="identifier">x</span><span class="special">;</span>
 123   <span class="identifier">Complex</span> <span class="identifier">num</span> <span class="special">=</span> <span class="identifier">t</span><span class="special">*(</span><span class="identifier">z</span><span class="special">/</span><span class="identifier">pi</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">&gt;());</span>
 124   <span class="identifier">Complex</span> <span class="identifier">res</span> <span class="special">=</span> <span class="identifier">num</span><span class="special">/</span><span class="identifier">den</span><span class="special">;</span>
 125   <span class="keyword">return</span> <span class="identifier">res</span><span class="special">;</span>
 126 <span class="special">};</span>
 127
 128 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">quadrature</span><span class="special">::</span><span class="identifier">gauss</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">,</span> <span class="number">30</span><span class="special">&gt;</span> <span class="identifier">integrator</span><span class="special">;</span>
 129 <span class="identifier">Complex</span> <span class="identifier">W</span> <span class="special">=</span> <span class="identifier">integrator</span><span class="special">.</span><span class="identifier">integrate</span><span class="special">(</span><span class="identifier">lw</span><span class="special">,</span> <span class="special">(</span><span class="identifier">Real</span><span class="special">)</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">pi</span><span class="special">&lt;</span><span class="identifier">Real</span><span class="special">&gt;());</span>
 130 </pre>
 131 <h4>
 132 <a name="math_toolkit.gauss.h2"></a>
 133       <span class="phrase"><a name="math_toolkit.gauss.choosing_the_number_of_points"></a></span><a class="link" href="gauss.html#math_toolkit.gauss.choosing_the_number_of_points">Choosing
 134       the number of points</a>
 135     </h4>
 136 <p>
 137       Internally class <code class="computeroutput"><span class="identifier">gauss</span></code> has
 138       pre-computed tables of abscissa and weights for 7, 15, 20, 25 and 30 points
 139       at up to 100-decimal digit precision. That means that using for example, <code class="computeroutput"><span class="identifier">gauss</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="number">30</span><span class="special">&gt;::</span><span class="identifier">integrate</span></code>
 140       incurs absolutely zero set-up overhead from computing the abscissa/weight pairs.
 141       When using multiprecision types with less than 100 digits of precision, then
 142       there is a small initial one time cost, while the abscissa/weight pairs are
 143       constructed from strings.
 144     </p>
 145 <p>
 146       However, for types with higher precision, or numbers of points other than those
 147       given above, the abscissa/weight pairs are computed when first needed and then
 148       cached for future use, which does incur a noticeable overhead. If this is likely
 149       to be an issue, then
 150     </p>
 151 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 152 <li class="listitem">
 153           Defining BOOST_MATH_GAUSS_NO_COMPUTE_ON_DEMAND will result in a compile-time
 154           error, whenever a combination of number type and number of points is used
 155           which does not have pre-computed values.
 156         </li>
 157 <li class="listitem">
 158           There is a program <a href="../../../tools/gauss_kronrod_constants.cpp" target="_top">gauss_kronrod_constants.cpp</a>
 159           which was used to provide the pre-computed values already in gauss.hpp.
 160           The program can be trivially modified to generate code and constants for
 161           other precisions and numbers of points.
 162         </li>
 163 </ul></div>
 164 <h4>
 165 <a name="math_toolkit.gauss.h3"></a>
 166       <span class="phrase"><a name="math_toolkit.gauss.examples"></a></span><a class="link" href="gauss.html#math_toolkit.gauss.examples">Examples</a>
 167     </h4>
 168 <p>
 169       We'll begin by integrating t<sup>2</sup> atan(t) over (0,1) using a 7 term Gauss-Legendre
 170       rule, and begin by defining the function to integrate as a C++ lambda expression:
 171     </p>
 172 <pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">quadrature</span><span class="special">;</span>
 173
 174 <span class="keyword">auto</span> <span class="identifier">f</span> <span class="special">=</span> <span class="special">[](</span><span class="keyword">const</span> <span class="keyword">double</span><span class="special">&amp;</span> <span class="identifier">t</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">t</span> <span class="special">*</span> <span class="identifier">t</span> <span class="special">*</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">atan</span><span class="special">(</span><span class="identifier">t</span><span class="special">);</span> <span class="special">};</span>
 175 </pre>
 176 <p>
 177       Integration is simply a matter of calling the <code class="computeroutput"><span class="identifier">gauss</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span>
 178       <span class="number">7</span><span class="special">&gt;::</span><span class="identifier">integrate</span></code> method:
 179     </p>
 180 <pre class="programlisting"><span class="keyword">double</span> <span class="identifier">Q</span> <span class="special">=</span> <span class="identifier">gauss</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="number">7</span><span class="special">&gt;::</span><span class="identifier">integrate</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span>
 181 </pre>
 182 <p>
 183       Which yields a value 0.2106572512 accurate to 1e-10.
 184     </p>
 185 <p>
 186       For more accurate evaluations, we'll move to a multiprecision type and use
 187       a 20-point integration scheme:
 188     </p>
 189 <pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">cpp_bin_float_quad</span><span class="special">;</span>
 190
 191 <span class="keyword">auto</span> <span class="identifier">f2</span> <span class="special">=</span> <span class="special">[](</span><span class="keyword">const</span> <span class="identifier">cpp_bin_float_quad</span><span class="special">&amp;</span> <span class="identifier">t</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">t</span> <span class="special">*</span> <span class="identifier">t</span> <span class="special">*</span> <span class="identifier">atan</span><span class="special">(</span><span class="identifier">t</span><span class="special">);</span> <span class="special">};</span>
 192
 193 <span class="identifier">cpp_bin_float_quad</span> <span class="identifier">Q2</span> <span class="special">=</span> <span class="identifier">gauss</span><span class="special">&lt;</span><span class="identifier">cpp_bin_float_quad</span><span class="special">,</span> <span class="number">20</span><span class="special">&gt;::</span><span class="identifier">integrate</span><span class="special">(</span><span class="identifier">f2</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span>
 194 </pre>
 195 <p>
 196       Which yields 0.2106572512258069881080923020669, which is accurate to 5e-28.
 197     </p>
 198 </div>
 199 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 200 <td align="left"></td>
 201 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2019 Nikhar
 202       Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
 203       Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
 204       R&#229;de, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
 205       Daryle Walker and Xiaogang Zhang<p>
 206         Distributed under the Boost Software License, Version 1.0. (See accompanying
 207         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>)
 208       </p>
 209 </div></td>
 210 </tr></table>
 211 <hr>
 212 <div class="spirit-nav">
 213 <a accesskey="p" href="trapezoidal.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quadrature.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="gauss_kronrod.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 214 </div>
 215 </body>
 216 </html>