<?xml version='1.0'?>
<html xmlns='http://www.w3.org/1999/xhtml'
      xmlns:math='http://www.w3.org/1998/Math/MathML'
>
<head>
<title>Determine Amount of Time to Execute a Test</title>
<meta name="description" id="description" content="Determine Amount of Time to Execute a Test"/>
<meta name="keywords" id="keywords" content=" time_test test speed time "/>
<style type='text/css'>
body { color : black }
body { background-color : white }
A:link { color : blue }
A:visited { color : purple }
A:active { color : purple }
</style>
<script type='text/javascript' language='JavaScript' src='_time_test_xml.js'>
</script>
</head>
<body>
<table><tr>
<td>
<a href="http://www.coin-or.org/CppAD/" target="_top"><img border="0" src="_image.gif"/></a>
</td>
<td><a href="speed_program.cpp.xml" target="_top">Prev</a>
</td><td><a href="elapsed_seconds.xml" target="_top">Next</a>
</td><td>
<select onchange='choose_across0(this)'>
<option>Index-&gt;</option>
<option>contents</option>
<option>reference</option>
<option>index</option>
<option>search</option>
<option>external</option>
</select>
</td>
<td>
<select onchange='choose_up0(this)'>
<option>Up-&gt;</option>
<option>CppAD</option>
<option>library</option>
<option>time_test</option>
</select>
</td>
<td>
<select onchange='choose_down2(this)'>
<option>CppAD-&gt;</option>
<option>Install</option>
<option>Introduction</option>
<option>AD</option>
<option>ADFun</option>
<option>preprocessor</option>
<option>multi_thread</option>
<option>library</option>
<option>ipopt_solve</option>
<option>Example</option>
<option>speed</option>
<option>Appendix</option>
</select>
</td>
<td>
<select onchange='choose_down1(this)'>
<option>library-&gt;</option>
<option>ErrorHandler</option>
<option>NearEqual</option>
<option>speed_test</option>
<option>SpeedTest</option>
<option>time_test</option>
<option>NumericType</option>
<option>CheckNumericType</option>
<option>SimpleVector</option>
<option>CheckSimpleVector</option>
<option>nan</option>
<option>pow_int</option>
<option>Poly</option>
<option>LuDetAndSolve</option>
<option>RombergOne</option>
<option>RombergMul</option>
<option>Runge45</option>
<option>Rosen34</option>
<option>OdeErrControl</option>
<option>OdeGear</option>
<option>OdeGearControl</option>
<option>CppAD_vector</option>
<option>thread_alloc</option>
<option>index_sort</option>
<option>BenderQuad</option>
<option>opt_val_hes</option>
<option>LuRatio</option>
</select>
</td>
<td>
<select onchange='choose_down0(this)'>
<option>time_test-&gt;</option>
<option>elapsed_seconds</option>
<option>time_test.cpp</option>
</select>
</td>
<td>
<select onchange='choose_current0(this)'>
<option>Headings-&gt;</option>
<option>Syntax</option>
<option>Purpose</option>
<option>Motivation</option>
<option>Include</option>
<option>test</option>
<option>---..size</option>
<option>---..repeat</option>
<option>time_min</option>
<option>test_size</option>
<option>time</option>
<option>Timing</option>
<option>Example</option>
</select>
</td>
</tr></table><br/>







<center><b><big><big>Determine Amount of Time to Execute a Test</big></big></b></center>
<br/>
<b><big><a name="Syntax" id="Syntax">Syntax</a></big></b>

<br/>

<code><font color="blue"><span style='white-space: nowrap'>#&#xA0;include&#xA0;&lt;cppad/time_test.hpp&gt;<br/>
</span></font></code>

<code><i><font color="black"><span style='white-space: nowrap'>time</span></font></i><font color="blue"><span style='white-space: nowrap'>&#xA0;=&#xA0;time_test(</span></font><i><font color="black"><span style='white-space: nowrap'>test</span></font></i><font color="blue"><span style='white-space: nowrap'>,&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>time_min</span></font></i><font color="blue"><span style='white-space: nowrap'>)</span></font></code>


