\(\newcommand{\W}[1]{ \; #1 \; }\) \(\newcommand{\R}[1]{ {\rm #1} }\) \(\newcommand{\B}[1]{ {\bf #1} }\) \(\newcommand{\D}[2]{ \frac{\partial #1}{\partial #2} }\) \(\newcommand{\DD}[3]{ \frac{\partial^2 #1}{\partial #2 \partial #3} }\) \(\newcommand{\Dpow}[2]{ \frac{\partial^{#1}}{\partial {#2}^{#1}} }\) \(\newcommand{\dpow}[2]{ \frac{ {\rm d}^{#1}}{{\rm d}\, {#2}^{#1}} }\)
chkpoint_one¶
View page sourceCheckpoint Functions: First Generation¶
Deprecated 2019-01-14¶
Using the checkpoint
class has been deprecated.
Use chkpoint_two instead.
Syntax¶
checkpoint
< Base > atom_fun (size_var
()option
( option_value )Base
>:: clear ()See Also¶
Purpose¶
Reduce Memory¶
You can reduce the size of the tape and memory required for AD by checkpointing functions of the form \(y = f(x)\) where \(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 \(f(x)\) may depend on its independent variables.
Repeating Forward¶
Normally, CppAD store Forward mode results until they freed using capacity_order or the corresponding ADFun 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 operation sequence representing \(f(x)\) cannot depend on the value of \(x\). The approach in the rev_checkpoint.cpp example case be applied when the operation sequence depends on \(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
Virtual Functions
and hence its source code cppad/core/chkpoint_one/chkpoint_one.hpp
provides an example implementation of atomic_two .
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 parallel 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 atomic 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
simple vector class 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 \(x \in \B{R}^n\)
at which an AD
< Base > version of
\(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
\(y = f(x)\).
sparsity¶
This argument has prototype
atomic_base
< Base >::option_enum
sparsity
It specifies 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 optimized . 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 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 atomic_two_option .
algo¶
The type of algo is arbitrary, except for the fact that the syntax
algo ( ax , ay )
must evaluate the function \(y = f(x)\) using
AD
< Base > operations.
In addition, we assume that the
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 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 parallel execution mode.
Parallel Mode¶
The CppAD checkpoint function delays the caching of certain calculations until they are needed. In parallel model , this may result in thread_alloc::inuse(thread) 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 available 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 .