--------------------------------------------------------------
lines 8-123 of file: include/cppad/core/atomic/four/atomic.hpp
--------------------------------------------------------------

{xrst_begin atomic_four_define}
{xrst_spell
   ctor
}

Defining Atomic Functions: Fourth Generation
############################################

Syntax
******

Define Class
============

| ``class`` *atomic_user* : ``public CppAD::atomic_four<`` *Base* > {
| |tab| ...
| };

Constructor
===========
*atomic_user* *afun* ( *ctor_arg_list* )

Call
====

| *afun* ( *ax* , *ay* )
| *afun* ( *call_id* , *ax* , *ay* )

Callbacks
=========

| *ok* = *afun* . ``for_type`` ( *call_id* ,
| |tab| *type_x* , *type_y*
| )
| *ok* = *afun* . ``forward`` ( *call_id* ,
| |tab| *select_y* , *order_low* , *order_up* , *taylor_x* , *taylor_y*
| )
| *ok* = *afun* . ``reverse`` ( *call_id* ,
| |tab| *select_x* , *order_up* , *taylor_x* , *taylor_y* , *partial_x* , *partial_y*
| )
| *ok* = *afun* . ``jac_sparsity`` ( *call_id* ,
| |tab| *dependency* , *ident_zero_x* , *select_x* *select_y* , *pattern_out*
| )
| *ok* = *afun* . ``hes_sparsity`` ( *call_id* ,
| |tab| *ident_zero_x* , *select_x* , *select_y* , *pattern_out*
| )
| *ok* = *afun* . ``rev_depend`` ( *call_id* ,
| |tab| *ident_zero_x* , *depend_x* , *depend_y*
| )

See Also
********
:ref:`chkpoint_two-name` , :ref:`atomic_three-name`

Purpose
*******

Speed
=====
In some cases, it is possible to compute derivatives of a function

.. math::

   y = g(x) \; {\rm where} \; g : \B{R}^n \rightarrow \B{R}^m

more efficiently than by coding it using ``AD`` < *Base* >
:ref:`glossary@Operation@Atomic` operations
and letting CppAD do the rest.
The class ``atomic_four`` < ``Base`` > is used to
create a new atomic operation corresponding to a function :math:`g(x)`
where the user specifies how to compute the derivatives
and sparsity patterns for :math:`g(x)`.

Reduce Memory
=============
If the function :math:`g(x)` is used many times during the recording
of an :ref:`ADFun-name` object,
an atomic version of :math:`g(x)` removes the need for repeated
copies of the corresponding ``AD`` < *Base* > operations and variables
in the recording.

Virtual Functions
*****************
The :ref:`callback functions<atomic_four_define@Syntax@Callbacks>`
are implemented by defining the virtual functions in the
*atomic_user* class.
These functions compute derivatives,
sparsity patterns, and dependency relations.
Each virtual function has a default implementation
that returns *ok* == ``false`` .
The :ref:`for_type<atomic_four_for_type-name>`
and :ref:`forward<atomic_four_forward-name>` function
(for the case *order_up*  == 0 ) are used by an atomic function
:ref:`atomic_four_define@Syntax@Call` .
Hence, they are required for one to use an atomic function.
Other functions and orders are only required if they are used
for your calculations.
For example,
*forward* for the case *order_up*  == 2 can just return
*ok* == ``false`` unless you require
forward mode calculation of second derivatives.

Contents
********
{xrst_toc_table
   include/cppad/core/atomic/four/ctor.hpp
   include/cppad/core/atomic/four/call.hpp
   include/cppad/core/atomic/four/for_type.hpp
   include/cppad/core/atomic/four/forward.hpp
   include/cppad/core/atomic/four/reverse.hpp
   include/cppad/core/atomic/four/jac_sparsity.hpp
   include/cppad/core/atomic/four/hes_sparsity.hpp
   include/cppad/core/atomic/four/rev_depend.hpp
}

{xrst_end atomic_four_define}