$Id: glossary.omh 3768 2015-12-28 18:58:35Z bradbell $
/* --------------------------------------------------------------------------
CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-15 Bradley M. Bell

CppAD is distributed under multiple licenses. This distribution is under
the terms of the
                    GNU General Public License Version 3.

A copy of this license is included in the COPYING file of this distribution.
Please visit http://www.coin-or.org/CppAD/ for information on other licenses.
-------------------------------------------------------------------------- */

$begin glossary$$
$aindex head subhead$$
$spell
	std
	Vec
	cos
	bool
	Op
	Diff
	Var
	Cpp
	enum
	Taylor
$$

$section Glossary$$
$mindex efficient$$



$head AD Function$$
Given an $cref ADFun$$ object $icode f$$
there is a corresponding
AD of $icode Base$$ $cref/operation sequence/glossary/Operation/Sequence/$$.
This operation sequence
defines a function
$latex F : B^n \rightarrow B^m $$
where $icode B$$ is the space corresponding to objects of type $icode Base$$,
$icode n$$ is the size of the $cref/domain/seq_property/Domain/$$ space, and
$icode m$$ is the size of the $cref/range/seq_property/Range/$$ space.
We refer to $latex F$$ as the AD function corresponding to
the operation sequence stored in the object $icode f$$.
(See the $cref/FunCheck discussion/FunCheck/Discussion/$$ for
possible differences between $latex F(x)$$ and the algorithm that defined
the operation sequence.)

$head AD of Base$$
An object is called an AD of $icode Base$$ object its type is
either $codei%AD<%Base%>%$$
(see the default and copy $cref/constructors/ad_ctor/$$
or $codei%VecAD<%Base%>::reference%$$ (see $cref VecAD$$)
for some $icode Base$$ type.

$head AD Type Above Base$$
If $icode Base$$ is a type,
an AD type above $icode Base$$
is the following sequence of types:
$codei%
	AD<%Base%> %,% AD< AD<%Base%> > %,% AD< AD< AD<%Base%> > > %,% %...%
%$$

$head Base Function$$
A function $latex f : B \rightarrow B$$
is referred to as a $icode Base$$ function,
if $icode Base$$ is a C++ type that represent elements of
the domain and range space of $icode f$$; i.e. elements of $latex B$$.

$head Base Type$$
If $icode x$$ is an $codei%AD<%Base%>%$$ object,
$icode Base$$ is referred to as the base type for $icode x$$.

$head Elementary Vector$$
The $th j$$ elementary vector $latex e^j \in B^m$$ is defined by
$latex \[
e_i^j = \left\{ \begin{array}{ll}
	1 & {\rm if} \; i = j \\
	0 & {\rm otherwise}
\end{array} \right.
\] $$


$head Operation$$

$subhead Atomic$$
An atomic $icode Type$$ operation is an operation that
has a $icode Type$$ result and is not made up of other
more basic operations.

$subhead Sequence$$
A sequence of atomic $icode Type$$ operations
is called a $icode Type$$ operation sequence.
A sequence of atomic $cref/AD of Base/glossary/AD of Base/$$ operations
is referred to as an AD of $icode Base$$ operation sequence.
The abbreviated notation AD operation sequence is often used
when it is not necessary to specify the base type.

$subhead Dependent$$
Suppose that $icode x$$ and $icode y$$ are $icode Type$$ objects and
the result of
$codei%
	%x% < %y%
%$$
has type $code bool$$ (where $icode Type$$ is not the same as $code bool$$).
If one executes the following code
$codei%
	if( %x% < %y% )
		%y% = cos(%x%);
	else	%y% = sin(%x%);
%$$
the choice above depends on the value of $icode x$$ and $icode y$$
and the two choices result in a different $icode Type$$ operation sequence.
In this case, we say that the $icode Type$$ operation sequence depends
on $icode x$$ and $icode y$$.

$subhead Independent$$
Suppose that $icode i$$ and $icode n$$ are $code size_t$$ objects,
and $icode%x%[%i%]%$$, $icode y$$ are $icode Type$$ objects,
where $icode Type$$ is different from $code size_t$$.
The $icode Type$$ sequence of operations corresponding to
$codei%
	%y% = %Type%(0);
	for(%i% = 0; %i% < %n%; %i%++)
		%y% += %x%[%i%];
%$$
does not depend on the value of $icode x$$ or $icode y$$.
In this case, we say that the $icode Type$$ operation sequence
is independent of $icode y$$ and the elements of $icode x$$.

$head Parameter$$
All $icode Base$$ objects are parameters.
An $codei%AD<%Base%>%$$ object $icode u$$ is currently a parameter if
its value does not depend on the value of
an $cref Independent$$ variable vector for an
$cref/active tape/glossary/Tape/Active/$$.
If $icode u$$ is a parameter, the function
$cref/Parameter(u)/ParVar/$$ returns true
and $cref/Variable(u)/ParVar/$$ returns false.

$head Sparsity Pattern$$
CppAD describes a sparse matrix as a vector of sets with each
vector component corresponding to a row
and the elements of the set corresponding to the possibly non-zero columns.
A vector of $code bool$$
can represent a vector of sets using one bit per element.
(Some vectors of $code bool$$ use one byte per element but
$cref/vectorBool/CppAD_vector/vectorBool/$$ is an example class that
uses one bit per element.)
The problem is that this representation uses one bit for both the elements
that are there and the ones that are not.
$pre

$$
A vector of $code std::set<size_t>$$ does not
represent the elements that are not present,
but it uses about three $code size_t$$ values
for each element that is present.
For example, if $code size_t$$ uses 32 bits,
a vector of $code std::set<size_t>$$ uses
about 100 bits for each element that is present in the
vector of sets.
Thus, a vector of $code std::set<size_t>$$ should be more efficient for
very sparse matrix representations.

$subhead Vector of Boolean$$
Given a matrix
$latex A \in B^{m \times n}$$,
a vector of $code bool$$ $latex B$$ of length $latex m \times n$$
is a sparsity pattern for $latex A$$ if
for $latex i = 0, \ldots , m-1$$ and $latex j = 0 , \ldots n-1$$,
$latex \[
A_{i,j} \neq 0
\; \Rightarrow \;
B_{i * n + j} = {\rm true}
\] $$
Given two sparsity patterns $latex B$$ and $icode C$$
for a matrix $icode A$$, we say that $icode B$$ is more efficient than
$icode C$$ if $icode B$$ has fewer true elements than $icode C$$.
For example, if $latex A$$ is the identity matrix,
$latex \[
	B_{i * n + j} = (i = j)
\] $$
defines an efficient sparsity pattern for $latex A$$.

$subhead Vector of Sets$$
Given a matrix
$latex A \in B^{m \times n}$$,
a vector of sets $latex S$$ of length $latex m$$ is a
sparsity pattern for $latex A$$ if
for $latex i = 0, \ldots , m-1$$
$latex \[
A_{i,j} \neq 0
\; \Rightarrow \; j \in S_i
\] $$
Given two sparsity patterns $latex S$$ and $icode T$$
for a matrix $icode A$$, we say that $icode S$$ is more efficient than
$icode T$$ if $icode S$$ has fewer elements than $icode T$$.
For example, if $latex A$$ is the identity matrix,
$latex \[
	S_i =  \{ i \}
\] $$
defines an efficient sparsity pattern for $latex A$$.

$head Tape$$

$subhead Active$$
A new tape is created and becomes active
after each call of the form (see $cref Independent$$)
$codei%
	Independent(%x%)
%$$
All operations that depend on the elements of $icode x$$ are
recorded on this active tape.

$subhead Inactive$$
The
$cref/operation sequence/glossary/Operation/Sequence/$$
stored in a tape must be transferred to a function object using the syntax
(see $cref/ADFun<Base> f(x, y)/FunConstruct/$$)
$codei%
	ADFun<%Base%> %f%( %x%, %y%)
%$$
or using the syntax (see $cref/f.Dependent(x, y)/Dependent/$$)
$codei%
	%f%.Dependent( %x%, %y%)
%$$
After such a transfer, the tape becomes inactive.

$subhead Independent Variable$$
While the tape is active, we refer to the elements of $icode x$$
as the independent variables for the tape.
When the tape becomes inactive,
the corresponding objects become
$cref/parameters/glossary/Parameter/$$.

$subhead Dependent Variables$$
While the tape is active, we use the term dependent variables for the tape
for any objects whose value depends on the independent variables for the tape.
When the tape becomes inactive,
the corresponding objects become
$cref/parameters/glossary/Parameter/$$.


$head Taylor Coefficient$$
Suppose $latex X : B \rightarrow B^n$$ is a
is $latex p$$ times continuously differentiable function
in some neighborhood of zero.
For $latex k = 0 , \ldots , p$$,
we use the column vector $latex x^{(k)} \in B^n$$ for the $th k$$ order
Taylor coefficient corresponding to $latex X$$
which is defined by
$latex \[
	x^{(k)} = \frac{1}{k !} \Dpow{k}{t} X(0)
\] $$
It follows that
$latex \[
	X(t) = x^{(0)} + x^{(1)} t + \cdots + x^{(p)} t^p  + R(t)
\]$$
where the remainder $latex R(t)$$ divided by $latex t^p$$
converges to zero and $latex t$$ goes to zero.


$head Variable$$
An $codei%AD<%Base%>%$$ object $icode u$$ is a variable if
its value depends on an independent variable vector for
a currently $cref/active tape/glossary/Tape/Active/$$.
If $icode u$$ is a variable,
$cref/Variable(u)/ParVar/$$ returns true and
$cref/Parameter(u)/ParVar/$$ returns false.
For example,
directly after the code sequence
$codei%
	Independent(%x%);
	AD<double> %u% = %x%[0];
%$$
the $codei%AD<double>%$$ object $icode u$$ is currently a variable.
Directly after the code sequence
$codei%
	Independent(%x%);
	AD<double> %u% = %x%[0];
	%u% = 5;
%$$
$icode u$$  is currently a $cref/parameter/glossary/Parameter/$$
(not a variable).
$pre

$$
Note that we often drop the word currently and
just refer to an $codei%AD<%Base%>%$$ object as a variable
or parameter.

$end
