<?xml version='1.0'?>
<html xmlns='http://www.w3.org/1999/xhtml'
      xmlns:math='http://www.w3.org/1998/Math/MathML'
>
<head>
<title>Checkpointing Functions</title>
<meta name="description" id="description" content="Checkpointing Functions"/>
<meta name="keywords" id="keywords" content=" function checkpoint "/>
<style type='text/css'>
body { color : black }
body { background-color : white }
A:link { color : blue }
A:visited { color : purple }
A:active { color : purple }
</style>
<script type='text/javascript' language='JavaScript' src='_checkpoint_xml.js'>
</script>
</head>
<body>
<table><tr>
<td>
<a href="http://www.coin-or.org/CppAD/" target="_top"><img border="0" src="_image.gif"/></a>
</td>
<td><a href="atomic.xml" target="_top">Prev</a>
</td><td><a href="checkpoint.cpp.xml" target="_top">Next</a>
</td><td>
<select onchange='choose_across0(this)'>
<option>Index-&gt;</option>
<option>contents</option>
<option>reference</option>
<option>index</option>
<option>search</option>
<option>external</option>
</select>
</td>
<td>
<select onchange='choose_up0(this)'>
<option>Up-&gt;</option>
<option>CppAD</option>
<option>AD</option>
<option>ADValued</option>
<option>atomic</option>
<option>checkpoint</option>
</select>
</td>
<td>
<select onchange='choose_down3(this)'>
<option>AD-&gt;</option>
<option>ad_ctor</option>
<option>ad_assign</option>
<option>Convert</option>
<option>ADValued</option>
<option>BoolValued</option>
<option>VecAD</option>
<option>base_require</option>
</select>
</td>
<td>
<select onchange='choose_down2(this)'>
<option>ADValued-&gt;</option>
<option>Arithmetic</option>
<option>std_math_ad</option>
<option>MathOther</option>
<option>CondExp</option>
<option>Discrete</option>
<option>atomic</option>
</select>
</td>
<td>
<select onchange='choose_down1(this)'>
<option>atomic-&gt;</option>
<option>checkpoint</option>
<option>atomic_base</option>
</select>
</td>
<td>
<select onchange='choose_down0(this)'>
<option>checkpoint-&gt;</option>
<option>checkpoint.cpp</option>
</select>
</td>
<td>
<select onchange='choose_current0(this)'>
<option>Headings-&gt;</option>
<option>Syntax</option>
<option>Purpose</option>
<option>Method</option>
<option>constructor</option>
<option>Base</option>
<option>ADVector</option>
<option>name</option>
<option>ax</option>
<option>ay</option>
<option>option</option>
<option>algo</option>
<option>afun</option>
<option>clear</option>
<option>---..Restriction</option>
<option>Example</option>
</select>
</td>
</tr></table><br/>
<center><b><big><big>Checkpointing Functions</big></big></b></center>
<br/>
<b><big><a name="Syntax" id="Syntax">Syntax</a></big></b>

<br/>

<code><font color="blue"><span style='white-space: nowrap'>checkpoint&lt;</span></font><i><font color="black"><span style='white-space: nowrap'>Base</span></font></i><font color="blue"><span style='white-space: nowrap'>&gt;&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>afun</span></font></i><font color="blue"><span style='white-space: nowrap'>(</span></font><i><font color="black"><span style='white-space: nowrap'>name</span></font></i><font color="blue"><span style='white-space: nowrap'>,&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>algo</span></font></i><font color="blue"><span style='white-space: nowrap'>,&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>ax</span></font></i><font color="blue"><span style='white-space: nowrap'>,&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>ay</span></font></i><font color="blue"><span style='white-space: nowrap'>)<br/>
</span></font><i><font color="black"><span style='white-space: nowrap'>afun</span></font></i><font color="blue"><span style='white-space: nowrap'>.option(</span></font><i><font color="black"><span style='white-space: nowrap'>option_value</span></font></i><font color="blue"><span style='white-space: nowrap'>)<br/>
</span></font><i><font color="black"><span style='white-space: nowrap'>algo</span></font></i><font color="blue"><span style='white-space: nowrap'>(</span></font><i><font color="black"><span style='white-space: nowrap'>ax</span></font></i><font color="blue"><span style='white-space: nowrap'>,&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>ay</span></font></i><font color="blue"><span style='white-space: nowrap'>)<br/>
</span></font><i><font color="black"><span style='white-space: nowrap'>afun</span></font></i><font color="blue"><span style='white-space: nowrap'>(</span></font><i><font color="black"><span style='white-space: nowrap'>ax</span></font></i><font color="blue"><span style='white-space: nowrap'>,&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>ay</span></font></i><font color="blue"><span style='white-space: nowrap'>)<br/>
checkpoint&lt;</span></font><i><font color="black"><span style='white-space: nowrap'>Base</span></font></i><font color="blue"><span style='white-space: nowrap'>&gt;::clear()</span></font></code>


