CppAD: A C++ Algorithmic Differentiation Package  20130102
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-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
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines