$Id: seq_property.omh 3214 2014-03-18 20:50:38Z bradbell $
/* --------------------------------------------------------------------------
CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-14 Bradley M. Bell

CppAD is distributed under multiple licenses. This distribution is under
the terms of the 
                    GNU General Public License Version 3.

A copy of this license is included in the COPYING file of this distribution.
Please visit http://www.coin-or.org/CppAD/ for information on other licenses.
-------------------------------------------------------------------------- */

$begin seq_property$$
$spell 
	inuse
	Addr
	CppAD
	sizeof
	op
	arg
	enum
	Taylor
	const
	bool
	var
	VecAD
$$

$section ADFun Sequence Properties$$

$head Syntax$$
$icode%n% = %f%.Domain()
%$$
$icode%m% = %f%.Range()
%$$
$icode%p% = %f%.Parameter(%i%)
%$$
$icode%s% = %f%.size_var()
%$$
$icode%s% = %f%.size_par()
%$$
$icode%s% = %f%.size_op()
%$$
$icode%s% = %f%.size_op_arg()
%$$
$icode%s% = %f%.size_text()
%$$
$icode%s% = %f%.size_VecAD()
%$$
$icode%s% = %f%.size_op_seq()
%$$

$subhead See Also$$
$cref size_order$$, $cref capacity_order$$.

$head Purpose$$
The operations above return properties of the
AD of $icode Base$$
$cref/operation sequence/glossary/Operation/Sequence/$$
stored in the ADFun object $icode f$$. 
(If there is no operation sequence stored in $icode f$$,
$code size_var$$ returns zero.)

$head f$$
The object $icode f$$ has prototype
$codei%
	const ADFun<%Base%> %f%
%$$
(see $codei%ADFun<%Base%>%$$ $cref/constructor/FunConstruct/$$).

$head Domain$$
$index ADFun, Domain$$
$index Domain, ADFun$$
The result $icode n$$ has prototype
$codei%
	size_t %n%
%$$
and is the dimension of the domain space corresponding to $icode f$$.
This is equal to the size of the vector $icode x$$ in the call
$codei%
	Independent(%x%)
%$$
that starting recording the operation sequence 
currently stored in $icode f$$
(see $cref FunConstruct$$ and $cref Dependent$$). 

$head Range$$
$index ADFun, Range$$
$index Range, ADFun$$
The result $icode m$$ has prototype
$codei%
	size_t %m%
%$$
and is the dimension of the range space corresponding to $icode f$$.
This is equal to the size of the vector $icode y$$ in syntax
$codei%
	ADFun<%Base> %f%(%x%, %y%)
%$$
or
$codei%
	%f%.Dependent(%y%)
%$$
depending on which stored the operation sequence currently in $icode f$$
(see $cref FunConstruct$$ and $cref Dependent$$). 

$head Parameter$$
$index ADFun, Parameter$$
$index Parameter, ADFun$$
The argument $icode i$$ has prototype
$codei%
	size_t %i%
%$$
and $latex 0 \leq i < m$$.
The result $icode p$$ has prototype
$codei%
	bool %p%
%$$
It is true if the $th i$$ component of range space for $latex F$$
corresponds to a
$cref/parameter/glossary/Parameter/$$ in the operation sequence.
In this case,
the $th i$$ component of $latex F$$ is constant and
$latex \[
	\D{F_i}{x_j} (x) = 0
\] $$
for $latex j = 0 , \ldots , n-1$$ and all $latex x \in B^n$$.

$head size_var$$
$index ADFun, size_var$$
$index size_var, ADFun$$
The result $icode s$$ has prototype
$codei%
	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 $icode f$$ is roughly proportional to $icode s$$.
(The function call $cref/f.size_order()/size_order/$$ 
returns the number of Taylor coefficient orders, per variable,direction,
currently stored in $icode f$$.)
$pre

$$
If there is no operation sequence stored in $icode f$$,
$code size_var$$ returns zero
(see $cref/default constructor/FunConstruct/Default Constructor/$$).

$head size_par$$
$index ADFun, size_par$$
$index size_par, ADFun$$
The result $icode s$$ has prototype
$codei%
	size_t %s%
%$$
and is the number of parameters in the operation sequence.
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 $icode f$$.
Note that one $icode Base$$ value is required for each parameter.

$head size_op$$
The result $icode s$$ has prototype
$codei%
	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 
$cref/size_var/seq_property/size_var/$$. 
Note that one $code enum$$ value is required for each operator.

$head size_op_arg$$
The result $icode s$$ has prototype
$codei%
	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.

$head size_text$$
The result $icode s$$ has prototype
$codei%
	size_t %s%
%$$
and is the total characters used in the $cref PrintFor$$ commands
in this operation sequence.

$head size_VecAD$$
$index ADFun, size_VecAD$$
$index size_VecAD, ADFun$$
The result $icode s$$ has prototype
$codei%
	size_t %s%
%$$
and is the number of $cref VecAD$$ vectors,
plus the number of elements in the vectors.
Only $code VecAD$$ vectors that depend on the 
independent variables are stored in the operation sequence.

$head size_op_seq$$
The result $icode s$$ has prototype
$codei%
	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
$codei%
	%s% = %f%.size_op()     * sizeof(CppAD::OpCode)
	    + %f%.size_op_arg() * sizeof(%tape_addr_type%)
	    + %f%.size_par()    * sizeof(%Base%)
	    + %f%.size_text()   * sizeof(char)
	    + %f%.size_VecAD()  * sizeof(%tape_addr_type%)
%$$
see $cref/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 ($cref/inuse/ta_inuse/$$)
for the operations sequence may be larger.

$head Example$$
$children%
	example/seq_property.cpp
%$$
The file
$cref seq_property.cpp$$ 
contains an example and test of these operations.
It returns true if it succeeds and false otherwise.


$end