<br/>
<br/>
<b><big><a name="Purpose" id="Purpose">Purpose</a></big></b>
<br/>
You can reduce the size of the tape and memory required for AD by 
checkpointing functions of the form 
<math xmlns="http://www.w3.org/1998/Math/MathML" display="inline"><mrow>
<mi mathvariant='italic'>y</mi>
<mo stretchy="false">=</mo>
<mi mathvariant='italic'>f</mi>
<mo stretchy="false">(</mo>
<mi mathvariant='italic'>x</mi>
<mo stretchy="false">)</mo>
</mrow></math>

 where

<math xmlns="http://www.w3.org/1998/Math/MathML" display="inline"><mrow>
<mi mathvariant='italic'>f</mi>
<mo stretchy="false">:</mo>
<msup><mi mathvariant='italic'>B</mi>
<mi mathvariant='italic'>n</mi>
</msup>
<mo stretchy="false">&#x02192;</mo>
<msup><mi mathvariant='italic'>B</mi>
<mi mathvariant='italic'>m</mi>
</msup>
</mrow></math>

.

<br/>
<br/>
<b><big><a name="Method" id="Method">Method</a></big></b>
<br/>
The <code><font color="blue">checkpoint</font></code> class is derived from <code><font color="blue">atomic_base</font></code>
and makes this easy.
It implements all the <code><font color="blue">atomic_base</font></code>
<a href="atomic_base.xml#Virtual Functions" target="_top"><span style='white-space: nowrap'>virtual&#xA0;functions</span></a>

and hence its source code <code><font color="blue">cppad/local/checkpoint.hpp</font></code>
provides an example implementation of <a href="atomic_base.xml" target="_top"><span style='white-space: nowrap'>atomic_base</span></a>
.
The difference is that <code><font color="blue">checkpoint.hpp</font></code> uses AD 
instead of user provided derivatives.

<br/>
<br/>
<b><big><a name="constructor" id="constructor">constructor</a></big></b>
<br/>
The constructor 

<code><font color="blue"><span style='white-space: nowrap'><br/>
&#xA0;&#xA0;&#xA0;&#xA0;&#xA0;checkpoint&lt;</span></font><i><font color="black"><span style='white-space: nowrap'>Base</span></font></i><font color="blue"><span style='white-space: nowrap'>&gt;&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>afun</span></font></i><font color="blue"><span style='white-space: nowrap'>(</span></font><i><font color="black"><span style='white-space: nowrap'>name</span></font></i><font color="blue"><span style='white-space: nowrap'>,&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>algo</span></font></i><font color="blue"><span style='white-space: nowrap'>,&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>ax</span></font></i><font color="blue"><span style='white-space: nowrap'>,&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>ay</span></font></i><font color="blue"><span style='white-space: nowrap'>)<br/>
</span></font></code>
cannot be called in <a href="ta_in_parallel.xml" target="_top"><span style='white-space: nowrap'>parallel</span></a>
 mode.
In addition, you cannot currently be recording 

<code><font color="blue"><span style='white-space: nowrap'>AD&lt;</span></font><i><font color="black"><span style='white-space: nowrap'>Base</span></font></i><font color="blue"><span style='white-space: nowrap'>&gt;</span></font></code>
 operations when the constructor is called.
This class is implemented as a derived class of
<a href="atomic_ctor.xml#atomic_base" target="_top"><span style='white-space: nowrap'>atomic_base</span></a>
 and hence 
some of its error message will refer to <code><font color="blue">atomic_base</font></code>.

<br/>
<br/>
<b><big><a name="Base" id="Base">Base</a></big></b>
<br/>
The type 
<code><i><font color="black"><span style='white-space: nowrap'>Base</span></font></i></code>
 specifies the base type for AD operations.

<br/>
<br/>
<b><big><a name="ADVector" id="ADVector">ADVector</a></big></b>
<br/>
The type 
<code><i><font color="black"><span style='white-space: nowrap'>ADVector</span></font></i></code>
 must be a
<a href="simplevector.xml" target="_top"><span style='white-space: nowrap'>simple&#xA0;vector&#xA0;class</span></a>
 with elements of type

