CppAD: A C++ Algorithmic Differentiation Package  20130102
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-12 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 CPPAD_BEGIN_NAMESPACE
00148 /*!
00149 \defgroup time_test_hpp time_test.hpp
00150 \{
00151 \file time_test.hpp
00152 \brief Function that preforms one timing test (for speed of execution).
00153 */
00154 
00155 /*!
00156 Preform one wall clock execution timing test.
00157 
00158 \tparam Test
00159 Either the type <code>void (*)(size_t)</code> or a function object
00160 type that supports the same syntax. 
00161 
00162 \param test
00163 The function, or function object, that supports the operation
00164 <code>test(repeat)</code> where \c repeat is the number of times
00165 to repeat the tests operaiton that is being timed.
00166 
00167 \param time_min
00168 is the minimum amount of time that \c test should take to preform
00169 the repetitions of the operation being timed.
00170 */
00171 template <class Test>
00172 double time_test(Test test, double time_min )
00173 {
00174      size_t repeat = 0;
00175      double s0     = elapsed_seconds();
00176      double s1     = s0;
00177      while( s1 - s0 < time_min )
00178      {    repeat = std::max(size_t(1), 2 * repeat);
00179           s0     = elapsed_seconds();
00180           test(repeat);
00181           s1     = elapsed_seconds();
00182      }
00183      double time = (s1 - s0) / double(repeat);
00184      return time;
00185 }
00186 
00187 /*!
00188 Preform one wall clock execution timing test.
00189 
00190 \tparam Test
00191 Either the type <code>void (*)(size_t, size_t)</code> or a function object
00192 type that supports the same syntax. 
00193 
00194 \param test
00195 The function, or function object, that supports the operation
00196 <code>test(size, repeat)</code> where 
00197 \c is the size for this test and
00198 \c repeat is the number of times
00199 to repeat the tests operaiton that is being timed.
00200 
00201 \param time_min
00202 is the minimum amount of time that \c test should take to preform
00203 the repetitions of the operation being timed.
00204 
00205 \param test_size
00206 will be used for the value of \c size in the call to \c test.
00207 */
00208 template <class Test>
00209 double time_test(Test test, double time_min, size_t test_size)
00210 {
00211      size_t repeat = 0;
00212      double s0     = elapsed_seconds();
00213      double s1     = s0;
00214      while( s1 - s0 < time_min )
00215      {    repeat = std::max(size_t(1), 2 * repeat);
00216           s0     = elapsed_seconds();
00217           test(test_size, repeat);
00218           s1     = elapsed_seconds();
00219      }
00220      double time = (s1 - s0) / double(repeat);
00221      return time;
00222 }
00223 
00224 /*! \} */
00225 CPPAD_END_NAMESPACE
00226 
00227 // END PROGRAM
00228 # endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines