Prev

Next

Index-> contents reference index search external

Up-> CppAD AD ADValued user_atomic

CppAD-> Install Introduction AD ADFun multi_thread library cppad_ipopt_nlp Example preprocessor Appendix

AD-> ad_ctor ad_assign Convert ADValued BoolValued VecAD base_require

ADValued-> Arithmetic std_math_ad MathOther CondExp Discrete user_atomic

user_atomic-> user_tan.cpp mat_mul.cpp

Headings-> Syntax ---..Define Function ---..Use Function ---..Callback Routines ---..Free Static Memory Purpose Partial Implementation CPPAD_USER_ATOMIC ---..Tvector ---..Base ok id k n m tx ty afun ---..ax ---..ay ---..Parallel Mode forward ---..Usage ---..vx ---..vy reverse ---..Usage ---..py ---..px for_jac_sparse ---..Usage ---..q ---..r ---..s rev_jac_sparse ---..Usage ---..q ---..s ---..r rev_hes_sparse ---..Usage ---..q ---..r ---..s ---..t ---..u ---..v clear ---..Restriction Example ---..Tangent Function ---..Matrix Multiplication

User Defined Atomic AD Functions
Syntax

Define Function
CPPAD_USER_ATOMIC(afun, Tvector, Base, 
     forward, reverse, for_jac_sparse, rev_jac_sparse, rev_hes_sparse
)

Use Function
afun(id, ax, ay)

Callback Routines
ok = forward(id, k, n, m, vx, vy, tx, ty)
ok = reverse(id, k, n, m, tx, ty, px, py)
ok = for_jac_sparse(id, n, m, q, r, s)
ok = rev_jac_sparse(id, n, m, q, r, s)
ok = rev_hes_sparse(id, n, m, q, r, s, t, u, v)

Free Static Memory
user_atomic<Base>::clear()

Purpose
In some cases, the user knows how to compute the derivative of a function $$\mathit{y}=\mathit{f}(\mathit{x})\mathrm{where}\mathit{f}:{\mathit{B}}^{\mathit{n}}\to {\mathit{B}}^{\mathit{m}}$$ more efficiently than by coding it AD<Base> atomic operations and letting CppAD do the rest. In this case, CPPAD_USER_ATOMIC can be used add the user code for $\mathit{f}(\mathit{x})$ , and its derivatives, to the set of AD<Base> atomic operations.

Partial Implementation
The routines forward , reverse , for_jac_sparse , rev_jac_sparse , and rev_hes_sparse , must be defined by the user. The forward the routine, for the case k = 0 , must be implemented. Functions with the correct prototype, that just return false , can be used for the other cases (unless they are required by your calculations). For example, you need not implement forward for the case k == 2 until you require forward mode calculation of second derivatives.

CPPAD_USER_ATOMIC
The macro
CPPAD_USER_ATOMIC(afun, Tvector, Base, 
     forward, reverse, for_jac_sparse, rev_jac_sparse, rev_hes_sparse
)
defines the AD<Base> routine afun . This macro can be placed within a namespace (not the CppAD namespace) but must be outside of any routine.

Tvector
The macro argument Tvector must be a simple vector template class . It determines the type of vectors used as arguments to the routine afun .

Base
The macro argument Base specifies the base type corresponding to AD<Base> operation sequences. Calling the routine afun will add the operator defined by this macro to an AD<Base> operation sequence.

ok
For all routines documented below, the return value ok has prototype
     bool ok
If it is true, the corresponding evaluation succeeded, otherwise it failed.

id
For all routines documented below, the argument id has prototype
     size_t id
Its value in all other calls is the same as in the corresponding call to afun . It can be used to store and retrieve extra information about a specific call to afun .

k
For all routines documented below, the argument k has prototype
     size_t k
The value k is the order of the Taylor coefficient that we are evaluating (forward ) or taking the derivative of (reverse ).

n
For all routines documented below, the argument n has prototype
     size_t n
It is the size of the vector ax in the corresponding call to afun(id, ax, ay) ; i.e., the dimension of the domain space for $\mathit{y}=\mathit{f}(\mathit{x})$ .

m
For all routines documented below, the argument m has prototype
     size_t m
