CppAD: A C++ Algorithmic Differentiation Package 20110419
rev_one.hpp
Go to the documentation of this file.
00001 /* $Id$ */
00002 # ifndef CPPAD_REV_ONE_INCLUDED
00003 # define CPPAD_REV_ONE_INCLUDED
00004 
00005 /* --------------------------------------------------------------------------
00006 CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-09 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 /*
00017 $begin RevOne$$
00018 $spell
00019         dw
00020         Taylor
00021         const
00022 $$
00023 
00024 
00025 $index derivative, first order driver$$
00026 $index first, order derivative driver$$
00027 $index driver, first order derivative$$
00028 
00029 $index easy, derivative$$
00030 $index driver, easy derivative$$
00031 $index derivative, easy$$
00032 
00033 $section First Order Derivative: Driver Routine$$
00034 
00035 $head Syntax$$
00036 $syntax%%dw% = %f%.RevOne(%x%, %i%)%$$
00037 
00038 
00039 $head Purpose$$
00040 We use $latex F : B^n \rightarrow B^m$$ to denote the
00041 $xref/glossary/AD Function/AD function/$$ corresponding to $italic f$$.
00042 The syntax above sets $italic dw$$ to the
00043 derivative of $latex F_i$$ with respect to $latex x$$; i.e.,
00044 $latex \[
00045 dw =
00046 F_i^{(1)} (x) 
00047 = \left[ 
00048         \D{ F_i }{ x_0 } (x) , \cdots , \D{ F_i }{ x_{n-1} } (x) 
00049 \right]
00050 \] $$
00051 
00052 $head f$$
00053 The object $italic f$$ has prototype
00054 $syntax%
00055         ADFun<%Base%> %f%
00056 %$$
00057 Note that the $xref/ADFun/$$ object $italic f$$ is not $code const$$
00058 (see $xref/RevOne/RevOne Uses Forward/RevOne Uses Forward/$$ below).
00059 
00060 $head x$$
00061 The argument $italic x$$ has prototype
00062 $syntax%
00063         const %Vector% &%x%
00064 %$$
00065 (see $xref/RevOne/Vector/Vector/$$ below)
00066 and its size 
00067 must be equal to $italic n$$, the dimension of the
00068 $xref/seq_property/Domain/domain/$$ space for $italic f$$.
00069 It specifies
00070 that point at which to evaluate the derivative.
00071 
00072 $head i$$
00073 The index $italic i$$ has prototype
00074 $syntax%
00075         size_t %i%
00076 %$$
00077 and is less than $latex m$$, the dimension of the
00078 $xref/seq_property/Range/range/$$ space for $italic f$$.
00079 It specifies the
00080 component of $latex F$$ that we are computing the derivative of.
00081 
00082 $head dw$$
00083 The result $italic dw$$ has prototype
00084 $syntax%
00085         %Vector% %dw%
00086 %$$
00087 (see $xref/RevOne/Vector/Vector/$$ below)
00088 and its size is $italic n$$, the dimension of the
00089 $xref/seq_property/Domain/domain/$$ space for $italic f$$.
00090 The value of $italic dw$$ is the derivative of $latex F_i$$ 
00091 evaluated at $italic x$$; i.e.,
00092 for $latex j = 0 , \ldots , n - 1 $$ 
00093 $latex \[.
00094         dw[ j ] = \D{ F_i }{ x_j } ( x )
00095 \] $$
00096 
00097 $head Vector$$
00098 The type $italic Vector$$ must be a $xref/SimpleVector/$$ class with
00099 $xref/SimpleVector/Elements of Specified Type/elements of type/$$
00100 $italic Base$$.
00101 The routine $xref/CheckSimpleVector/$$ will generate an error message
00102 if this is not the case.
00103 
00104 $head RevOne Uses Forward$$
00105 After each call to $xref/Forward/$$,
00106 the object $italic f$$ contains the corresponding 
00107 $xref/glossary/Taylor Coefficient/Taylor coefficients/$$.
00108 After $code RevOne$$,
00109 the previous calls to $xref/Forward/$$ are undefined.
00110 
00111 $head Example$$
00112 $children%
00113         example/rev_one.cpp
00114 %$$
00115 The routine 
00116 $xref/RevOne.cpp//RevOne/$$ is both an example and test.
00117 It returns $code true$$, if it succeeds and $code false$$ otherwise.
00118 
00119 $end
00120 -----------------------------------------------------------------------------
00121 */
00122 
00123 //  BEGIN CppAD namespace
00124 namespace CppAD {
00125 
00126 template <typename Base>
00127 template <typename Vector>
00128 Vector ADFun<Base>::RevOne(const Vector  &x, size_t i)
00129 {       size_t i1;
00130 
00131         size_t n = Domain();
00132         size_t m = Range();
00133 
00134         // check Vector is Simple Vector class with Base type elements
00135         CheckSimpleVector<Base, Vector>();
00136 
00137         CPPAD_ASSERT_KNOWN(
00138                 x.size() == n,
00139                 "RevOne: Length of x not equal domain dimension for f"
00140         ); 
00141         CPPAD_ASSERT_KNOWN(
00142                 i < m,
00143                 "RevOne: the index i is not less than range dimension for f"
00144         );
00145 
00146         // point at which we are evaluating the derivative
00147         Forward(0, x);
00148 
00149         // component which are are taking the derivative of
00150         Vector w(m);
00151         for(i1 = 0; i1 < m; i1++)
00152                 w[i1] = 0.;
00153         w[i] = Base(1);
00154 
00155         // dimension the return value
00156         Vector dw(n);
00157 
00158         // compute the return value
00159         dw = Reverse(1, w);
00160 
00161         return dw;
00162 }
00163 
00164 } // END CppAD namespace
00165 
00166 # endif