00001 # ifndef CPPAD_FUN_CHECK_INCLUDED 00002 # define CPPAD_FUN_CHECK_INCLUDED 00003 00004 /* -------------------------------------------------------------------------- 00005 CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-07 Bradley M. Bell 00006 00007 CppAD is distributed under multiple licenses. This distribution is under 00008 the terms of the 00009 Common Public License Version 1.0. 00010 00011 A copy of this license is included in the COPYING file of this distribution. 00012 Please visit http://www.coin-or.org/CppAD/ for information on other licenses. 00013 -------------------------------------------------------------------------- */ 00014 00015 /* 00016 $begin FunCheck$$ 00017 $spell 00018 exp 00019 bool 00020 const 00021 Taylor 00022 $$ 00023 00024 $index FunCheck$$ 00025 $index check, ADFun$$ 00026 $index ADFun, check$$ 00027 00028 $section Check an ADFun Sequence of Operations$$ 00029 00030 $head Syntax$$ 00031 $syntax%%ok% = FunCheck(%f%, %g%, %x%, %r%, %a%)%$$ 00032 $pre 00033 $$ 00034 $bold See Also$$ 00035 $xref/CompareChange/$$ 00036 00037 00038 $head Purpose$$ 00039 We use $latex F : B^n \rightarrow B^m$$ to denote the 00040 $xref/glossary/AD Function/AD function/$$ corresponding to $italic f$$. 00041 We use $latex G : B^n \rightarrow B^m$$ to denote the 00042 function corresponding to the C++ function object $italic g$$. 00043 This routine check if 00044 $latex \[ 00045 F(x) = G(x) 00046 \]$$ 00047 If $latex F(x) \neq G(x)$$, the 00048 $xref/glossary/Operation/Sequence/operation sequence/1/$$ 00049 corresponding to $italic f$$ does not represents the algorithm used 00050 by $italic g$$ to calculate values for $latex G$$ 00051 (see $xref/FunCheck/Discussion/Discussion/$$ below). 00052 00053 $head f$$ 00054 The $code FunCheck$$ argument $italic f$$ has prototype 00055 $syntax% 00056 ADFun<%Base%> %f% 00057 %$$ 00058 Note that the $xref/ADFun/$$ object $italic f$$ is not $code const$$ 00059 (see $xref/FunCheck/FunCheck Uses Forward/Forward/$$ below). 00060 00061 $head g$$ 00062 The $code FunCheck$$ argument $italic g$$ has prototype 00063 $syntax% 00064 %Fun% &%g% 00065 %$$ 00066 ($italic Fun$$ is defined the properties of $italic g$$). 00067 The C++ function object $italic g$$ supports the syntax 00068 $syntax% 00069 %y% = %g%(%x%) 00070 %$$ 00071 which computes $latex y = G(x)$$. 00072 00073 $subhead x$$ 00074 The $italic g$$ argument $italic x$$ has prototype 00075 $syntax% 00076 const %Vector% &%x% 00077 %$$ 00078 (see $xref/FunCheck/Vector/Vector/$$ below) 00079 and its size 00080 must be equal to $italic n$$, the dimension of the 00081 $xref/SeqProperty/Domain/domain/$$ space for $italic f$$. 00082 00083 $head y$$ 00084 The $italic g$$ result $italic y$$ has prototype 00085 $syntax% 00086 %Vector% %y% 00087 %$$ 00088 and its value is $latex G(x)$$. 00089 The size of $italic y$$ 00090 is equal to $italic m$$, the dimension of the 00091 $xref/SeqProperty/Range/range/$$ space for $italic f$$. 00092 00093 $head x$$ 00094 The $code FunCheck$$ argument $italic x$$ has prototype 00095 $syntax% 00096 const %Vector% &%x% 00097 %$$ 00098 and its size 00099 must be equal to $italic n$$, the dimension of the 00100 $xref/SeqProperty/Domain/domain/$$ space for $italic f$$. 00101 This specifies that point at which to compare the values 00102 calculated by $italic f$$ and $italic G$$. 00103 00104 $head r$$ 00105 The $code FunCheck$$ argument $italic r$$ has prototype 00106 $syntax% 00107 const %Base% &%r% 00108 %$$ 00109 It specifies the relative error the element by element 00110 comparison of the value of $latex F(x)$$ and $latex G(x)$$. 00111 00112 $head a$$ 00113 The $code FunCheck$$ argument $italic a$$ has prototype 00114 $syntax% 00115 const %Base% &%a% 00116 %$$ 00117 It specifies the absolute error the element by element 00118 comparison of the value of $latex F(x)$$ and $latex G(x)$$. 00119 00120 $head ok$$ 00121 The $code FunCheck$$ result $italic ok$$ has prototype 00122 $syntax% 00123 bool %ok% 00124 %$$ 00125 It is true, if for $latex i = 0 , \ldots , m-1$$ 00126 either the relative error bound is satisfied 00127 $latex \[ 00128 | F_i (x) - G_i (x) | 00129 \leq 00130 r ( | F_i (x) | + | G_i (x) | ) 00131 \] $$ 00132 or the absolute error bound is satisfied 00133 $latex \[ 00134 | F_i (x) - G_i (x) | \leq a 00135 \] $$ 00136 It is false if for some $latex (i, j)$$ neither 00137 of these bounds is satisfied. 00138 00139 $head Vector$$ 00140 The type $italic Vector$$ must be a $xref/SimpleVector/$$ class with 00141 $xref/SimpleVector/Elements of Specified Type/elements of type/$$ 00142 $italic Base$$. 00143 The routine $xref/CheckSimpleVector/$$ will generate an error message 00144 if this is not the case. 00145 00146 $head FunCheck Uses Forward$$ 00147 After each call to $xref/Forward/$$, 00148 the object $italic f$$ contains the corresponding 00149 $xref/glossary/Taylor Coefficient/Taylor coefficients/$$. 00150 After $code FunCheck$$, 00151 the previous calls to $xref/Forward/$$ are undefined. 00152 00153 $head Discussion$$ 00154 Suppose that the algorithm corresponding to $italic g$$ contains 00155 $syntax% 00156 if( %x% >= 0 ) 00157 %y% = exp(%x%) 00158 else %y% = exp(-%x%) 00159 %$$ 00160 where $italic x$$ and $italic y$$ are $syntax%AD<double>%$$ objects. 00161 It follows that the 00162 AD of $code double$$ $xref/glossary/Operation/Sequence/operation sequence/1/$$ 00163 depends on the value of $italic x$$. 00164 If the sequence of operations stored in $italic f$$ corresponds to 00165 $italic g$$ with $latex x \geq 0$$, 00166 the function values computed using $italic f$$ when $latex x < 0$$ 00167 will not agree with the function values computed by $latex g$$. 00168 This is because the operation sequence corresponding to $italic g$$ changed 00169 (and hence the object $italic f$$ does not represent the function 00170 $latex G$$ for this value of $italic x$$). 00171 In this case, you probably want to re-tape the calculations 00172 performed by $italic g$$ with the 00173 $cref/independent variables/glossary/Tape/Independent Variable/$$ 00174 equal to the values in $italic x$$ 00175 (so AD operation sequence properly represents the algorithm 00176 for this value of independent variables). 00177 00178 00179 $head Example$$ 00180 $children% 00181 example/fun_check.cpp 00182 %$$ 00183 The file 00184 $xref/FunCheck.cpp/$$ 00185 contains an example and test of this function. 00186 It returns true if it succeeds and false otherwise. 00187 00188 $end 00189 --------------------------------------------------------------------------- 00190 */ 00191 00192 namespace CppAD { 00193 template <class Base, class Fun, class Vector> 00194 bool FunCheck( 00195 ADFun<Base> &f , 00196 Fun &g , 00197 const Vector &x , 00198 const Base &r , 00199 const Base &a ) 00200 { bool ok = true; 00201 00202 size_t m = f.Range(); 00203 Vector yf = f.Forward(0, x); 00204 Vector yg = g(x); 00205 00206 size_t i; 00207 for(i = 0; i < m; i++) 00208 ok &= NearEqual(yf[i], yg[i], r, a); 00209 return ok; 00210 } 00211 } 00212 00213 # endif