It is the size of the vector ay in the corresponding call to afun(id, ax, ay) ; i.e., the dimension of the range space for $\mathit{y}=\mathit{f}(\mathit{x})$ .

tx
For all routines documented below, the argument tx has prototype
     const CppAD::vector<Base>& tx
and tx.size() >= (k + 1) * n . For $\mathit{j}=0,\dots ,\mathit{n}-1$ and $\ell =0,\dots ,\mathit{k}$ , we use the Taylor coefficient notation $$\begin{array}{ccc}\hfill {\mathit{x}}_{\mathit{j}}^{\ell }& \hfill =\hfill & \mathit{tx}[\mathit{j}*(\mathit{k}+1)+\ell ]\hfill \\ \hfill {\mathit{X}}_{\mathit{j}}(\mathit{t})& \hfill =\hfill & {\mathit{x}}_{\mathit{j}}^0+{\mathit{x}}_{\mathit{j}}^1{\mathit{t}}^1+\cdots +{\mathit{x}}_{\mathit{j}}^{\mathit{k}}{\mathit{t}}^{\mathit{k}}\hfill \end{array}$$ If tx.size() > (k + 1) * n , the other components of tx are not specified and should not be used. Note that superscripts represent an index for ${\mathit{x}}_{\mathit{j}}^{\ell }$ and an exponent for ${\mathit{t}}^{\ell }$ . Also note that the Taylor coefficients for $\mathit{X}(\mathit{t})$ correspond to the derivatives of $\mathit{X}(\mathit{t})$ at $\mathit{t}=0$ in the following way: $${\mathit{x}}_{\mathit{j}}^{\ell }=\frac{1}{\ell !}{\mathit{X}}_{\mathit{j}}^{(\ell )}(0)$$
ty
In calls to forward , the argument ty has prototype
     CppAD::vector<Base>& ty
while in calls to reverse it has prototype
     const CppAD::vector<Base>& ty
For all calls, tx.size() >= (k + 1) * m . For $\mathit{i}=0,\dots ,\mathit{m}-1$ and $\ell =0,\dots ,\mathit{k}$ , we use the Taylor coefficient notation $$\begin{array}{ccc}\hfill {\mathit{y}}_{\mathit{i}}^{\ell }& \hfill =\hfill & \mathit{ty}[\mathit{i}*(\mathit{k}+1)+\ell ]\hfill \\ \hfill {\mathit{Y}}_{\mathit{i}}(\mathit{t})& \hfill =\hfill & {\mathit{y}}_{\mathit{i}}^0+{\mathit{y}}_{\mathit{i}}^1{\mathit{t}}^1+\cdots +{\mathit{y}}_{\mathit{i}}^{\mathit{k}}{\mathit{t}}^{\mathit{k}}+\mathit{o}({\mathit{t}}^{\mathit{k}})\hfill \end{array}$$ where $\mathit{o}({\mathit{t}}^{\mathit{k}})/{\mathit{t}}^{\mathit{k}}\to 0$ as $\mathit{t}\to 0$ . If ty.size() > (k + 1) * m , the other components of ty are not specified and should not be used. Note that superscripts represent an index for ${\mathit{y}}_{\mathit{j}}^{\ell }$ and an exponent for ${\mathit{t}}^{\ell }$ . Also note that the Taylor coefficients for $\mathit{Y}(\mathit{t})$ correspond to the derivatives of $\mathit{Y}(\mathit{t})$ at $\mathit{t}=0$ in the following way: $${\mathit{y}}_{\mathit{j}}^{\ell }=\frac{1}{\ell !}{\mathit{Y}}_{\mathit{j}}^{(\ell )}(0)$$
afun
The macro argument afun , is the name of the AD function corresponding to this atomic operation (as it is used in the source code). CppAD uses the other functions, where the arguments are vectors with elements of type Base , to implement the function
     afun(id, ax, ay)
where the argument are vectors with elements of type AD<Base> .

ax
The afun argument ax has prototype
     const Tvector< AD<Base> >& ax
It is the argument vector $\mathit{x}\in {\mathit{B}}^{\mathit{n}}$ at which the AD<Base> version of $\mathit{y}=\mathit{f}(\mathit{x})$ is to be evaluated. The dimension of the domain space for $\mathit{y}=\mathit{f}(\mathit{x})$ is specified by n = ax.size() , which must be greater than zero.

