lines 6-289 of file: include/cppad/core/fun_property.xrst

{xrst_begin fun_property}
{xrst_spell
   inuse
}

ADFun Function Properties
#########################

Syntax
******

| *n* = *f* . ``Domain`` ()
| *m* = *f* . ``Range`` ()
| *p* = *f* . ``Parameter`` ( *i* )
| *s* = *f* . ``size_var`` ()
| *s* = *f* . ``size_par`` ()
| *s* = *f* . ``size_op`` ()
| *s* = *f* . ``size_op_arg`` ()
| *s* = *f* . ``size_text`` ()
| *s* = *f* . ``size_VecAD`` ()
| *s* = *f* . ``size_random`` ()
| *s* = *f* . ``size_dyn_ind`` ()
| *s* = *f* . ``size_dyn_par`` ()
| *s* = *f* . ``size_dyn_arg`` ()
| *s* = *f* . ``size_op_seq`` ()

See Also
========
:ref:`function_name-name` ,
:ref:`size_order-name` ,
:ref:`capacity_order-name` ,
:ref:`number_skip-name` .

Purpose
*******
The operations above return properties of the
AD of *Base*
:ref:`operation sequence<glossary@Operation@Sequence>`
stored in the ADFun object *f* .
(If there is no operation sequence stored in *f* ,
``size_var`` returns zero.)

f
*
The object *f* has prototype

   ``const ADFun`` < *Base* > *f*

(see ``ADFun`` < *Base* > :ref:`constructor<fun_construct-name>` ).

Domain
******
The result *n* has prototype

   ``size_t`` *n*

and is the dimension of the domain space corresponding to *f* .
This is equal to the size of the vector *x* in the call

   ``Independent`` ( *x* )

that starting recording the operation sequence
currently stored in *f*
(see :ref:`fun_construct-name` and :ref:`Dependent-name` ).

Range
*****
The result *m* has prototype

   ``size_t`` *m*

and is the dimension of the range space corresponding to *f* .
This is equal to the size of the vector *y* in syntax

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

or

   *f* . ``Dependent`` ( *y* )

depending on which stored the operation sequence currently in *f*
(see :ref:`fun_construct-name` and :ref:`Dependent-name` ).

Parameter
*********
The argument *i* has prototype

   ``size_t`` *i*

and :math:`0 \leq i < m`.
The result *p* has prototype

   ``bool`` *p*

It is true if the *i*-th component of range space for :math:`F`
corresponds to a
:ref:`glossary@Parameter` in the operation sequence.
In this case,
the *i*-th component of :math:`F` is constant and

.. math::

   \D{F_i}{x_j} (x) = 0

for :math:`j = 0 , \ldots , n-1` and all :math:`x \in \B{R}^n`.

size_var
********
The result *s* has prototype

   ``size_t`` *s*

and is the number of variables in the operation sequence plus the following:
one for a phantom variable with tape address zero,
one for each component of the range that is a parameter.
The amount of work and memory necessary for computing function values
and derivatives using *f* is roughly proportional to *s* .
(The function call :ref:`f.size_order()<size_order-name>`
returns the number of Taylor coefficient orders, per variable,direction,
currently stored in *f* .)

If there is no operation sequence stored in *f* ,
``size_var`` returns zero
(see :ref:`fun_construct@Default Constructor` ).

size_par
********
The result *s* has prototype

   ``size_t`` *s*

and is the number of parameters in the operation sequence
(include a phantom parameter at index zero that is not used).
Parameters differ from variables in that only values
(and not derivatives) need to be stored for each parameter.
These parameters are considered part of the operation
sequence, as opposed to the Taylor coefficients which are
considered extra data in the function object *f* .
Note that one *Base* value is required for each parameter.

size_op
*******
The result *s* has prototype

   ``size_t`` *s*

and is the number of operations in the operation sequence.
Some operators, like comparison operators,
do not correspond to a variable.
Other operators, like the sine operator,
correspond to two variables.
Thus, this value will be different from
:ref:`fun_property@size_var` .
Note that one ``enum`` value is required for each operator.

