----------------------------------------------------------
lines 9-108 of file: include/cppad/core/capacity_order.hpp
----------------------------------------------------------

{xrst_begin capacity_order}
{xrst_spell
   pre
   xq
   yq
}

Controlling Taylor Coefficients Memory Allocation
#################################################

Syntax
******
| *f* . ``capacity_order`` ( *c* )

See Also
========
:ref:`fun_property-name`

Purpose
*******
The Taylor coefficients calculated by :ref:`Forward-name` mode calculations
are retained in an :ref:`ADFun-name` object for subsequent use during
:ref:`Reverse-name` mode and higher order Forward mode calculations.
For example, a call to :ref:`Forward<forward_order-name>` 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 :math:`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 :ref:`Dependent-name` 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 :ref:`ta_hold_memory-name` 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 :ref:`constructed<fun_construct-name>` with the syntax

   ``ADFun`` < *Base* > *f* ( *x* , *y* )

,
there is an implicit call to :ref:`forward_zero-name` with *xq* equal to
the value of the
:ref:`independent variables<glossary@Tape@Independent Variable>`
when the AD operation sequence was recorded.
This corresponds to *c*  == 1 .
{xrst_toc_hidden
   example/general/capacity_order.cpp
}
Example
*******
The file
:ref:`capacity_order.cpp-name`
contains an example and test of these operations.

{xrst_end capacity_order}