ay
The afun result ay has prototype
     Tvector< AD<Base> >& ay
The input values of its elements do not matter. Upon return, it is the AD<Base> version of the result vector $\mathit{y}=\mathit{f}(\mathit{x})$ . The dimension of the range space for $\mathit{y}=\mathit{f}(\mathit{x})$ is specified by m = ay.size() , which must be greater than zero.

Parallel Mode
The first call to
     afun(id, ax, ay)
must not be in parallel mode. In addition, the user_atomic clear routine cannot be called while in parallel mode.

forward
The macro argument forward is a user defined function
     ok = forward(id, k, n, m, vx, vy, tx, ty)
that computes results during a forward mode sweep. For this call, we are given the Taylor coefficients in tx form order zero through k , and the Taylor coefficients in ty with order less than k . The forward routine computes the k order Taylor coefficients for $\mathit{y}$ using the definition $\mathit{Y}(\mathit{t})=\mathit{f}[\mathit{X}(\mathit{t})]$ . For example, for $\mathit{i}=0,\dots ,\mathit{m}-1$ , $$\begin{array}{ccc}\hfill {\mathit{y}}_{\mathit{i}}^0& \hfill =\hfill & \mathit{Y}(0)={\mathit{f}}_{\mathit{i}}({\mathit{x}}^0)\hfill \\ \hfill {\mathit{y}}_{\mathit{i}}^1& \hfill =\hfill & {\mathit{Y}}^{(1)}(0)={\mathit{f}}_{\mathit{i}}^{(1)}({\mathit{x}}^0){\mathit{X}}^{(1)}(0)={\mathit{f}}_{\mathit{i}}^{(1)}({\mathit{x}}^0){\mathit{x}}^1\hfill \end{array}$$ Then, for $\mathit{i}=0,\dots ,\mathit{m}-1$ , it sets $$\mathit{ty}[\mathit{i}*(\mathit{k}+1)+\mathit{k}]={\mathit{y}}_{\mathit{i}}^{\mathit{k}}$$ The other components of ty must be left unchanged.

Usage
This routine is used, with vx.size() > 0 and k == 0 , by calls to afun . It is used, with vx.size() = 0 and k equal to the order of the derivative begin computed, by calls to forward .

vx
The forward argument vx has prototype
     const CppAD::vector<bool>& vx
The case vx.size() > 0 occurs once for each call to afun , during the call, and before any of the other callbacks corresponding to that call. Hence such a call can be used to cache information attached to the corresponding id (such as the elements of vx ). If vx.size() > 0 then k == 0 , vx.size() >= n , and for $\mathit{j}=0,\dots ,\mathit{n}-1$ , vx[j] is true if and only if ax[j] is a variable .

If vx.size() == 0 , then vy.size() == 0 and neither of these vectors should be used.

vy
The forward argument vy has prototype
     CppAD::vector<bool>& vy
If vy.size() == 0 , it should not be used. Otherwise, k == 0 and vy.size() >= m . The input values of the elements of vy do not matter. Upon return, for $\mathit{j}=0,\dots ,\mathit{m}-1$ , vy[i] is true if and only if ay[j] is a variable. (CppAD uses vy to reduce the necessary computations.)

reverse
The macro argument reverse is a user defined function
     ok = reverse(id, k, n, m, tx, ty, px, py)
