CppAD: A C++ Algorithmic Differentiation Package 20110419
cap_taylor.hpp
Go to the documentation of this file.
00001 /* $Id$ */
00002 # ifndef CPPAD_CAP_TAYLOR_INCLUDED
00003 # define CPPAD_CAP_TAYLOR_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 capacity_taylor$$
00018 $spell
00019         var
00020         taylor_
00021 $$
00022 
00023 $index Forward, capacity$$
00024 $index capacity_taylor$$
00025 $index capacity, Forward$$
00026 $index memory, control$$
00027 
00028 $section Controlling Taylor Coefficients Memory Allocation$$
00029 
00030 $head Syntax$$
00031 $syntax%%f%.capacity_taylor(%c%)%$$
00032 
00033 $subhead See Also$$
00034 $cref/seq_property/$$
00035 
00036 $head Purpose$$
00037 The Taylor coefficients calculated by $cref/Forward/$$ mode calculations
00038 are retained in an $xref/ADFun/$$ object for subsequent use during 
00039 $xref/Reverse/$$ mode or higher order Forward mode calculations.
00040 This operation allow you to control that amount of memory
00041 that is retained by an AD function object 
00042 (for subsequent calculations).
00043 
00044 $head f$$
00045 The object $italic f$$ has prototype
00046 $syntax%
00047         ADFun<%Base%> %f%
00048 %$$
00049 
00050 $head c$$
00051 The argument $italic c$$ has prototype
00052 $syntax%
00053         size_t %c%
00054 %$$
00055 It specifies the number of Taylor coefficients that are allocated for
00056 each variable in the AD operation sequence corresponding to $italic f$$.
00057 
00058 $head Discussion$$
00059 A call to $xref/ForwardAny//Forward/$$ with the syntax
00060 $syntax%
00061         %y_p% = %f%.Forward(%p%, %x_p%)
00062 %$$
00063 uses the lower order Taylor coefficients and 
00064 computes the $th p$$ order Taylor coefficients for all
00065 the variables in the operation sequence corresponding to $italic f$$.
00066 (You can determine the number of variables in the operation sequence
00067 using the $xref/seq_property/size_var/size_var/$$ function.)
00068 
00069 $subhead Pre-Allocating Memory$$
00070 If you plan to make calls to $code Forward$$ with the maximum value of 
00071 $italic p$$ equal to $italic q$$,
00072 it should be faster to pre-allocate memory for these calls using
00073 $syntax%
00074         %f%.capacity_taylor(%c%)
00075 %$$
00076 with $italic c$$ equal to $latex q + 1$$.
00077 If you do no do this, $code Forward$$ will automatically allocate memory
00078 and will copy the results to a larger buffer, when necessary.
00079 $pre
00080 
00081 $$
00082 Note that each call to $cref/Dependent/$$ frees the old memory
00083 connected to the function object and sets the corresponding 
00084 taylor capacity to zero.
00085 
00086 $subhead Freeing Memory$$
00087 If you no longer need the Taylor coefficients of order $italic q$$
00088 and higher (that are stored in $italic f$$), 
00089 you can reduce the memory allocated to $italic f$$ using
00090 $syntax%
00091         %f%.capacity_taylor(%c%)
00092 %$$
00093 with $italic c$$ equal to $italic q$$.
00094 
00095 $subhead Original State$$
00096 If $italic f$$ is $cref/constructed/FunConstruct/$$ with the syntax
00097 $syntax%
00098         ADFun<%Base%> %f%(%x%, %y%)
00099 %$$,
00100 there is an implicit call to $code Forward$$ with $italic p$$ equal to zero
00101 and $italic x_p$$ equal to 
00102 the value of the
00103 $cref/independent variables/glossary/Tape/Independent Variable/$$ 
00104 when the AD operation sequence was recorded.
00105 
00106 $head Example$$
00107 The file 
00108 $xref/Forward.cpp/$$
00109 contains an example and test of these operations.
00110 It returns true if it succeeds and false otherwise.
00111 
00112 $end
00113 -----------------------------------------------------------------------------
00114 */
00115 
00116 // BEGIN CppAD namespace
00117 namespace CppAD {
00118 
00119 template <typename Base>
00120 void ADFun<Base>::capacity_taylor(size_t c)
00121 {       // temporary indices
00122         size_t i, j, p;
00123 
00124                 // taylor_per_var_,
00125 
00126         if( c == taylor_col_dim_ )
00127                 return;
00128 
00129         if( c == 0 )
00130         {       if( taylor_ != CPPAD_NULL )
00131                         CPPAD_TRACK_DEL_VEC(taylor_);
00132                 taylor_ = CPPAD_NULL;
00133                 taylor_per_var_ = 0;
00134                 taylor_col_dim_ = 0;
00135                 return;
00136         }
00137         
00138         // Allocate new matrix will requested number of columns 
00139         size_t newlen   = c * total_num_var_;
00140         Base *newptr    = CPPAD_NULL;
00141         newptr          = CPPAD_TRACK_NEW_VEC(newlen, newptr);
00142 
00143         // number of columns to copy
00144         p = std::min(taylor_per_var_, c);
00145 
00146         // copy the old data into the new matrix
00147         CPPAD_ASSERT_UNKNOWN( (taylor_per_var_ == 0) | (taylor_ != CPPAD_NULL) );
00148         for(i = 0; i < total_num_var_; i++)
00149         {       for(j = 0; j < p; j++)
00150                 {       newptr[i * c + j]  = taylor_[i * taylor_col_dim_ + j];
00151                 }
00152         }
00153         // free the old memory
00154         if( taylor_ != CPPAD_NULL )
00155                 CPPAD_TRACK_DEL_VEC(taylor_);
00156 
00157         // use the new pointer
00158         taylor_         = newptr;
00159         taylor_col_dim_   = c;
00160         taylor_per_var_ = p;
00161 
00162         return;
00163 }
00164 
00165 } // END CppAD namespace
00166         
00167 
00168 # endif