<code><font color="blue"><span style='white-space: nowrap'>AD&lt;</span></font><i><font color="black"><span style='white-space: nowrap'>Base</span></font></i><font color="blue"><span style='white-space: nowrap'>&gt;</span></font></code>
.

<br/>
<br/>
<b><big><a name="name" id="name">name</a></big></b>
<br/>
This 
<code><i><font color="black"><span style='white-space: nowrap'>checkpoint</span></font></i></code>
 constructor argument has prototype

<code><font color="blue"><span style='white-space: nowrap'><br/>
&#xA0;&#xA0;&#xA0;&#xA0;&#xA0;const&#xA0;char*&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>name</span></font></i><font color="blue"><span style='white-space: nowrap'><br/>
</span></font></code>
It is the name used for error reporting.
The suggested value for 
<code><i><font color="black"><span style='white-space: nowrap'>name</span></font></i></code>
 is 
<code><i><font color="black"><span style='white-space: nowrap'>afun</span></font></i></code>
; i.e.,
the same name as used for the function.

<br/>
<br/>
<b><big><a name="ax" id="ax">ax</a></big></b>
<br/>
This argument has prototype

<code><font color="blue"><span style='white-space: nowrap'><br/>
&#xA0;&#xA0;&#xA0;&#xA0;&#xA0;const&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>ADVector</span></font></i><font color="blue"><span style='white-space: nowrap'>&amp;&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>ax</span></font></i><font color="blue"><span style='white-space: nowrap'><br/>
</span></font></code>
and size must be equal to 
<code><i><font color="black"><span style='white-space: nowrap'>n</span></font></i></code>
.
It specifies vector 
<math xmlns="http://www.w3.org/1998/Math/MathML" display="inline"><mrow>
<mi mathvariant='italic'>x</mi>
<mo stretchy="false">&#x02208;</mo>
<msup><mi mathvariant='italic'>B</mi>
<mi mathvariant='italic'>n</mi>
</msup>
</mrow></math>

 
at which an 
<code><font color="blue"><span style='white-space: nowrap'>AD&lt;</span></font><i><font color="black"><span style='white-space: nowrap'>Base</span></font></i><font color="blue"><span style='white-space: nowrap'>&gt;</span></font></code>
 version of 

<math xmlns="http://www.w3.org/1998/Math/MathML" display="inline"><mrow>
<mi mathvariant='italic'>y</mi>
<mo stretchy="false">=</mo>
<mi mathvariant='italic'>f</mi>
<mo stretchy="false">(</mo>
<mi mathvariant='italic'>x</mi>
<mo stretchy="false">)</mo>
</mrow></math>

 is to be evaluated.

<br/>
<br/>
<b><big><a name="ay" id="ay">ay</a></big></b>
<br/>
This argument has prototype

<code><font color="blue"><span style='white-space: nowrap'><br/>
&#xA0;&#xA0;&#xA0;&#xA0;&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>ADVector</span></font></i><font color="blue"><span style='white-space: nowrap'>&amp;&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>ay</span></font></i><font color="blue"><span style='white-space: nowrap'><br/>
</span></font></code>
Its input size must be equal to 
<code><i><font color="black"><span style='white-space: nowrap'>m</span></font></i></code>
 and does not change.
The input values of its elements do not matter.
Upon return, it is an 
<code><font color="blue"><span style='white-space: nowrap'>AD&lt;</span></font><i><font color="black"><span style='white-space: nowrap'>Base</span></font></i><font color="blue"><span style='white-space: nowrap'>&gt;</span></font></code>
 version of 

<math xmlns="http://www.w3.org/1998/Math/MathML" display="inline"><mrow>
<mi mathvariant='italic'>y</mi>
<mo stretchy="false">=</mo>
<mi mathvariant='italic'>f</mi>
<mo stretchy="false">(</mo>
<mi mathvariant='italic'>x</mi>
<mo stretchy="false">)</mo>
</mrow></math>

.

<br/>
<br/>
<b><big><a name="option" id="option">option</a></big></b>
<br/>
The <code><font color="blue">option</font></code> syntax can be used to set the type of sparsity
pattern used by 
<code><i><font color="black"><span style='white-space: nowrap'>afun</span></font></i></code>
.
This is an 
<code><font color="blue"><span style='white-space: nowrap'>atomic_base&lt;</span></font><i><font color="black"><span style='white-space: nowrap'>Base</span></font></i><font color="blue"><span style='white-space: nowrap'>&gt;</span></font></code>
 function and its documentation
can be found at <a href="atomic_option.xml" target="_top"><span style='white-space: nowrap'>atomic_option</span></a>
.

<br/>
<br/>
<b><big><a name="algo" id="algo">algo</a></big></b>
<br/>
The type of 
<code><i><font color="black"><span style='white-space: nowrap'>algo</span></font></i></code>
 is arbitrary, except for the fact that
the syntax

<code><font color="blue"><span style='white-space: nowrap'><br/>
&#xA0;&#xA0;&#xA0;&#xA0;&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>algo</span></font></i><font color="blue"><span style='white-space: nowrap'>(</span></font><i><font color="black"><span style='white-space: nowrap'>ax</span></font></i><font color="blue"><span style='white-space: nowrap'>,&#xA0;</span></font><i><font color="black"><span style='white-space: nowrap'>ay</span></font></i><font color="blue"><span style='white-space: nowrap'>)<br/>
</span></font></code>
must evaluate the function 
<math xmlns="http://www.w3.org/1998/Math/MathML" display="inline"><mrow>
<mi mathvariant='italic'>y</mi>
<mo stretchy="false">=</mo>
<mi mathvariant='italic'>f</mi>
<mo stretchy="false">(</mo>
<mi mathvariant='italic'>x</mi>
<mo stretchy="false">)</mo>
</mrow></math>

 using

<code><font color="blue"><span style='white-space: nowrap'>AD&lt;</span></font><i><font color="black"><span style='white-space: nowrap'>Base</span></font></i><font color="blue"><span style='white-space: nowrap'>&gt;</span></font></code>
 operations.
In addition, we assume that the 
<a href="glossary.xml#Operation.Sequence" target="_top"><span style='white-space: nowrap'>operation&#xA0;sequence</span></a>

does not depend on the value of 
<code><i><font color="black"><span style='white-space: nowrap'>ax</span></font></i></code>
.

<br/>
<br/>
<b><big><a name="afun" id="afun">afun</a></big></b>
<br/>
Given 
<code><i><font color="black"><span style='white-space: nowrap'>ax</span></font></i></code>
 it computes the corresponding value of 
<code><i><font color="black"><span style='white-space: nowrap'>ay</span></font></i></code>

using the operation sequence corresponding to 
<code><i><font color="black"><span style='white-space: nowrap'>algo</span></font></i></code>
. 
If 
<code><font color="blue"><span style='white-space: nowrap'>AD&lt;</span></font><i><font color="black"><span style='white-space: nowrap'>Base</span></font></i><font color="blue"><span style='white-space: nowrap'>&gt;</span></font></code>
 operations are being recorded,
it enters the computation as single operation in the recording
see <a href="independent.xml#Start Recording" target="_top"><span style='white-space: nowrap'>start&#xA0;recording</span></a>
.
(Currently each use of 
<code><i><font color="black"><span style='white-space: nowrap'>afun</span></font></i></code>
 actually corresponds to

<code><i><font color="black"><span style='white-space: nowrap'>m</span></font></i><font color="blue"><span style='white-space: nowrap'>+</span></font><i><font color="black"><span style='white-space: nowrap'>n</span></font></i><font color="blue"><span style='white-space: nowrap'>+2</span></font></code>
 operations and creates 
<code><i><font color="black"><span style='white-space: nowrap'>m</span></font></i></code>
 new variables, 
but this is not part of the CppAD specifications and my change.)

<br/>
<br/>
<b><big><a name="clear" id="clear">clear</a></big></b>
<br/>
The <code><font color="blue">atomic_base</font></code> class holds onto static work space in order to
increase speed by avoiding system memory allocation calls.
This call makes to work space <a href="ta_available.xml" target="_top"><span style='white-space: nowrap'>available</span></a>
 to
for other uses by the same thread.
This should be called when you are done using the 
user atomic functions for a specific value of 
<code><i><font color="black"><span style='white-space: nowrap'>Base</span></font></i></code>
.

<br/>
<br/>
<b><a name="clear.Restriction" id="clear.Restriction">Restriction</a></b>
<br/>
The <code><font color="blue">clear</font></code> routine cannot be called
while in <a href="ta_in_parallel.xml" target="_top"><span style='white-space: nowrap'>parallel</span></a>
 execution mode.


<br/>
<br/>
<b><big><a name="Example" id="Example">Example</a></big></b>
<br/>
The file <a href="checkpoint.cpp.xml" target="_top"><span style='white-space: nowrap'>checkpoint.cpp</span></a>
 contains an example and test
of these operations.
It returns true if it succeeds and false if it fails.


<hr/>Input File: cppad/local/checkpoint.hpp

</body>
</html>
