CppAD: A C++ Algorithmic Differentiation Package 20110419
near_equal_ext.hpp
Go to the documentation of this file.
00001 /* $Id$ */
00002 # ifndef CPPAD_NEAR_EQUAL_EXT_INCLUDED
00003 # define CPPAD_NEAR_EQUAL_EXT_INCLUDED
00004 
00005 /* --------------------------------------------------------------------------
00006 CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-08 Bradley M. Bell
00007 
00008 CppAD is distributed under multiple licenses. This distribution is under
00009 the terms of the 
00010                     Common 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 $begin NearEqualExt$$
00017 $spell
00018         cout
00019         endl
00020         Microsoft
00021         std
00022         Cpp
00023         namespace
00024         const
00025         bool
00026 $$
00027 
00028 $section Compare AD and Base Objects for Nearly Equal$$
00029 
00030 $index NearEqual, AD with Base$$
00031 
00032 $head Syntax$$
00033 $syntax%%b% = NearEqual(%x%, %y%, %r%, %a%)%$$
00034 
00035 
00036 $head Purpose$$
00037 The routine $xref/NearEqual/$$ determines if two objects of
00038 the same type are nearly.
00039 This routine is extended to the case where one object can have type
00040 $italic Type$$ while the other can have type
00041 $syntax%AD<%Type%>%$$ or
00042 $syntax%AD< std::complex<%Type%> >%$$.
00043 
00044 $head x$$
00045 The arguments $italic x$$ 
00046 has one of the following possible prototypes:
00047 $syntax%
00048         const %Type%                     &%x%
00049         const AD<%Type%>                 &%x%
00050         const AD< std::complex<%Type%> > &%x%
00051 %$$
00052 
00053 $head y$$
00054 The arguments $italic y$$ 
00055 has one of the following possible prototypes:
00056 $syntax%
00057         const %Type%                     &%y%
00058         const AD<%Type%>                 &%y%
00059         const AD< std::complex<%Type%> > &%x%
00060 %$$
00061 
00062 
00063 $head r$$
00064 The relative error criteria $italic r$$ has prototype
00065 $syntax%
00066         const %Type% &%r%
00067 %$$
00068 It must be greater than or equal to zero.
00069 The relative error condition is defined as:
00070 $latex \[
00071         \frac{ | x - y | } { |x| + |y| } \leq r
00072 \] $$
00073 
00074 $head a$$
00075 The absolute error criteria $italic a$$ has prototype
00076 $syntax%
00077         const %Type% &%a%
00078 %$$
00079 It must be greater than or equal to zero.
00080 The absolute error condition is defined as:
00081 $latex \[
00082         | x - y | \leq a
00083 \] $$
00084 
00085 $head b$$
00086 The return value $italic b$$ has prototype
00087 $syntax%
00088         bool %b%
00089 %$$
00090 If either $italic x$$ or $italic y$$ is infinite or not a number, 
00091 the return value is false.
00092 Otherwise, if either the relative or absolute error 
00093 condition (defined above) is satisfied, the return value is true.
00094 Otherwise, the return value is false.
00095 
00096 $head Type$$
00097 The type $italic Type$$ must be a
00098 $xref/NumericType/$$.
00099 The routine $xref/CheckNumericType/$$ will generate
00100 an error message if this is not the case.
00101 If $italic a$$ and $italic b$$ have type $italic Type$$,
00102 the following operation must be defined 
00103 $table
00104 $bold Operation$$     $cnext 
00105         $bold Description$$ $rnext
00106 $syntax%%a% <= %b%$$  $cnext 
00107         less that or equal operator (returns a $code bool$$ object)
00108 $tend
00109 
00110 $head Operation Sequence$$
00111 The result of this operation is not an
00112 $xref/glossary/AD of Base/AD of Base/$$ object.
00113 Thus it will not be recorded as part of an
00114 AD of $italic Base$$
00115 $xref/glossary/Operation/Sequence/operation sequence/1/$$.
00116 
00117 $head Example$$
00118 $children%
00119         example/near_equal_ext.cpp
00120 %$$
00121 The file $xref/NearEqualExt.cpp/$$ contains an example
00122 and test of this extension of $xref/NearEqual/$$.
00123 It return true if it succeeds and false otherwise.
00124 
00125 $end
00126 
00127 */
00128 // BEGIN CppAD namespace
00129 namespace CppAD {
00130 // ------------------------------------------------------------------------
00131 
00132 // fold into base type and then use <cppad/near_equal.hpp>
00133 template <class Base>
00134 CPPAD_INLINE bool NearEqual(
00135 const AD<Base> &x, const AD<Base> &y, const Base &r, const Base &a)
00136 {       return NearEqual(x.value_, y.value_, r, a);
00137 }
00138 
00139 template <class Base>
00140 CPPAD_INLINE bool NearEqual(
00141 const Base &x, const AD<Base> &y, const Base &r, const Base &a)
00142 {       return NearEqual(x, y.value_, r, a);
00143 }
00144 
00145 template <class Base>
00146 CPPAD_INLINE bool NearEqual(
00147 const AD<Base> &x, const Base &y, const Base &r, const Base &a)
00148 {       return NearEqual(x.value_, y, r, a);
00149 }
00150 
00151 // fold into AD type and then use cases above
00152 template <class Base>
00153 CPPAD_INLINE bool NearEqual(
00154         const VecAD_reference<Base> &x, const VecAD_reference<Base> &y, 
00155         const Base &r, const Base &a)
00156 {       return NearEqual(x.ADBase(), y.ADBase(), r, a);
00157 }
00158 template <class Base>
00159 CPPAD_INLINE bool NearEqual(const VecAD_reference<Base> &x, const AD<Base> &y, 
00160         const Base &r, const Base &a)
00161 {       return NearEqual(x.ADBase(), y, r, a);
00162 }
00163 template <class Base>
00164 CPPAD_INLINE bool NearEqual(const VecAD_reference<Base> &x, const Base &y, 
00165         const Base &r, const Base &a)
00166 {       return NearEqual(x.ADBase(), y, r, a);
00167 }
00168 template <class Base>
00169 CPPAD_INLINE bool NearEqual(const AD<Base> &x, const VecAD_reference<Base> &y, 
00170         const Base &r, const Base &a)
00171 {       return NearEqual(x, y.ADBase(), r, a);
00172 }
00173 template <class Base>
00174 CPPAD_INLINE bool NearEqual(const Base &x, const VecAD_reference<Base> &y, 
00175         const Base &r, const Base &a)
00176 {       return NearEqual(x, y.ADBase(), r, a);
00177 }
00178 
00179 } // END CppAD namespace
00180 
00181 # endif