<code><i><font color="black"><span style='white-space: nowrap'>time</span></font></i><font color="blue"><span style='white-space: nowrap'>&#xA0;=&#xA0;time_test(</span></font><i><font color="black"><span style='white-space: nowrap'>test</span></font></i><font color="blue"><span style='white-space: nowrap'>,&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>time_min</span></font></i><font color="blue"><span style='white-space: nowrap'>,&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>test_size</span></font></i><font color="blue"><span style='white-space: nowrap'>)</span></font></code>


<br/>
<br/>
<b><big><a name="Purpose" id="Purpose">Purpose</a></big></b>
<br/>
The <code><font color="blue">time_test</font></code> function executes a timing test
and reports the amount of wall clock time for execution.

<br/>
<br/>
<b><big><a name="Motivation" id="Motivation">Motivation</a></big></b>
<br/>
It is important to separate small calculation units
and test them individually.
This way individual changes can be tested in the context of the
routine that they are in.
On many machines, accurate timing of a very short execution 
sequences is not possible.
In addition,
there may be set up and tear down time for a test that
we do not really want included in the timing.
For this reason <code><font color="blue">time_test</font></code>
automatically determines how many times to 
repeat the section of the test that we wish to time.

<br/>
<br/>
<b><big><a name="Include" id="Include">Include</a></big></b>
<br/>
The file <code><font color="blue">cppad/time_test.hpp</font></code> defines the 
<code><font color="blue">time_test</font></code> function.
This file is included by <code><font color="blue">cppad/cppad.hpp</font></code>
and it can also be included separately with out the rest of 
the <code><font color="blue">CppAD</font></code> routines.

<br/>
<br/>
<b><big><a name="test" id="test">test</a></big></b>
<br/>
The <code><font color="blue">time_test</font></code> argument 
<code><i><font color="black"><span style='white-space: nowrap'>test</span></font></i></code>
 is a function,
or function object.
In the case where 
<code><i><font color="black"><span style='white-space: nowrap'>test_size</span></font></i></code>
 is not present, 

<code><i><font color="black"><span style='white-space: nowrap'>test</span></font></i></code>
 supports the syntax

<code><font color="blue"><span style='white-space: nowrap'><br/>
&#xA0;&#xA0;&#xA0;&#xA0;&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>test</span></font></i><font color="blue"><span style='white-space: nowrap'>(</span></font><i><font color="black"><span style='white-space: nowrap'>repeat</span></font></i><font color="blue"><span style='white-space: nowrap'>)<br/>
</span></font></code>
In the case where 
<code><i><font color="black"><span style='white-space: nowrap'>test_size</span></font></i></code>
 is present, 

<code><i><font color="black"><span style='white-space: nowrap'>test</span></font></i></code>
 supports the syntax

<code><font color="blue"><span style='white-space: nowrap'><br/>
&#xA0;&#xA0;&#xA0;&#xA0;&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>test</span></font></i><font color="blue"><span style='white-space: nowrap'>(</span></font><i><font color="black"><span style='white-space: nowrap'>size</span></font></i><font color="blue"><span style='white-space: nowrap'>,&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>repeat</span></font></i><font color="blue"><span style='white-space: nowrap'>)<br/>
</span></font></code>
In either case, the return value for 
<code><i><font color="black"><span style='white-space: nowrap'>test</span></font></i></code>
 is <code><font color="blue">void</font></code>.

<br/>
<br/>
<b><a name="test.size" id="test.size">size</a></b>
<br/>
If the argument 
<code><i><font color="black"><span style='white-space: nowrap'>size</span></font></i></code>
 is present,
it has prototype

