CppAD: A C++ Algorithmic Differentiation Package  20130918
time_test.hpp
Go to the documentation of this file.
00001 /* $Id$ */
00002 # ifndef CPPAD_TIME_TEST_INCLUDED
00003 # define CPPAD_TIME_TEST_INCLUDED
00004 
00005 /* --------------------------------------------------------------------------
00006 CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-14 Bradley M. Bell
00007 
00008 CppAD is distributed under multiple licenses. This distribution is under
00009 the terms of the 
00010                     Eclipse Public License Version 1.0.
00011 
00012 A copy of this license is included in the COPYING file of this distribution.
00013 Please visit http://www.coin-or.org/CppAD/ for information on other licenses.
00014 -------------------------------------------------------------------------- */
00015 
00016 /*
00017 $begin time_test$$
00018 $spell
00019      gettimeofday
00020      vec
00021      cppad.hpp
00022      Microsoft
00023      namespace
00024      std
00025      const
00026      cout
00027      ctime
00028      ifdef
00029      const
00030      endif
00031      cpp
00032 $$
00033 
00034 $index time_test$$
00035 $index test, speed$$
00036 $index test, time$$
00037 
00038 $section Determine Amount of Time to Execute a Test$$
00039 
00040 $head Syntax$$
00041 $codei%# include <cppad/time_test.hpp>
00042 %$$
00043 $icode%time% = time_test(%test%, %time_min%)%$$
00044 $icode%time% = time_test(%test%, %time_min%, %test_size%)%$$
00045 
00046 $head Purpose$$
00047 The $code time_test$$ function executes a timing test
00048 and reports the amount of wall clock time for execution.
00049 
00050 $head Motivation$$
00051 It is important to separate small calculation units
00052 and test them individually.
00053 This way individual changes can be tested in the context of the
00054 routine that they are in.
00055 On many machines, accurate timing of a very short execution 
00056 sequences is not possible.
00057 In addition,
00058 there may be set up and tear down time for a test that
00059 we do not really want included in the timing.
00060 For this reason $code time_test$$
00061 automatically determines how many times to 
00062 repeat the section of the test that we wish to time.
00063 
00064 $head Include$$
00065 The file $code cppad/time_test.hpp$$ defines the 
00066 $code time_test$$ function.
00067 This file is included by $code cppad/cppad.hpp$$
00068 and it can also be included separately with out the rest of 
00069 the $code CppAD$$ routines.
00070 
00071 $head test$$
00072 The $code time_test$$ argument $icode test$$ is a function,
00073 or function object.
00074 In the case where $icode test_size$$ is not present, 
00075 $icode test$$ supports the syntax
00076 $codei%
00077      %test%(%repeat%)
00078 %$$
00079 In the case where $icode test_size$$ is present, 
00080 $icode test$$ supports the syntax
00081 $codei%
00082      %test%(%size%, %repeat%)
00083 %$$
00084 In either case, the return value for $icode test$$ is $code void$$.
00085 
00086 $subhead size$$
00087 If the argument $icode size$$ is present,
00088 it has prototype
00089 $codei%
00090      size_t %size%
00091 %$$
00092 and is equal to the $icode test_size$$ argument to $code time_test$$.
00093 
00094 $subhead repeat$$
00095 The $icode test$$ argument $icode repeat$$ has prototype
00096 $codei%
00097      size_t %repeat%
00098 %$$
00099 It will be equal to the $icode size$$ argument to $code time_test$$.
00100 
00101 $head time_min$$
00102 The argument $icode time_min$$ has prototype
00103 $codei%
00104      double %time_min%
00105 %$$
00106 It specifies the minimum amount of time in seconds
00107 that the $icode test$$ routine should take.
00108 The $icode repeat$$ argument to $icode test$$ is increased
00109 until this amount of execution time (or more) is reached.
00110 
00111 $head test_size$$
00112 This argument has prototype
00113 $codei%
00114      size_t %test_size%
00115 %$$
00116 It specifies the $icode size$$ argument to $icode test$$.
00117 
00118 $head time$$
00119 The return value $icode time$$ has prototype
00120 $codei%
00121      double %time%
00122 %$$ 
00123 and is the number of wall clock seconds that it took
00124 to execute $icode test$$ divided by the value used for $icode repeat$$.
00125 
00126 $head Timing$$
00127 The routine $cref elapsed_seconds$$ will be used to determine the
00128 amount of time it took to execute the test.
00129 
00130 $children%
00131      cppad/elapsed_seconds.hpp%
00132      speed/example/time_test.cpp
00133 %$$
00134 $head Example$$
00135 The routine $cref time_test.cpp$$ is an example and test
00136 of $code time_test$$.
00137 
00138 $end
00139 -----------------------------------------------------------------------
00140 */
00141 
00142 # include <cstddef>
00143 # include <cmath>
00144 # include <cppad/elapsed_seconds.hpp>
00145 # include <cppad/local/define.hpp>
00146 
00147 namespace CppAD { // BEGIN_CPPAD_NAMESPACE
00148 /*!
00149 \file time_test.hpp
00150 \brief Function that preforms one timing test (for speed of execution).
00151 */
00152 
00153 /*!
00154 Preform one wall clock execution timing test.
00155 
00156 \tparam Test
00157 Either the type <code>void (*)(size_t)</code> or a function object
00158 type that supports the same syntax. 
00159 
00160 \param test
00161 The function, or function object, that supports the operation
00162 <code>test(repeat)</code> where \c repeat is the number of times
00163 to repeat the tests operaiton that is being timed.
00164 
00165 \param time_min
00166 is the minimum amount of time that \c test should take to preform
00167 the repetitions of the operation being timed.
00168 */
00169 template <class Test>
00170 double time_test(Test test, double time_min )
00171 {
00172      size_t repeat = 0;
00173      double s0     = elapsed_seconds();
00174      double s1     = s0;
00175      while( s1 - s0 < time_min )
00176      {    repeat = std::max(size_t(1), 2 * repeat);
00177           s0     = elapsed_seconds();
00178           test(repeat);
00179           s1     = elapsed_seconds();
00180      }
00181      double time = (s1 - s0) / double(repeat);
00182      return time;
00183 }
00184 
00185 /*!
00186 Preform one wall clock execution timing test.
00187 
00188 \tparam Test
00189 Either the type <code>void (*)(size_t, size_t)</code> or a function object
00190 type that supports the same syntax. 
00191 
00192 \param test
00193 The function, or function object, that supports the operation
00194 <code>test(size, repeat)</code> where 
00195 \c is the size for this test and
00196 \c repeat is the number of times
00197 to repeat the tests operaiton that is being timed.
00198 
00199 \param time_min
00200 is the minimum amount of time that \c test should take to preform
00201 the repetitions of the operation being timed.
00202 
00203 \param test_size
00204 will be used for the value of \c size in the call to \c test.
00205 */
00206 template <class Test>
00207 double time_test(Test test, double time_min, size_t test_size)
00208 {
00209      size_t repeat = 0;
00210      double s0     = elapsed_seconds();
00211      double s1     = s0;
00212      while( s1 - s0 < time_min )
00213      {    repeat = std::max(size_t(1), 2 * repeat);
00214           s0     = elapsed_seconds();
00215           test(test_size, repeat);
00216           s1     = elapsed_seconds();
00217      }
00218      double time = (s1 - s0) / double(repeat);
00219      return time;
00220 }
00221 
00222 } // END_CPPAD_NAMESPACE
00223 
00224 // END PROGRAM
00225 # endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines