lines 17-255 of file: include/cppad/core/chkpoint_one/chkpoint_one.hpp

{xrst_begin chkpoint_one app}
{xrst_spell
   caching
   destructed
   inuse
   recomputed
   sv
}

Checkpoint Functions: First Generation
######################################

Deprecated 2019-01-14
*********************
Using the ``checkpoint`` class has been deprecated.
Use :ref:`chkpoint_two-name` instead.

Syntax
******

| ``checkpoint`` < *Base* > *atom_fun* (
| |tab| *name* , *algo* , *ax* , *ay* , *sparsity* , *optimize*
| )
| *sv* = *atom_fun* . ``size_var`` ()
| *atom_fun* . ``option`` ( *option_value* )
| *algo* ( *ax* , *ay* )
| *atom_fun* ( *ax* , *ay* )
| *checkpoint* < ``Base`` >:: *clear* ()

See Also
********
:ref:`atomic_two-name` , :ref:`rev_checkpoint.cpp-name`

Purpose
*******

Reduce Memory
=============
You can reduce the size of the tape and memory required for AD by
checkpointing functions of the form :math:`y = f(x)` where
:math:`f : \B{R}^n \rightarrow \B{R}^m`.

Faster Recording
================
It may also reduce the time to make a recording the same function
for different values of the independent variable.
Note that the operation sequence for a recording that uses :math:`f(x)`
may depend on its independent variables.

Repeating Forward
=================
Normally, CppAD store :ref:`forward-name` mode results until they freed
using :ref:`capacity_order-name` or the corresponding :ref:`ADFun-name` object is
deleted. This is not true for checkpoint functions because a checkpoint
function may be used repeatedly with different arguments in the same tape.
Thus, forward mode results are recomputed each time a checkpoint function
is used during a forward or reverse mode sweep.

Restriction
===========
The :ref:`operation sequence<glossary@Operation@Sequence>`
representing :math:`f(x)` cannot depend on the value of :math:`x`.
The approach in the :ref:`rev_checkpoint.cpp-name` example case be applied
when the operation sequence depends on :math:`x`.

Multiple Level AD
=================
If *Base* is an AD type, it is possible to record *Base*
operations.
Note that *atom_fun* will treat *algo* as an atomic
operation while recording ``AD`` < ``Base`` > operations, but not while
recording *Base* operations.
See the ``chkpoint_one_mul_level.cpp`` example.

Method
******
The ``checkpoint`` class is derived from ``atomic_base``
and makes this easy.
It implements all the ``atomic_base``
:ref:`atomic_two@Virtual Functions`
and hence its source code ``cppad/core/chkpoint_one/chkpoint_one.hpp``
provides an example implementation of :ref:`atomic_two-name` .
The difference is that ``chkpoint_one.hpp`` uses AD
instead of user provided derivatives.

constructor
***********
The syntax for the checkpoint constructor is

   ``checkpoint`` < *Base* > *atom_fun* ( *name* , *algo* , *ax* , *ay* )

#. This constructor cannot be called in :ref:`parallel<ta_in_parallel-name>` mode.
#. You cannot currently be recording
   ``AD`` < *Base* > operations when the constructor is called.
#. This object *atom_fun* must not be destructed for as long
   as any ``ADFun`` < *Base* > object uses its atomic operation.
#. This class is implemented as a derived class of
   :ref:`atomic<atomic_two_ctor@atomic_base>` and hence
   some of its error message will refer to ``atomic_base`` .

Base
****
The type *Base* specifies the base type for AD operations.

ADVector
********
The type *ADVector* must be a
:ref:`simple vector class<SimpleVector-name>` with elements of type
``AD`` < *Base* > .

name
****
This *checkpoint* constructor argument has prototype

   ``const char`` * *name*

It is the name used for error reporting.
The suggested value for *name* is *atom_fun* ; i.e.,
the same name as used for the object being constructed.

ax
**
This argument has prototype

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

and size must be equal to *n* .
It specifies vector :math:`x \in \B{R}^n`
at which an ``AD`` < *Base* > version of
:math:`y = f(x)` is to be evaluated.

ay
**
This argument has prototype

   *ADVector* & *ay*

Its input size must be equal to *m* and does not change.
The input values of its elements do not matter.
Upon return, it is an ``AD`` < *Base* > version of
:math:`y = f(x)`.

sparsity
********
This argument has prototype

   ``atomic_base`` < *Base* >:: ``option_enum`` *sparsity*

It specifies :ref:`atomic_two_ctor@atomic_base@sparsity`
in the ``atomic_base`` constructor and must be either
``atomic_base`` < *Base* >:: ``pack_sparsity_enum`` ,
``atomic_base`` < *Base* >:: ``bool_sparsity_enum`` , or
``atomic_base`` < *Base* >:: ``set_sparsity_enum`` .
This argument is optional and its default value is unspecified.

optimize
********
This argument has prototype

   ``bool`` *optimize*

It specifies if the recording corresponding to the atomic function
should be :ref:`optimized<optimize-name>` .
One expects to use a checkpoint function many times, so it should
be worth the time to optimize its operation sequence.
For debugging purposes, it may be useful to use the
original operation sequence (before optimization)
because it corresponds more closely to *algo* .
This argument is optional and its default value is true.

size_var
********
This ``size_var`` member function return value has prototype

   ``size_t`` *sv*

It is the :ref:`fun_property@size_var` for the
``ADFun`` < *Base* > object is used to store the operation sequence
corresponding to *algo* .

option
******
The ``option`` syntax can be used to set the type of sparsity
pattern used by *atom_fun* .
This is an ``atomic_base`` < *Base* > function and its documentation
can be found at :ref:`atomic_two_option-name` .

algo
****
The type of *algo* is arbitrary, except for the fact that
the syntax

   *algo* ( *ax* , *ay* )

must evaluate the function :math:`y = f(x)` using
``AD`` < *Base* > operations.
In addition, we assume that the
:ref:`operation sequence<glossary@Operation@Sequence>`
does not depend on the value of *ax* .

atom_fun
********
Given *ax* it computes the corresponding value of *ay*
using the operation sequence corresponding to *algo* .
If ``AD`` < *Base* > operations are being recorded,
it enters the computation as single operation in the recording
see :ref:`Independent@Start Recording` .
(Currently each use of *atom_fun* actually corresponds to
*m* + *n* +2 operations and creates *m* new variables,
but this is not part of the CppAD specifications and my change.)

Memory
******

Restriction
===========
The ``clear`` routine cannot be called
while in :ref:`parallel<ta_in_parallel-name>` execution mode.

Parallel Mode
*************
The CppAD checkpoint function delays the caching of certain calculations
until they are needed.
In :ref:`parallel model<ta_parallel_setup-name>` ,
this may result in :ref:`thread_alloc::inuse(thread)<ta_inuse-name>`
being non-zero even though the specified thread is no longer active.
This memory will be freed when the checkpoint object is deleted.

clear
=====
The ``atomic_base`` class holds onto static work space
that is not connected to a particular object
(in order to increase speed by avoiding system memory allocation calls).
This call makes to work space :ref:`available<ta_available-name>` to
for other uses by the same thread.
This should be called when you are done using the
atomic functions for a specific value of *Base* .

{xrst_end chkpoint_one}
