\(\newcommand{\W}[1]{ \; #1 \; }\) \(\newcommand{\R}[1]{ {\rm #1} }\) \(\newcommand{\B}[1]{ {\bf #1} }\) \(\newcommand{\D}[2]{ \frac{\partial #1}{\partial #2} }\) \(\newcommand{\DD}[3]{ \frac{\partial^2 #1}{\partial #2 \partial #3} }\) \(\newcommand{\Dpow}[2]{ \frac{\partial^{#1}}{\partial {#2}^{#1}} }\) \(\newcommand{\dpow}[2]{ \frac{ {\rm d}^{#1}}{{\rm d}\, {#2}^{#1}} }\)

capacity_order

View page source

Controlling Taylor Coefficients Memory Allocation

Syntax

f . capacity_order ( c )

See Also

fun_property

Purpose

The Taylor coefficients calculated by Forward mode calculations are retained in an ADFun object for subsequent use during Reverse mode and higher order Forward mode calculations. For example, a call to Forward with the syntax

yq = f . Forward ( q , xq )

where q > 0 and xq . size () == f . Domain () , uses the lower order Taylor coefficients and computes the q-th order Taylor coefficients for all the variables in the operation sequence corresponding to f . The capacity_order operation allows you to control that amount of memory that is retained by an AD function object (to hold Forward results for subsequent calculations).

f

The object f has prototype

ADFun < Base > f

c

The argument c has prototype

size_t c

It specifies the number of Taylor coefficient orders that are allocated in the AD operation sequence corresponding to f .

Pre-Allocating Memory

If you plan to make calls to Forward with the maximum value of q equal to Q , it should be faster to pre-allocate memory for these calls using

f . capacity_order ( c )

with c equal to \(Q + 1\). If you do no do this, Forward will automatically allocate memory and will copy the results to a larger buffer, when necessary.

Note that each call to Dependent frees the old memory connected to the function object and sets the corresponding taylor capacity to zero.

Freeing Memory

If you no longer need the Taylor coefficients of order q and higher (that are stored in f ), you can reduce the memory allocated to f using

f . capacity_order ( c )

with c equal to q . Note that, if ta_hold_memory is true, this memory is not actually returned to the system, but rather held for future use by the same thread.

Original State

If f is constructed with the syntax

ADFun < Base > f ( x , y )

, there is an implicit call to forward_zero with xq equal to the value of the independent variables when the AD operation sequence was recorded. This corresponds to c == 1 .

Example

The file capacity_order.cpp contains an example and test of these operations.