<code><font color="blue"><span style='white-space: nowrap'><br/>
&#xA0;&#xA0;&#xA0;&#xA0;&#xA0;size_t&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>size</span></font></i><font color="blue"><span style='white-space: nowrap'><br/>
</span></font></code>
and is equal to the 
<code><i><font color="black"><span style='white-space: nowrap'>test_size</span></font></i></code>
 argument to <code><font color="blue">time_test</font></code>.

<br/>
<br/>
<b><a name="test.repeat" id="test.repeat">repeat</a></b>
<br/>
The 
<code><i><font color="black"><span style='white-space: nowrap'>test</span></font></i></code>
 argument 
<code><i><font color="black"><span style='white-space: nowrap'>repeat</span></font></i></code>
 has prototype

<code><font color="blue"><span style='white-space: nowrap'><br/>
&#xA0;&#xA0;&#xA0;&#xA0;&#xA0;size_t&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>repeat</span></font></i><font color="blue"><span style='white-space: nowrap'><br/>
</span></font></code>
It will be equal to the 
<code><i><font color="black"><span style='white-space: nowrap'>size</span></font></i></code>
 argument to <code><font color="blue">time_test</font></code>.

<br/>
<br/>
<b><big><a name="time_min" id="time_min">time_min</a></big></b>
<br/>
The argument 
<code><i><font color="black"><span style='white-space: nowrap'>time_min</span></font></i></code>
 has prototype

<code><font color="blue"><span style='white-space: nowrap'><br/>
&#xA0;&#xA0;&#xA0;&#xA0;&#xA0;double&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>time_min</span></font></i><font color="blue"><span style='white-space: nowrap'><br/>
</span></font></code>
It specifies the minimum amount of time in seconds
that the 
<code><i><font color="black"><span style='white-space: nowrap'>test</span></font></i></code>
 routine should take.
The 
<code><i><font color="black"><span style='white-space: nowrap'>repeat</span></font></i></code>
 argument to 
<code><i><font color="black"><span style='white-space: nowrap'>test</span></font></i></code>
 is increased
until this amount of execution time (or more) is reached.

<br/>
<br/>
<b><big><a name="test_size" id="test_size">test_size</a></big></b>
<br/>
This argument has prototype

<code><font color="blue"><span style='white-space: nowrap'><br/>
&#xA0;&#xA0;&#xA0;&#xA0;&#xA0;size_t&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>test_size</span></font></i><font color="blue"><span style='white-space: nowrap'><br/>
</span></font></code>
It specifies the 
<code><i><font color="black"><span style='white-space: nowrap'>size</span></font></i></code>
 argument to 
<code><i><font color="black"><span style='white-space: nowrap'>test</span></font></i></code>
.

<br/>
<br/>
<b><big><a name="time" id="time">time</a></big></b>
<br/>
The return value 
<code><i><font color="black"><span style='white-space: nowrap'>time</span></font></i></code>
 has prototype

<code><font color="blue"><span style='white-space: nowrap'><br/>
&#xA0;&#xA0;&#xA0;&#xA0;&#xA0;double&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>time</span></font></i><font color="blue"><span style='white-space: nowrap'><br/>
</span></font></code>
and is the number of wall clock seconds that it took
to execute 
<code><i><font color="black"><span style='white-space: nowrap'>test</span></font></i></code>
 divided by the value used for 
<code><i><font color="black"><span style='white-space: nowrap'>repeat</span></font></i></code>
.

<br/>
<br/>
<b><big><a name="Timing" id="Timing">Timing</a></big></b>
<br/>
The routine <a href="elapsed_seconds.xml" target="_top"><span style='white-space: nowrap'>elapsed_seconds</span></a>
 will be used to determine the
amount of time it took to execute the test.


<br/>
<br/>
<b><big><a name="Example" id="Example">Example</a></big></b>
<br/>
The routine <a href="time_test.cpp.xml" target="_top"><span style='white-space: nowrap'>time_test.cpp</span></a>
 is an example and test
of <code><font color="blue">time_test</font></code>.


<hr/>Input File: cppad/time_test.hpp

</body>
</html>