that computes results during a reverse mode sweep. The input value of the vectors tx and ty contain Taylor coefficient, up to order k , for $\mathit{X}(\mathit{t})$ and $\mathit{Y}(\mathit{t})$ respectively. We use the $\{{\mathit{x}}_{\mathit{j}}^{\ell }\}$ and $\{{\mathit{y}}_{\mathit{i}}^{\ell }\}$ to denote these Taylor coefficients where the implicit range indices are $\mathit{i}=0,\dots ,\mathit{m}-1$ , $\mathit{j}=0,\dots ,\mathit{n}-1$ , $\ell =0,\dots ,\mathit{k}$ . Using the calculations done by forward , the Taylor coefficients $\{{\mathit{y}}_{\mathit{i}}^{\ell }\}$ are a function of the Taylor coefficients for $\{{\mathit{x}}_{\mathit{j}}^{\ell }\}$ ; i.e., given $\mathit{y}=\mathit{f}(\mathit{x})$ we define the function $\mathit{F}:{\mathit{B}}^{\mathit{n}\times (\mathit{k}+1)}\to {\mathit{B}}^{\mathit{m}\times (\mathit{k}+1)}$ by $${\mathit{y}}_{\mathit{i}}^{\ell }={\mathit{F}}_{\mathit{i}}^{\ell }(\{{\mathit{x}}_{\mathit{j}}^{\ell }\})$$ We use $\mathit{G}:{\mathit{B}}^{\mathit{m}\times (\mathit{k}+1)}\to \mathit{B}$ to denote an arbitrary scalar valued function of the Taylor coefficients for $\mathit{Y}(\mathit{t})$ and write $\mathit{z}=\mathit{G}(\{{\mathit{y}}_{\mathit{i}}^{\ell }\})$ . The reverse routine is given the derivative of $\mathit{z}$ with respect to $\{{\mathit{y}}_{\mathit{i}}^{\ell }\}$ and computes its derivative with respect to $\{{\mathit{x}}_{\mathit{j}}^{\ell }\}$ .

Usage
This routine is used, with k + 1 equal to the order of the derivative being calculated, by calls to reverse .

py
The reverse argument py has prototype
     const CppAD::vector<Base>& py
and py.size() >= (k + 1) * m . For $\mathit{i}=0,\dots ,\mathit{m}-1$ and $\ell =0,\dots ,\mathit{k}$ , $$\mathit{py}[\mathit{i}*(\mathit{k}+1)+\ell ]=\partial \mathit{G}/\partial {\mathit{y}}_{\mathit{i}}^{\ell }$$ If py.size() > (k + 1) * m , the other components of py are not specified and should not be used.

px
We define the function $$\mathit{H}(\{{\mathit{x}}_{\mathit{j}}^{\ell }\})=\mathit{G}[\mathit{F}(\{{\mathit{x}}_{\mathit{j}}^{\ell }\})]$$ The reverse argument px has prototype
     CppAD::vector<Base>& px
and px.size() >= (k + 1) * n . The input values of the elements of px do not matter. Upon return, for $\mathit{j}=0,\dots ,\mathit{n}-1$ and $\ell =0,\dots ,\mathit{k}$ , $$\begin{array}{ccc}\hfill \mathit{px}[\mathit{j}*(\mathit{k}+1)+\ell ]& \hfill =\hfill & \partial \mathit{H}/\partial {\mathit{x}}_{\mathit{j}}^{\ell }\hfill \\ \hfill & \hfill =\hfill & (\partial \mathit{G}/\partial \{{\mathit{y}}_{\mathit{i}}^{\ell }\})(\partial \{{\mathit{y}}_{\mathit{i}}^{\ell }\}/\partial {\mathit{x}}_{\mathit{j}}^{\ell })\hfill \\ \hfill & \hfill =\hfill & \sum _{\mathit{i}=0}^{\mathit{m}-1}\sum _{\ell =0}^{\mathit{k}}(\partial \mathit{G}/\partial {\mathit{y}}_{\mathit{i}}^{\ell })(\partial {\mathit{y}}_{\mathit{i}}^{\ell }/\partial {\mathit{x}}_{\mathit{j}}^{\ell })\hfill \\ \hfill & \hfill =\hfill & \sum _{\mathit{i}=0}^{\mathit{m}-1}\sum _{\ell =0}^{\mathit{k}}\mathit{py}[\mathit{i}*(\mathit{k}+1)+\ell ](\partial {\mathit{F}}_{\mathit{i}}^{\ell }/\partial {\mathit{x}}_{\mathit{j}}^{\ell })\hfill \end{array}$$ If px.size() > (k + 1) * n , the other components of px are not specified and should not be used.

for_jac_sparse
The macro argument for_jac_sparse is a user defined function
     ok = for_jac_sparse(id, n, m, q, r, s)
