---------------------------------------------------------
lines 8-217 of file: include/cppad/core/fun_construct.hpp
---------------------------------------------------------

{xrst_begin fun_construct}
{xrst_spell
   versa
}

Construct an ADFun Object and Stop Recording
############################################

Syntax
******
| ``ADFun`` < *Base* > *f* ( *ax* , *ay* );
| ``ADFun`` < *Base* > *f*
| *f* . ``swap`` ( *g* )
| ``f`` = ``g``

Purpose
*******
The ``ADFun`` < *Base* > object *f*
stores an AD of *Base*
:ref:`operation sequence<glossary@Operation@Sequence>` .
It can then be used to calculate derivatives of the corresponding
:ref:`glossary@AD Function`

.. math::

   F : \B{R}^n \rightarrow \B{R}^m

where :math:`B` is the space corresponding to objects of type *Base* .

ax
**
If the argument *ax* is present, it has prototype

   ``const`` *ADVector* & *ax*

It must be the vector argument in the previous call to
:ref:`Independent-name` .
Neither its size, or any of its values, are allowed to change
between calling

   ``Independent`` ( *ax* )

and

   ``ADFun`` < *Base* > *f* ( *ax* , *ay* )

ay
**
If the argument *ay* is present, it has prototype

   ``const`` *ADVector* & *ay*

The sequence of operations that map *ax*
to *ay* are stored in the ADFun object *f* .

ADVector
********
The type *ADVector* must be a :ref:`SimpleVector-name` class with
:ref:`elements of type<SimpleVector@Elements of Specified Type>`
``AD`` < *Base* > .
The routine :ref:`CheckSimpleVector-name` will generate an error message
if this is not the case.

Default Constructor
*******************
The default constructor

   ``ADFun`` < *Base* > *g*

creates an
``AD`` < *Base* > object with no corresponding operation sequence; i.e.,

   *g* . ``size_var`` ()

returns the value zero (see :ref:`fun_property@size_var` ).

Sequence Constructor
********************
The following constructor stores the current ``AD`` < *Base* > operation
sequence in *f* :

   ``ADFun`` < *Base* > *f* ( *ax* , *ay* )

To be specific, it is equivalent to the following
steps using the default constructor:

#. Create *f* with the default constructor

      ``ADFun`` < *Base* > *f* ;

#. Stop the recording and store the operation sequence using

      *f* . ``Dependent`` ( *ax* , *ay* );

   see :ref:`Independent@Start Recording` ,
   :ref:`Dependent@Stop Recording` , and
   :ref:`Dependent@Store Operation Sequence` .

#. Calculate the zero order Taylor coefficients for all
   the variables in the operation sequence using

      *y* = *f* . ``Forward`` ( 0 , *x* )

   see :ref:`forward_zero-name`.
   Here *x* and *y* are :ref:`simple vectors <SimpleVector-name>`
   with elements of type *Base* and the elements of *x*
   are equal to the corresponding elements in *ax*.

#. If NDEBUG is not defined, *y* is checked to make sure it's elements are
   nearly equal to the corresponding values in *ay* .

Copy Constructor
****************
It is an error to attempt to use the ``ADFun`` < *Base* > copy constructor;
i.e., the following syntax is not allowed:

   ``ADFun`` < *Base* > *g* ( *f* )

where *f* is an ``ADFun`` < *Base* > object.
Use its :ref:`fun_construct@Default Constructor` instead
and its assignment operator.

swap
****
The swap operation *f* . ``swap`` ( *g* ) exchanges the contents of
the two ``ADFun`` < *Base* > functions; i.e.,
*f* before the swap is identical to *g* after the swap and vise versa.

Assignment Operator
*******************
The ``ADFun`` < *Base* > assignment operation

   *g* = *f*

makes a copy of the operation sequence currently stored in *f*
in the object *g* .
The object *f* is not affected by this operation and
can be ``const`` .
All of information (state) stored in *f* is copied to *g*
and any information originally in *g* is lost.

Move Semantics
==============
In the special case where *f* is a temporary object,
this assignment will use move semantics.
This avoids the overhead of the copying all the information from
*f* to *g* .

Taylor Coefficients
===================
The Taylor coefficient information currently stored in *f*
(computed by :ref:`f.Forward<Forward-name>` ) is
copied to *g* .
Hence, directly after this operation

   *g* . ``size_order`` () == *f* . ``size_order`` ()

Sparsity Patterns
=================
The forward Jacobian sparsity pattern currently stored in *f*
(computed by :ref:`f.ForSparseJac<ForSparseJac-name>` ) is
copied to *g* .
Hence, directly after this operation

| |tab| *g* . ``size_forward_bool`` () == *f* . ``size_forward_bool`` ()
| |tab| *g* . ``size_forward_set`` ()  == *f* . ``size_forward_set`` ()

Parallel Mode
*************
The call to ``Independent`` ,
and the corresponding call to

   ``ADFun`` < *Base* > *f* ( *ax* , *ay* )

or

   *f* . ``Dependent`` ( *ax* , *ay* )

or :ref:`abort_recording-name` ,
must be preformed by the same thread; i.e.,
:ref:`thread_alloc::thread_num<ta_thread_num-name>` must be the same.

Example
*******

Sequence Constructor
====================
The file
:ref:`independent.cpp-name`
contains an example and test of the sequence constructor.

Default Constructor
===================
The files
:ref:`fun_check.cpp-name`
and
:ref:`hes_lagrangian.cpp-name`
contain an examples and tests using the default constructor.
They return true if they succeed and false otherwise.
{xrst_toc_hidden
   example/general/fun_assign.cpp
}
Assignment Operator
===================
The file
:ref:`fun_assign.cpp-name`
contains an example and test of the ``ADFun`` < *Base* >
assignment operator.

{xrst_end fun_construct}