size_op_arg
***********
The result *s* has prototype

   ``size_t`` *s*

and is the total number of operator arguments in the operation sequence.
For example, Binary operators (e.g. addition) have two arguments.
Note that one integer index is stored in the operation sequence
for each argument.
Also note that, as of 2013-10-20, there is an extra
phantom argument with index 0 that is not used.

size_text
*********
The result *s* has prototype

   ``size_t`` *s*

and is the total characters used in the :ref:`PrintFor-name` commands
in this operation sequence.

size_VecAD
**********
The result *s* has prototype

   ``size_t`` *s*

and is the number of :ref:`VecAD-name` vectors,
plus the number of elements in the vectors.
Only ``VecAD`` vectors that depend on the
independent variables are stored in the operation sequence.

size_random
***********
The result *s* has prototype

   ``size_t`` *s*

and is the amount of memory currently holding information
for randomly access the operator sequence.
Random access is only used by the following routines
:ref:`subgraph_sparsity-name` ,
:ref:`subgraph_reverse-name` , and
:ref:`optimize-name` .
The optimize routine replaces the operation sequence, so the extra
memory is automatically dropped.
The subgraph routines hold onto this information
so that it does not need to be recalculated between calls.
The routine
:ref:`subgraph_reverse@clear_subgraph`
will free this extra memory.

size_dyn_ind
************
The result *s* has prototype

   ``size_t`` *s*

and is the number of independent
:ref:`glossary@Parameter@Dynamic` parameters
in the operation sequence.
This is the size of the
:ref:`Independent@dynamic` parameter in the
corresponding call to ``Independent`` .

size_dyn_par
************
The result *s* has prototype

   ``size_t`` *s*

and is the number of
:ref:`glossary@Parameter@Dynamic` parameters.
The dynamic parameters depend on the value of
the independent dynamic parameters but not on the value of the variables.
This includes the independent dynamic parameters.

size_dyn_arg
************
The result *s* has prototype

   ``size_t`` *s*

and is the total number of dynamic parameter operator arguments
in the operation sequence.
For example, Binary operators (e.g. addition) have two arguments.
Note that one integer index is stored in the operation sequence
for each argument.

size_op_seq
***********
The result *s* has prototype

   ``size_t`` *s*

and is the amount of memory required to store the operation sequence
(not counting a small amount of memory required for every operation sequence).
For the current version of CppAD, this is given by
{xrst_comment see size_t player::Memory(void)}

| |tab| *s* = *f* . ``size_op`` ()      * ``sizeof`` ( ``CPPAD_VEC_ENUM_TYPE`` )
| |tab| |tab| + *f* . ``size_op_arg`` ()  * ``sizeof`` ( *tape_addr_type* )
| |tab| |tab| + *f* . ``size_par`` ()     * ``sizeof`` ( *Base* )
| |tab| |tab| + *f* . ``size_par`` ()     * ``sizeof`` ( ``bool`` )
| |tab| |tab| + *f* . ``size_dyn_par`` () * ``sizeof`` ( ``CPPAD_VEC_ENUM_TYPE`` )
| |tab| |tab| + *f* . ``size_dyn_par`` () * ``sizeof`` ( *tape_addr_type* )
| |tab| |tab| + *f* . ``size_dyn_arg`` () * ``sizeof`` ( *tape_addr_type* )
| |tab| |tab| + *f* . ``size_text`` ()    * ``sizeof`` ( ``char`` )
| |tab| |tab| + *f* . ``size_VecAD`` ()   * ``sizeof`` ( *tape_addr_type* )

see :ref:`tape_addr_type<cmake@cppad_tape_addr_type>` .
Note that this is the minimal amount of memory that can hold
the information corresponding to an operation sequence.
The actual amount of memory allocated (:ref:`inuse<ta_inuse-name>` )
for the operations sequence may be larger.
Also note that ``CPPAD_VEC_ENUM_TYPE`` is not part
of the CppAD API and may change.

Example
*******
{xrst_toc_hidden
   example/general/fun_property.cpp
}
The file
:ref:`fun_property.cpp-name`
contains an example and test of these operations.

{xrst_end fun_property}