that is used to compute results during a forward Jacobian sparsity sweep. For a fixed $\mathit{n}\times \mathit{q}$ matrix $\mathit{R}$ , the Jacobian of $\mathit{f}(\mathit{x}+\mathit{R}*\mathit{u})$ with respect to $\mathit{u}\in {\mathit{B}}^{\mathit{q}}$ is $$\mathit{S}(\mathit{x})={\mathit{f}}^{(1)}(\mathit{x})*\mathit{R}$$ Given a sparsity pattern for $\mathit{R}$ , for_jac_sparse computes a sparsity pattern for $\mathit{S}(\mathit{x})$ .

Usage
This routine is used by calls to ForSparseJac .

q
The for_jac_sparse argument q has prototype
     size_t q
It specifies the number of columns in $\mathit{R}\in {\mathit{B}}^{\mathit{n}\times \mathit{q}}$ and the Jacobian $\mathit{S}(\mathit{x})\in {\mathit{B}}^{\mathit{m}\times \mathit{q}}$ .

r
The for_jac_sparse argument r has prototype
     const CppAD::vector< std::set<size_t> >& r
and r.size() >= n . For $\mathit{j}=0,\dots ,\mathit{n}-1$ , all the elements of r[j] are between zero and q-1 inclusive. This specifies a sparsity pattern for the matrix $\mathit{R}$ .

s
The for_jac_sparse return value s has prototype
     CppAD::vector< std::set<size_t> >& s
and s.size() >= m . The input values of its sets do not matter. Upon return for $\mathit{i}=0,\dots ,\mathit{m}-1$ , all the elements of s[i] are between zero and q-1 inclusive. This represents a sparsity pattern for the matrix $\mathit{S}(\mathit{x})$ .

rev_jac_sparse
The macro argument rev_jac_sparse is a user defined function
     ok = rev_jac_sparse(id, n, m, q, r, s)
that is used to compute results during a reverse Jacobian sparsity sweep. For a fixed $\mathit{q}\times \mathit{m}$ matrix $\mathit{S}$ , the Jacobian of $\mathit{S}*\mathit{f}(\mathit{x})$ with respect to $\mathit{x}\in {\mathit{B}}^{\mathit{n}}$ is $$\mathit{R}(\mathit{x})=\mathit{S}*{\mathit{f}}^{(1)}(\mathit{x})$$ Given a sparsity pattern for $\mathit{S}$ , rev_jac_sparse computes a sparsity pattern for $\mathit{R}(\mathit{x})$ .

Usage
This routine is used by calls to RevSparseJac and to optimize .

q
The rev_jac_sparse argument q has prototype
     size_t q
It specifies the number of rows in $\mathit{S}\in {\mathit{B}}^{\mathit{q}\times \mathit{m}}$ and the Jacobian $\mathit{R}(\mathit{x})\in {\mathit{B}}^{\mathit{q}\times \mathit{n}}$ .

s
The rev_jac_sparse argument s has prototype
     const CppAD::vector< std::set<size_t> >& s
and s.size() >= m . For $\mathit{i}=0,\dots ,\mathit{m}-1$ , all the elements of s[i} are between zero and q-1 inclusive. This specifies a sparsity pattern for the matrix ${\mathit{S}}^{\mathrm{T}}$ .

r
The rev_jac_sparse return value r has prototype
     CppAD::vector< std::set<size_t> >& r
and r.size() >= n . The input values of its sets do not matter. Upon return for $\mathit{j}=0,\dots ,\mathit{n}-1$ , all the elements of r[j] are between zero and q-1 inclusive. This represents a sparsity pattern for the matrix $\mathit{R}(\mathit{x}{)}^{\mathrm{T}}$ .

rev_hes_sparse
The macro argument rev_hes_sparse is a user defined function
     ok = rev_hes_sparse(id, n, m, q, r, s, t, u, v)
There is an unspecified scalar valued function $\mathit{g}:{\mathit{B}}^{\mathit{m}}\to \mathit{B}$ . Given a sparsity pattern for $\mathit{R}$ and information about the function $\mathit{z}=\mathit{g}(\mathit{y})$ , this routine computes the sparsity pattern for $$\mathit{V}(\mathit{x})=(\mathit{g}\circ \mathit{f}{)}^{(2)}(\mathit{x})\mathit{R}$$
Usage
This routine is used by calls to RevSparseHes .

q
The rev_hes_sparse argument q has prototype
     size_t q
It specifies the number of columns in the sparsity patterns.

