CppAD: A C++ Algorithmic Differentiation Package  20130102
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-12 Bradley M. Bell
00007 
00008 CppAD is distributed under multiple licenses. This distribution is under
00009 the terms of the 
00010                     Eclipse 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 $icode%dy% = %f%.ForOne(%x%, %j%)%$$
00038 
00039 
00040 $head Purpose$$
00041 We use $latex F : B^n \rightarrow B^m$$ to denote the
00042 $cref/AD function/glossary/AD Function/$$ corresponding to $icode f$$.
00043 The syntax above sets $icode 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 $icode f$$ has prototype
00055 $codei%
00056      ADFun<%Base%> %f%
00057 %$$
00058 Note that the $cref ADFun$$ object $icode f$$ is not $code const$$
00059 (see $cref/ForOne Uses Forward/ForOne/ForOne Uses Forward/$$ below).
00060 
00061 $head x$$
00062 The argument $icode x$$ has prototype
00063 $codei%
00064      const %Vector% &%x%
00065 %$$
00066 (see $cref/Vector/ForOne/Vector/$$ below)
00067 and its size 
00068 must be equal to $icode n$$, the dimension of the
00069 $cref/domain/seq_property/Domain/$$ space for $icode f$$.
00070 It specifies
00071 that point at which to evaluate the partial derivative.
00072 
00073 $head j$$
00074 The argument $icode j$$ has prototype
00075 $codei%
00076      size_t %j%
00077 %$$
00078 an is less than $icode n$$,
00079 $cref/domain/seq_property/Domain/$$ space for $icode f$$.
00080 It specifies the component of $icode F$$ 
00081 for which we are computing the partial derivative.
00082 
00083 $head dy$$
00084 The result $icode dy$$ has prototype
00085 $codei%
00086      %Vector% %dy%
00087 %$$
00088 (see $cref/Vector/ForOne/Vector/$$ below)
00089 and its size is $latex m$$, the dimension of the
00090 $cref/range/seq_property/Range/$$ space for $icode f$$.
00091 The value of $icode dy$$ is the partial of $latex F$$ with respect to
00092 $latex x_j$$ evaluated at $icode 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 $icode Vector$$ must be a $cref SimpleVector$$ class with
00101 $cref/elements of type/SimpleVector/Elements of Specified Type/$$
00102 $icode Base$$.
00103 The routine $cref CheckSimpleVector$$ will generate an error message
00104 if this is not the case.
00105 
00106 $head ForOne Uses Forward$$
00107 After each call to $cref Forward$$,
00108 the object $icode f$$ contains the corresponding 
00109 $cref/Taylor coefficients/glossary/Taylor Coefficient/$$.
00110 After a call to $code ForOne$$,
00111 the zero order Taylor coefficients correspond to
00112 $icode%f%.Forward(0,%x%)%$$
00113 and the other coefficients are unspecified.
00114 
00115 $head Example$$
00116 $children%
00117      example/for_one.cpp
00118 %$$
00119 The routine 
00120 $cref/ForOne/for_one.cpp/$$ is both an example and test.
00121 It returns $code true$$, if it succeeds and $code false$$ otherwise.
00122 
00123 $end
00124 -----------------------------------------------------------------------------
00125 */
00126 
00127 //  BEGIN CppAD namespace
00128 namespace CppAD {
00129 
00130 template <typename Base>
00131 template <typename Vector>
00132 Vector ADFun<Base>::ForOne(const Vector &x, size_t j)
00133 {    size_t j1;
00134 
00135      size_t n = Domain();
00136      size_t m = Range();
00137 
00138      // check Vector is Simple Vector class with Base type elements
00139      CheckSimpleVector<Base, Vector>();
00140 
00141      CPPAD_ASSERT_KNOWN(
00142           x.size() == n,
00143           "ForOne: Length of x not equal domain dimension for f"
00144      ); 
00145      CPPAD_ASSERT_KNOWN(
00146           j < n,
00147           "ForOne: the index j is not less than domain dimension for f"
00148      );
00149 
00150      // point at which we are evaluating the second partials
00151      Forward(0, x);
00152 
00153      // direction in which are are taking the derivative
00154      Vector dx(n);
00155      for(j1 = 0; j1 < n; j1++)
00156           dx[j1] = Base(0);
00157      dx[j] = Base(1);
00158 
00159      // dimension the return value
00160      Vector dy(m);
00161 
00162      // compute the return value
00163      dy = Forward(1, dx);
00164 
00165      return dy;
00166 }
00167 
00168 } // END CppAD namespace
00169 
00170 # endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines