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