// $Id: size_order.omh 3785 2016-02-08 12:53:06Z bradbell $
/* --------------------------------------------------------------------------
CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-15 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 size_order$$
$spell
	var
	Taylor
	const
$$

$section Number Taylor Coefficient Orders Currently Stored$$

$head Syntax$$
$icode%s% = %f%.size_order()%$$

$subhead See Also$$
$cref seq_property$$

$head Purpose$$
Determine the number of Taylor coefficient orders, per variable,direction,
currently calculated and stored in the ADFun object $icode f$$.
See the discussion under
$cref/Constructor/size_order/Constructor/$$,
$cref/Forward/size_order/Forward/$$, and
$cref/capacity_order/size_order/capacity_order/$$
for a description of when this value can change.


$head f$$
The object $icode f$$ has prototype
$codei%
	const ADFun<%Base%> %f%
%$$

$head s$$
The result $icode s$$ has prototype
$codei%
	size_t %s%
%$$
and is the number of Taylor coefficient orders,
per variable,direction in the AD operation sequence,
currently calculated and stored in the ADFun object $icode f$$.

$head Constructor$$
Directly after the $cref FunConstruct$$ syntax
$codei%
	ADFun<%Base%> %f%(%x%, %y%)
%$$
the value of $icode s$$ returned by $code size_order$$ is one.
This is because
there is an implicit call to $code Forward$$ that computes
the zero order Taylor coefficients during this constructor.

$head Forward$$
After a call to $cref/Forward/forward_order/$$ with the syntax
$codei%
        %f%.Forward(%q%, %x_q%)
%$$
the value of $icode s$$ returned by $code size_order$$
would be $latex q + 1$$.
The call to $code Forward$$ above
uses the lower order Taylor coefficients to compute and store
the $th q$$ order Taylor coefficients for all
the variables in the operation sequence corresponding to $icode f$$.
Thus there are $latex q + 1$$ (order zero through $icode q$$)
Taylor coefficients per variable,direction.
(You can determine the number of variables in the operation sequence
using the $cref/size_var/seq_property/size_var/$$ function.)

$head capacity_order$$
If the number of Taylor coefficient orders
currently stored in $icode f$$ is less than or equal $icode c$$,
a call to $cref capacity_order$$ with the syntax
$codei%
	%f%.capacity_order(%c%)
%$$
does not affect the value $icode s$$ returned by $code size_order$$.
Otherwise,
the value $icode s$$ returned by $code size_order$$
is equal to $icode c$$
(only Taylor coefficients of order zero through $latex c-1$$
have been retained).

$head Example$$
The file
$cref forward.cpp$$
contains an example and test of this operation.
It returns true if it succeeds and false otherwise.

$end
