CppAD: A C++ Algorithmic Differentiation Package 20110419
|
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