libs/math/doc/html/math_toolkit/internals/error_test.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Relative Error and Testing</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="../internals.html" title="Internal tools">
   9 <link rel="prev" href="minimax.html" title="Minimax Approximations and the Remez Algorithm">
  10 <link rel="next" href="test_data.html" title="Graphing, Profiling, and Generating Test Data for Special Functions">
  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="minimax.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals.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="test_data.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.internals.error_test"></a><a class="link" href="error_test.html" title="Relative Error and Testing">Relative Error and
  28       Testing</a>
  29 </h3></div></div></div>
  30 <h5>
  31 <a name="math_toolkit.internals.error_test.h0"></a>
  32         <span class="phrase"><a name="math_toolkit.internals.error_test.synopsis"></a></span><a class="link" href="error_test.html#math_toolkit.internals.error_test.synopsis">Synopsis</a>
  33       </h5>
  34 <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">tools</span><span class="special">/</span><span class="identifier">test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  35 </pre>
  36 <div class="important"><table border="0" summary="Important">
  37 <tr>
  38 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../../doc/src/images/important.png"></td>
  39 <th align="left">Important</th>
  40 </tr>
  41 <tr><td align="left" valign="top"><p>
  42           The header <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">test</span><span class="special">.</span><span class="identifier">hpp</span></code> is located under <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">include_private</span></code>
  43           and is NOT installed to the usual locations by default; you will need to
  44           add <code class="computeroutput"><span class="identifier">libs</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">include_private</span></code> to your compiler's include
  45           path in order to use this header.
  46         </p></td></tr>
  47 </table></div>
  48 <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>
  49 <span class="identifier">T</span> <span class="identifier">relative_error</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">b</span><span class="special">);</span>
  50
  51 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">A</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F2</span><span class="special">&gt;</span>
  52 <span class="identifier">test_result</span><span class="special">&lt;</span><span class="identifier">see</span><span class="special">-</span><span class="identifier">below</span><span class="special">&gt;</span> <span class="identifier">test</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">F1</span> <span class="identifier">test_func</span><span class="special">,</span> <span class="identifier">F2</span> <span class="identifier">expect_func</span><span class="special">);</span>
  53 </pre>
  54 <h5>
  55 <a name="math_toolkit.internals.error_test.h1"></a>
  56         <span class="phrase"><a name="math_toolkit.internals.error_test.description"></a></span><a class="link" href="error_test.html#math_toolkit.internals.error_test.description">Description</a>
  57       </h5>
  58 <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>
  59 <span class="identifier">T</span> <span class="identifier">relative_error</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">v</span><span class="special">);</span>
  60 </pre>
  61 <p>
  62         Returns the relative error between <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>v</em></span>
  63         using the usual formula:
  64       </p>
  65 <div class="blockquote"><blockquote class="blockquote"><p>
  66           <span class="inlinemediaobject"><img src="../../../equations/error1.svg"></span>
  67
  68         </p></blockquote></div>
  69 <p>
  70         In addition the value returned is zero if:
  71       </p>
  72 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  73 <li class="listitem">
  74             Both <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>v</em></span> are infinite.
  75           </li>
  76 <li class="listitem">
  77             Both <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>v</em></span> are denormalised
  78             numbers or zero.
  79           </li>
  80 </ul></div>
  81 <p>
  82         Otherwise if only one of <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>v</em></span>
  83         is zero then the value returned is 1.
  84       </p>
  85 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">A</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">F2</span><span class="special">&gt;</span>
  86 <span class="identifier">test_result</span><span class="special">&lt;</span><span class="identifier">see</span><span class="special">-</span><span class="identifier">below</span><span class="special">&gt;</span> <span class="identifier">test</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">F1</span> <span class="identifier">test_func</span><span class="special">,</span> <span class="identifier">F2</span> <span class="identifier">expect_func</span><span class="special">);</span>
  87 </pre>
  88 <p>
  89         This function is used for testing a function against tabulated test data.
  90       </p>
  91 <p>
  92         The return type contains statistical data on the relative errors (max, mean,
  93         variance, and the number of test cases etc), as well as the row of test data
  94         that caused the largest relative error. Public members of type test_result
  95         are:
  96       </p>
  97 <div class="variablelist">
  98 <p class="title"><b></b></p>
  99 <dl class="variablelist">
 100 <dt><span class="term"><code class="computeroutput"><span class="keyword">unsigned</span> <span class="identifier">worst</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span></code></span></dt>
 101 <dd><p>
 102               Returns the row at which the worst error occurred.
 103             </p></dd>
 104 <dt><span class="term"><code class="computeroutput"><span class="identifier">T</span> <span class="identifier">min</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span></code></span></dt>
 105 <dd><p>
 106               Returns the smallest relative error found.
 107             </p></dd>
 108 <dt><span class="term"><code class="computeroutput"><span class="identifier">T</span> <span class="identifier">max</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span></code></span></dt>
 109 <dd><p>
 110               Returns the largest relative error found.
 111             </p></dd>
 112 <dt><span class="term"><code class="computeroutput"><span class="identifier">T</span> <span class="identifier">mean</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span></code></span></dt>
 113 <dd><p>
 114               Returns the mean error found.
 115             </p></dd>
 116 <dt><span class="term"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span> <span class="identifier">count</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span></code></span></dt>
 117 <dd><p>
 118               Returns the number of test cases.
 119             </p></dd>
 120 <dt><span class="term"><code class="computeroutput"><span class="identifier">T</span> <span class="identifier">variance</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span></code></span></dt>
 121 <dd><p>
 122               Returns the variance of the errors found.
 123             </p></dd>
 124 <dt><span class="term"><code class="computeroutput"><span class="identifier">T</span> <span class="identifier">variance1</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span></code></span></dt>
 125 <dd><p>
 126               Returns the unbiased variance of the errors found.
 127             </p></dd>
 128 <dt><span class="term"><code class="computeroutput"><span class="identifier">T</span> <span class="identifier">rms</span><span class="special">()</span><span class="keyword">const</span></code></span></dt>
 129 <dd><p>
 130               Returns the Root Mean Square, or quadratic mean of the errors.
 131             </p></dd>
 132 <dt><span class="term"><code class="computeroutput"><span class="identifier">test_result</span><span class="special">&amp;</span>
 133           <span class="keyword">operator</span><span class="special">+=(</span><span class="keyword">const</span> <span class="identifier">test_result</span><span class="special">&amp;</span> <span class="identifier">t</span><span class="special">)</span></code></span></dt>
 134 <dd><p>
 135               Combines two test_result's into a single result.
 136             </p></dd>
 137 </dl>
 138 </div>
 139 <p>
 140         The template parameter of test_result, is the same type as the values in
 141         the two dimensional array passed to function <span class="emphasis"><em>test</em></span>, roughly
 142         that's <code class="computeroutput"><span class="identifier">A</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">::</span><span class="identifier">value_type</span></code>.
 143       </p>
 144 <p>
 145         Parameter <span class="emphasis"><em>a</em></span> is a matrix of test data: and must be a
 146         standard library Sequence type, that contains another Sequence type: typically
 147         it will be a two dimensional instance of <code class="literal">boost::array</code>.
 148         Each row of <span class="emphasis"><em>a</em></span> should contain all the parameters that
 149         are passed to the function under test as well as the expected result.
 150       </p>
 151 <p>
 152         Parameter <span class="emphasis"><em>test_func</em></span> is the function under test, it is
 153         invoked with each row of test data in <span class="emphasis"><em>a</em></span>. Typically type
 154         F1 is created with Boost.Lambda: see the example below.
 155       </p>
 156 <p>
 157         Parameter <span class="emphasis"><em>expect_func</em></span> is a functor that extracts the
 158         expected result from a row of test data in <span class="emphasis"><em>a</em></span>. Typically
 159         type F2 is created with Boost.Lambda: see the example below.
 160       </p>
 161 <p>
 162         If the function under test returns a non-finite value when a finite result
 163         is expected, or if a gross error is found, then a message is sent to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code>,
 164         and a call to BOOST_ERROR() made (which means that including this header
 165         requires you use Boost.Test). This is mainly a debugging/development aid
 166         (and a good place for a breakpoint).
 167       </p>
 168 <h5>
 169 <a name="math_toolkit.internals.error_test.h2"></a>
 170         <span class="phrase"><a name="math_toolkit.internals.error_test.example"></a></span><a class="link" href="error_test.html#math_toolkit.internals.error_test.example">Example</a>
 171       </h5>
 172 <p>
 173         Suppose we want to test the <code class="computeroutput"><span class="identifier">tgamma</span></code>
 174         and <code class="computeroutput"><span class="identifier">lgamma</span></code> functions, we
 175         can create a two-dimensional matrix of test data, each row is one test case,
 176         and contains three elements: the input value, and the expected results for
 177         the <code class="computeroutput"><span class="identifier">tgamma</span></code> and <code class="computeroutput"><span class="identifier">lgamma</span></code> functions respectively.
 178       </p>
 179 <pre class="programlisting"><span class="keyword">static</span> <span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">TestType</span><span class="special">,</span> <span class="number">3</span><span class="special">&gt;,</span> <span class="identifier">NumberOfTests</span><span class="special">&gt;</span>
 180    <span class="identifier">factorials</span> <span class="special">=</span> <span class="special">{</span>
 181       <span class="comment">/* big array of test data goes here */</span>
 182    <span class="special">};</span>
 183 </pre>
 184 <p>
 185         Now we can invoke the test function to test tgamma:
 186       </p>
 187 <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">tools</span><span class="special">;</span>
 188 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">lambda</span><span class="special">;</span>
 189
 190 <span class="comment">// get a pointer to the function under test:</span>
 191 <span class="identifier">TestType</span> <span class="special">(*</span><span class="identifier">funcp</span><span class="special">)(</span><span class="identifier">TestType</span><span class="special">)</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">tgamma</span><span class="special">;</span>
 192
 193 <span class="comment">// declare something to hold the result:</span>
 194 <span class="identifier">test_result</span><span class="special">&lt;</span><span class="identifier">TestType</span><span class="special">&gt;</span> <span class="identifier">result</span><span class="special">;</span>
 195 <span class="comment">//</span>
 196 <span class="comment">// and test tgamma against data:</span>
 197 <span class="comment">//</span>
 198 <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">test</span><span class="special">(</span>
 199    <span class="identifier">factorials</span><span class="special">,</span>
 200    <span class="identifier">bind</span><span class="special">(</span><span class="identifier">funcp</span><span class="special">,</span> <span class="identifier">ret</span><span class="special">&lt;</span><span class="identifier">TestType</span><span class="special">&gt;(</span><span class="identifier">_1</span><span class="special">[</span><span class="number">0</span><span class="special">])),</span> <span class="comment">// calls tgamma with factorials[row][0]</span>
 201    <span class="identifier">ret</span><span class="special">&lt;</span><span class="identifier">TestType</span><span class="special">&gt;(</span><span class="identifier">_1</span><span class="special">[</span><span class="number">1</span><span class="special">])</span>               <span class="comment">// extracts the expected result from factorials[row][1]</span>
 202 <span class="special">);</span>
 203 <span class="comment">//</span>
 204 <span class="comment">// Print out some results:</span>
 205 <span class="comment">//</span>
 206 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"The Mean was "</span> <span class="special">&lt;&lt;</span> <span class="identifier">result</span><span class="special">.</span><span class="identifier">mean</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 207 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"The worst error was "</span> <span class="special">&lt;&lt;</span> <span class="special">(</span><span class="identifier">result</span><span class="special">.</span><span class="identifier">max</span><span class="special">)()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 208 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"The worst error was at row "</span> <span class="special">&lt;&lt;</span> <span class="identifier">result</span><span class="special">.</span><span class="identifier">worst_case</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 209 <span class="comment">//</span>
 210 <span class="comment">// same again with lgamma this time:</span>
 211 <span class="comment">//</span>
 212 <span class="identifier">funcp</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">lgamma</span><span class="special">;</span>
 213 <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">test</span><span class="special">(</span>
 214    <span class="identifier">factorials</span><span class="special">,</span>
 215    <span class="identifier">bind</span><span class="special">(</span><span class="identifier">funcp</span><span class="special">,</span> <span class="identifier">ret</span><span class="special">&lt;</span><span class="identifier">TestType</span><span class="special">&gt;(</span><span class="identifier">_1</span><span class="special">[</span><span class="number">0</span><span class="special">])),</span> <span class="comment">// calls tgamma with factorials[row][0]</span>
 216    <span class="identifier">ret</span><span class="special">&lt;</span><span class="identifier">TestType</span><span class="special">&gt;(</span><span class="identifier">_1</span><span class="special">[</span><span class="number">2</span><span class="special">])</span>               <span class="comment">// extracts the expected result from factorials[row][2]</span>
 217 <span class="special">);</span>
 218 <span class="comment">//</span>
 219 <span class="comment">// etc ...</span>
 220 <span class="comment">//</span>
 221 </pre>
 222 </div>
 223 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 224 <td align="left"></td>
 225 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2019 Nikhar
 226       Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
 227       Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
 228       R&#229;de, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
 229       Daryle Walker and Xiaogang Zhang<p>
 230         Distributed under the Boost Software License, Version 1.0. (See accompanying
 231         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>)
 232       </p>
 233 </div></td>
 234 </tr></table>
 235 <hr>
 236 <div class="spirit-nav">
 237 <a accesskey="p" href="minimax.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals.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="test_data.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 238 </div>
 239 </body>
 240 </html>