libs/math/doc/sf_and_dist/html/math_toolkit/toolkit/internals2/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="../../../../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="../../../index.html" title="Math Toolkit">
   8 <link rel="up" href="../internals2.html" title="Testing and Development">
   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="../internals2.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 math_toolkit_toolkit_internals2_error_test">
  26 <div class="titlepage"><div><div><h4 class="title">
  27 <a name="math_toolkit.toolkit.internals2.error_test"></a><a class="link" href="error_test.html" title="Relative Error and Testing">Relative
  28         Error and Testing</a>
  29 </h4></div></div></div>
  30 <h5>
  31 <a name="math_toolkit.toolkit.internals2.error_test.h0"></a>
  32           <span><a name="math_toolkit.toolkit.internals2.error_test.synopsis"></a></span><a class="link" href="error_test.html#math_toolkit.toolkit.internals2.error_test.synopsis">Synopsis</a>
  33         </h5>
  34 <p>
  35 </p>
  36 <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>
  37 </pre>
  38 <p>
  39         </p>
  40 <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>
  41 <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>
  42
  43 <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>
  44 <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>
  45 </pre>
  46 <h5>
  47 <a name="math_toolkit.toolkit.internals2.error_test.h1"></a>
  48           <span><a name="math_toolkit.toolkit.internals2.error_test.description"></a></span><a class="link" href="error_test.html#math_toolkit.toolkit.internals2.error_test.description">Description</a>
  49         </h5>
  50 <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>
  51 <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>
  52 </pre>
  53 <p>
  54           Returns the relative error between <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>v</em></span>
  55           using the usual formula:
  56         </p>
  57 <p>
  58           <span class="inlinemediaobject"><img src="../../../../equations/error1.png"></span>
  59         </p>
  60 <p>
  61           In addition the value returned is zero if:
  62         </p>
  63 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
  64 <li class="listitem">
  65               Both <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>v</em></span> are infinite.
  66             </li>
  67 <li class="listitem">
  68               Both <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>v</em></span> are denormalised
  69               numbers or zero.
  70             </li>
  71 </ul></div>
  72 <p>
  73           Otherwise if only one of <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>v</em></span>
  74           is zero then the value returned is 1.
  75         </p>
  76 <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>
  77 <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>
  78 </pre>
  79 <p>
  80           This function is used for testing a function against tabulated test data.
  81         </p>
  82 <p>
  83           The return type contains statistical data on the relative errors (max,
  84           mean, variance, and the number of test cases etc), as well as the row of
  85           test data that caused the largest relative error. Public members of type
  86           test_result are:
  87         </p>
  88 <div class="variablelist">
  89 <p class="title"><b></b></p>
  90 <dl>
  91 <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>
  92 <dd><p>
  93                 Returns the row at which the worst error occurred.
  94               </p></dd>
  95 <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>
  96 <dd><p>
  97                 Returns the smallest relative error found.
  98               </p></dd>
  99 <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>
 100 <dd><p>
 101                 Returns the largest relative error found.
 102               </p></dd>
 103 <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>
 104 <dd><p>
 105                 Returns the mean error found.
 106               </p></dd>
 107 <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>
 108 <dd><p>
 109                 Returns the number of test cases.
 110               </p></dd>
 111 <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>
 112 <dd><p>
 113                 Returns the variance of the errors found.
 114               </p></dd>
 115 <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>
 116 <dd><p>
 117                 Returns the unbiased variance of the errors found.
 118               </p></dd>
 119 <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>
 120 <dd><p>
 121                 Returns the Root Mean Square, or quadratic mean of the errors.
 122               </p></dd>
 123 <dt><span class="term"><code class="computeroutput"><span class="identifier">test_result</span><span class="special">&amp;</span>
 124             <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>
 125 <dd><p>
 126                 Combines two test_result's into a single result.
 127               </p></dd>
 128 </dl>
 129 </div>
 130 <p>
 131           The template parameter of test_result, is the same type as the values in
 132           the two dimensional array passed to function <span class="emphasis"><em>test</em></span>,
 133           roughly 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>.
 134         </p>
 135 <p>
 136           Parameter <span class="emphasis"><em>a</em></span> is a matrix of test data: and must be
 137           a standard library Sequence type, that contains another Sequence type:
 138           typically it will be a two dimensional instance of <code class="literal">boost::array</code>.
 139           Each row of <span class="emphasis"><em>a</em></span> should contain all the parameters that
 140           are passed to the function under test as well as the expected result.
 141         </p>
 142 <p>
 143           Parameter <span class="emphasis"><em>test_func</em></span> is the function under test, it
 144           is invoked with each row of test data in <span class="emphasis"><em>a</em></span>. Typically
 145           type F1 is created with Boost.Lambda: see the example below.
 146         </p>
 147 <p>
 148           Parameter <span class="emphasis"><em>expect_func</em></span> is a functor that extracts the
 149           expected result from a row of test data in <span class="emphasis"><em>a</em></span>. Typically
 150           type F2 is created with Boost.Lambda: see the example below.
 151         </p>
 152 <p>
 153           If the function under test returns a non-finite value when a finite result
 154           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>, and a call to BOOST_ERROR() made
 155           (which means that including this header requires you use Boost.Test). This
 156           is mainly a debugging/development aid (and a good place for a breakpoint).
 157         </p>
 158 <h5>
 159 <a name="math_toolkit.toolkit.internals2.error_test.h2"></a>
 160           <span><a name="math_toolkit.toolkit.internals2.error_test.example"></a></span><a class="link" href="error_test.html#math_toolkit.toolkit.internals2.error_test.example">Example</a>
 161         </h5>
 162 <p>
 163           Suppose we want to test the tgamma and lgamma functions, we can create
 164           a two dimensional matrix of test data, each row is one test case, and contains
 165           three elements: the input value, and the expected results for the tgamma
 166           and lgamma functions respectively.
 167         </p>
 168 <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>
 169    <span class="identifier">factorials</span> <span class="special">=</span> <span class="special">{</span>
 170       <span class="comment">/* big array of test data goes here */</span>
 171    <span class="special">};</span>
 172 </pre>
 173 <p>
 174           Now we can invoke the test function to test tgamma:
 175         </p>
 176 <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>
 177 <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>
 178
 179 <span class="comment">// get a pointer to the function under test:</span>
 180 <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>
 181
 182 <span class="comment">// declare something to hold the result:</span>
 183 <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>
 184 <span class="comment">//</span>
 185 <span class="comment">// and test tgamma against data:</span>
 186 <span class="comment">//</span>
 187 <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">test</span><span class="special">(</span>
 188    <span class="identifier">factorials</span><span class="special">,</span>
 189    <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>
 190    <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>
 191 <span class="special">);</span>
 192 <span class="comment">//</span>
 193 <span class="comment">// Print out some results:</span>
 194 <span class="comment">//</span>
 195 <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>
 196 <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>
 197 <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>
 198 <span class="comment">//</span>
 199 <span class="comment">// same again with lgamma this time:</span>
 200 <span class="comment">//</span>
 201 <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>
 202 <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">test</span><span class="special">(</span>
 203    <span class="identifier">factorials</span><span class="special">,</span>
 204    <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>
 205    <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>
 206 <span class="special">);</span>
 207 <span class="comment">//</span>
 208 <span class="comment">// etc ...</span>
 209 <span class="comment">//</span>
 210 </pre>
 211 </div>
 212 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 213 <td align="left"></td>
 214 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2010 John Maddock, Paul A. Bristow, Hubert Holin, Xiaogang Zhang, Bruno
 215       Lalande, Johan R&#229;de, Gautam Sewani, Thijs van den Berg and Benjamin Sobotta<p>
 216         Distributed under the Boost Software License, Version 1.0. (See accompanying
 217         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>)
 218       </p>
 219 </div></td>
 220 </tr></table>
 221 <hr>
 222 <div class="spirit-nav">
 223 <a accesskey="p" href="minimax.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../internals2.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>
 224 </div>
 225 </body>
 226 </html>