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