00001 # ifndef CPPAD_ABS_INCLUDED 00002 # define CPPAD_ABS_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 ------------------------------------------------------------------------------- 00017 $begin abs$$ 00018 $spell 00019 Vec 00020 std 00021 faq 00022 Taylor 00023 Cpp 00024 namespace 00025 const 00026 abs 00027 $$ 00028 00029 $index abs, AD$$ 00030 $index absolute, AD value$$ 00031 $index value_, AD absolute$$ 00032 00033 $section AD Absolute Value Function$$ 00034 00035 $head Syntax$$ 00036 $syntax%%y% = abs(%x%)%$$ 00037 00038 00039 $head Purpose$$ 00040 Evaluates the absolute value function where its argument is an 00041 $xref/glossary/AD of Base/AD of/$$ $italic Base$$ object. 00042 00043 00044 $head Base$$ 00045 A definition of $code abs$$ for arguments of type 00046 $code float$$ and $code double$$ 00047 is included in the $code CppAD$$ namespace 00048 (the corresponding results has the same type as the arguments). 00049 The type $italic Base$$ can be any type in the 00050 $cref/AD levels above/glossary/AD Levels Above Base/$$ 00051 above $code float$$ or $code double$$. 00052 00053 00054 $head x$$ 00055 The argument $italic x$$ has one of the following prototypes 00056 $syntax% 00057 const AD<%Base%> &%x% 00058 const VecAD<%Base%>::reference &%x% 00059 %$$ 00060 where $italic Base$$ is $code float$$, $code double$$ or in the 00061 $cref/AD levels above/glossary/AD Levels Above Base/$$ 00062 above $code float$$ or $code double$$; for example, 00063 $code AD<double>$$. 00064 00065 $head y$$ 00066 The result $italic y$$ has prototype 00067 $syntax% 00068 AD<%Base%> %y% 00069 %$$ 00070 00071 00072 $head Operation Sequence$$ 00073 This is an AD of $italic Base$$ 00074 $xref/glossary/Operation/Atomic/atomic operation/1/$$ 00075 and hence is part of the current 00076 AD of $italic Base$$ 00077 $xref/glossary/Operation/Sequence/operation sequence/1/$$. 00078 00079 $head Complex Types$$ 00080 The function $code abs$$ is not defined for the AD type sequences 00081 above $code std::complex<float>$$ or $code std::complex<double>$$ 00082 because the complex $code abs$$ function is not complex differentiable 00083 (see $xref/Faq/Complex Types/complex types faq/$$). 00084 00085 $head Directional Derivative$$ 00086 $index directional, derivative abs$$ 00087 $index derivative, directional abs$$ 00088 The derivative of the absolute value function is one for 00089 $latex x > 0$$ and minus one for $latex x < 0$$. 00090 The subtitle issue is 00091 how to compute its directional derivative 00092 what $latex x = 0$$. 00093 $pre 00094 00095 $$ 00096 The function corresponding to the argument $italic x$$ 00097 and the result $italic y$$ are represented 00098 by their Taylor coefficients; i.e., 00099 $latex \[ 00100 \begin{array}{rcl} 00101 X(t) & = & x^{(0)} (t) + x^{(1)} t + \cdots + x^{(p)} t^p 00102 \\ 00103 Y(t) & = & y^{(0)} (t) + y^{(1)} t + \cdots + y^{(p)} t^p 00104 \end{array} 00105 \] $$ 00106 Note that $latex x^{(0)} = X(0)$$ is the value of $italic x$$ and 00107 $latex y^{(0)} = Y(0)$$ is the value of $italic y$$. 00108 In the equations above, the order $latex p$$ is specified 00109 by a call to $xref/Forward/$$ or $xref/Reverse/$$ as follows: 00110 $syntax% 00111 %f%.Forward(%p%, %dx%) 00112 %f%.Reverse(%p%+1, %w%) 00113 %$$ 00114 If all of the Taylor coefficients of $latex X(t)$$ are zero, 00115 we define $latex k = p$$. 00116 Otherwise, we define $latex k$$ to be the minimal index such that 00117 $latex x^{(k)} \neq 0$$. 00118 Note that if $latex x \neq 0$$, $latex k = 0$$. 00119 The Taylor coefficient representation of $latex Y(t)$$ 00120 (and hence it's derivatives) are computed as 00121 $latex \[ 00122 y^{(\ell)} 00123 = 00124 \left\{ \begin{array}{ll} 00125 x^{(\ell)} & {\rm if} \; x^{(k)} > 0 \\ 00126 0 & {\rm if} \; x^{(k)} = 0 \\ 00127 - x^{(\ell)} & {\rm if} \; x^{(k)} < 0 00128 \end{array} \right. 00129 \] $$ 00130 00131 00132 $head Example$$ 00133 $children% 00134 example/abs.cpp 00135 %$$ 00136 The file 00137 $xref/Abs.cpp/$$ 00138 contains an example and test of this function. 00139 It returns true if it succeeds and false otherwise. 00140 00141 $end 00142 ------------------------------------------------------------------------------- 00143 */ 00144 00145 // BEGIN CppAD namespace 00146 namespace CppAD { 00147 00148 inline float abs(const float &x) 00149 { if( x < 0. ) 00150 return - x; 00151 return x; 00152 } 00153 00154 inline double abs(const double &x) 00155 { if( x < 0. ) 00156 return - x; 00157 return x; 00158 } 00159 00160 template <class Base> 00161 AD<Base> AD<Base>::Abs (void) const 00162 { using CppAD::abs; 00163 00164 AD<Base> result; 00165 CPPAD_ASSERT_UNKNOWN( Parameter(result) ); 00166 00167 result.value_ = abs(value_); 00168 if( Variable(*this) ) 00169 { // add this operation to the tape 00170 tape_this()->RecordOp(AbsOp, result, taddr_); 00171 00172 } 00173 return result; 00174 } 00175 00176 template <class Base> 00177 inline AD<Base> abs(const AD<Base> &x) 00178 { return x.Abs(); } 00179 00180 template <class Base> 00181 inline AD<Base> abs(const VecAD_reference<Base> &x) 00182 { return abs( x.ADBase() ); } 00183 00184 } // END CppAD namespace 00185 00186 # endif