r
The rev_hes_sparse argument r has prototype
     const CppAD::vector< std::set<size_t> >& r
and r.size() >= n . For $\mathit{j}=0,\dots ,\mathit{n}-1$ , all the elements of r[j] are between zero and q-1 inclusive. This specifies a sparsity pattern for the matrix $\mathit{R}\in {\mathit{B}}^{\mathit{n}\times \mathit{q}}$ .

s
The rev_hes_sparse argument s has prototype
     const CppAD::vector<bool> >& s
and s.size() >= m . This specifies a sparsity pattern for the matrix $\mathit{S}(\mathit{x})={\mathit{g}}^{(1)}(\mathit{y})\in {\mathit{B}}^{1\times \mathit{m}}$ .

t
The rev_hes_sparse argument t has prototype
     CppAD::vector<bool> >& t
and t.size() >= n . The input values of its elements do not matter. Upon return it represents a sparsity pattern for the matrix $\mathit{T}(\mathit{x})=(\mathit{g}\circ \mathit{f}{)}^{(1)}(\mathit{x})\in {\mathit{B}}^{1\times \mathit{n}}$ .

u
The rev_hes_sparse argument u has prototype
     const CppAD::vector< std::set<size_t> >& u
and u.size() >= m . For $\mathit{i}=0,\dots ,\mathit{m}-1$ , all the elements of u[i] are between zero and q-1 inclusive. This specifies a sparsity pattern for the matrix $\mathit{U}(\mathit{x})\in {\mathit{B}}^{\mathit{m}\times \mathit{q}}$ defined by $$\begin{array}{ccc}\hfill \mathit{U}(\mathit{x})& \hfill =\hfill & {\partial }_{\mathit{u}}\{{\partial }_{\mathit{y}}\mathit{g}[\mathit{y}+{\mathit{f}}^{(1)}(\mathit{x})\mathit{R}\mathit{u}]{\}}_{\mathit{u}=0}\hfill \\ \hfill & \hfill =\hfill & {\partial }_{\mathit{u}}\{{\mathit{g}}^{(1)}[\mathit{y}+{\mathit{f}}^{(1)}(\mathit{x})\mathit{R}\mathit{u}]{\}}_{\mathit{u}=0}\hfill \\ \hfill & \hfill =\hfill & {\mathit{g}}^{(2)}(\mathit{y}){\mathit{f}}^{(1)}(\mathit{x})\mathit{R}\hfill \end{array}$$
v
The rev_hes_sparse argument v has prototype
     CppAD::vector< std::set<size_t> >& v
and v.size() >= n . The input values of its elements do not matter. Upon return, for $\mathit{j}=0,\dots ,\mathit{n}-1$ , all the elements of v[j] are between zero and q-1 inclusive. This represents a sparsity pattern for the matrix $\mathit{V}(\mathit{x})\in {\mathit{B}}^{\mathit{n}\times \mathit{q}}$ defined by $$\begin{array}{ccc}\hfill \mathit{V}(\mathit{x})& \hfill =\hfill & {\partial }_{\mathit{u}}[{\partial }_{\mathit{x}}(\mathit{g}\circ \mathit{f})(\mathit{x}+\mathit{R}\mathit{u}){]}_{\mathit{u}=0}\hfill \\ \hfill & \hfill =\hfill & {\partial }_{\mathit{u}}[(\mathit{g}\circ \mathit{f}{)}^{(1)}(\mathit{x}+\mathit{R}\mathit{u}){]}_{\mathit{u}=0}\hfill \\ \hfill & \hfill =\hfill & (\mathit{g}\circ \mathit{f}{)}^{(2)}(\mathit{x})\mathit{R}\hfill \end{array}$$
clear
User atomic functions hold onto static work space in order to increase speed by avoiding system memory allocation calls. The function call
     user_atomic<Base>::clear()
makes to work space available 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 Base .

Restriction
The user atomic clear routine cannot be called while in parallel execution mode.

Example

Tangent Function
The file user_tan.cpp contains an example and test implementation of the tangent function as a user atomic operation.

Matrix Multiplication
The file mat_mul.cpp contains an example and test implementation of matrix multiplication a a user atomic operation.

---

Input File: cppad/local/user_atomic.hpp