User Defined Atomic AD Functions
Keywords: user defined atomic ad functions operation old_atomic deprecated 2013-05-27 syntax function use callback routines free static memory purpose partial implementation cppad_user_atomic tvector base ok id k n m tx ty forward reverse afun ax ay parallel mode usage vx vy py px for_jac_sparse q r s rev_jac_sparse rev_hes_sparse t u v clear restriction example simple tangent matrix multiplication

| Prev | Next |  |  |  |  |  |  |

User Defined Atomic AD Functions
Deprecated 2013-05-27
Using `CPPAD_USER_ATOMIC` has been deprecated. Use atomic_base instead.
Syntax 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 y = f ( x ) where f : B n → B m more efficiently than by coding it using `AD<Base>` atomic operations and letting CppAD do the rest. In this case, `CPPAD_USER_ATOMIC` can be used add the user code for f ( x ) , and its derivatives, to the set of `AD<Base>` atomic operations. `
` Another possible purpose is to reduce the size of the tape; see use AD
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 y = f ( 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 y = f ( x ) .
tx
For all routines documented below, the argument `tx` has prototype `
const CppAD::vector<Base>& tx
` and `tx.size() >= (k + 1) * n` . For j = 0 , … , n -1 and ℓ = 0 , … , k , we use the Taylor coefficient notation x j ℓ = tx [ j * ( k + 1 ) + ℓ ] X j ( t ) = x j 0 + x j 1 t 1 + ⋯ + x j k t k 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 x j ℓ and an exponent for t ℓ . Also note that the Taylor coefficients for X ( t ) correspond to the derivatives of X ( t ) at t = 0 in the following way: x j ℓ = 1 ℓ ! X j ( ℓ ) ( 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 i = 0 , … , m -1 and ℓ = 0 , … , k , we use the Taylor coefficient notation y i ℓ = ty [ i * ( k + 1 ) + ℓ ] Y i ( t ) = y i 0 + y i 1 t 1 + ⋯ + y i k t k + o ( t k ) where o ( t k ) / t k → 0 as t → 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 y j ℓ and an exponent for t ℓ . Also note that the Taylor coefficients for Y ( t ) correspond to the derivatives of Y ( t ) at t = 0 in the following way: y j ℓ = 1 ℓ ! Y j ( ℓ ) ( 0 )
forward
In the case of `forward` , for i = 0 , … , m -1 , ty [ i * ( k + 1 ) + k ] is an output and all the other components of `ty` are inputs.
reverse
In the case of `reverse` , all the components of `ty` are inputs.
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 x ∈ B n at which the `AD<Base>` version of y = f ( x ) is to be evaluated. The dimension of the domain space for y = f ( 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 are not specified (must not matter). Upon return, it is the `AD<Base>` version of the result vector y = f ( x ) . The dimension of the range space for y = f ( 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 old_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 y using the definition Y ( t ) = f [ X ( t ) ] . For example, for i = 0 , … , m -1 , y i 0 = Y ( 0 ) = f i ( x 0 ) y i 1 = Y ( 1 ) ( 0 ) = f i ( 1 ) ( x 0 ) X ( 1 ) ( 0 ) = f i ( 1 ) ( x 0 ) x 1 y i 2 = 1 2 ! Y ( 2 ) ( 0 ) = 1 2 X ( 1 ) ( 0 ) T f i ( 2 ) ( x 0 ) X ( 1 ) ( 0 ) + 1 2 f i ( 1 ) ( x 0 ) X ( 2 ) ( 0 ) = 1 2 ( x 1 ) T f i ( 2 ) ( x 0 ) x 1 + f i ( 1 ) ( x 0 ) x 2 Then, for i = 0 , … , m -1 , it sets ty [ i * ( k + 1 ) + k ] = y i 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 j = 0 , … , 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` are not specified (must not matter). Upon return, for j = 0 , … , 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 X ( t ) and Y ( t ) respectively. We use the { x j ℓ } and { y i ℓ } to denote these Taylor coefficients where the implicit range indices are i = 0 , … , m -1 , j = 0 , … , n -1 , ℓ = 0 , … , k . Using the calculations done by forward , the Taylor coefficients { y i ℓ } are a function of the Taylor coefficients for { x j ℓ } ; i.e., given y = f ( x ) we define the function F : B n × ( k + 1 ) → B m × ( k + 1 ) by y i ℓ = F i ℓ ( { x j ℓ } ) We use G : B m × ( k + 1 ) → B to denote an arbitrary scalar valued function of the Taylor coefficients for Y ( t ) and write z = G ( { y i ℓ } ) . The `reverse` routine is given the derivative of z with respect to { y i ℓ } and computes its derivative with respect to { x j ℓ } .
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 i = 0 , … , m -1 and ℓ = 0 , … , k , py [ i * ( k + 1 ) + ℓ ] = ∂ G / ∂ y i ℓ If `py.size() > (k + 1) * m` , the other components of `py` are not specified and should not be used.
px
We define the function H ( { x j ℓ } ) = G [ F ( { x j ℓ } ) ] The `reverse` argument `px` has prototype `
CppAD::vector<Base>& px
` and `px.size() >= (k + 1) * n` . The input values of the elements of `px` are not specified (must not matter). Upon return, for j = 0 , … , n -1 and p = 0 , … , k , px [ j * ( k + 1 ) + p ] = ∂ H / ∂ x j p = ( ∂ G / ∂ { y i ℓ } ) ( ∂ { y i ℓ } / ∂ x j p ) = ∑ i = 0 m -1 ∑ ℓ = 0 k ( ∂ G / ∂ y i ℓ ) ( ∂ y i ℓ / ∂ x j p ) = ∑ i = 0 m -1 ∑ ℓ = p k py [ i * ( k + 1 ) + ℓ ] ( ∂ F i ℓ / ∂ x j p ) Note that we have used the fact that for ℓ < p , ∂ F i ℓ / ∂ x j p = 0 . 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 n × q matrix R , the Jacobian of f ( x + R * u ) with respect to u ∈ B q is S ( x ) = f ( 1 ) ( x ) * R Given a sparsity pattern for R , `for_jac_sparse` computes a sparsity pattern for S ( 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 R ∈ B n × q and the Jacobian S ( x ) ∈ B m × q .
r
The `for_jac_sparse` argument `r` has prototype `
const CppAD::vector< std::set<size_t> >& r
` and `r.size() >= n` . For j = 0 , … , n -1 , all the elements of `r[j]` are between zero and `q-1` inclusive. This specifies a sparsity pattern for the matrix 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 are not specified (must not matter). Upon return for i = 0 , … , m -1 , all the elements of `s[i]` are between zero and `q-1` inclusive. This represents a sparsity pattern for the matrix S ( 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 q × m matrix S , the Jacobian of S * f ( x ) with respect to x ∈ B n is R ( x ) = S * f ( 1 ) ( x ) Given a sparsity pattern for S , `rev_jac_sparse` computes a sparsity pattern for R ( 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 S ∈ B q × m and the Jacobian R ( x ) ∈ B q × n .
s
The `rev_jac_sparse` argument `s` has prototype `
const CppAD::vector< std::set<size_t> >& s
` and `s.size() >= m` . For i = 0 , … , m -1 , all the elements of `s[i]` are between zero and `q-1` inclusive. This specifies a sparsity pattern for the matrix S 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 are not specified (must not matter). Upon return for j = 0 , … , n -1 , all the elements of `r[j]` are between zero and `q-1` inclusive. This represents a sparsity pattern for the matrix R ( x ) 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 g : B m → B . Given a sparsity pattern for R and information about the function z = g ( y ) , this routine computes the sparsity pattern for V ( x ) = ( g ∘ f ) ( 2 ) ( x ) 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 j = 0 , … , n -1 , all the elements of `r[j]` are between zero and `q-1` inclusive. This specifies a sparsity pattern for the matrix R ∈ B n × 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 S ( x ) = g ( 1 ) ( y ) ∈ B 1 × m .
t
The `rev_hes_sparse` argument `t` has prototype `
CppAD::vector<bool>& t
` and `t.size() >= n` . The input values of its elements are not specified (must not matter). Upon return it represents a sparsity pattern for the matrix T ( x ) ∈ B 1 × n defined by T ( x ) = ( g ∘ f ) ( 1 ) ( x ) = S ( x ) * f ( 1 ) ( x )
u
The `rev_hes_sparse` argument `u` has prototype `
const CppAD::vector< std::set<size_t> >& u
` and `u.size() >= m` . For i = 0 , … , m -1 , all the elements of `u[i]` are between zero and `q-1` inclusive. This specifies a sparsity pattern for the matrix U ( x ) ∈ B m × q defined by U ( x ) = ∂ u { ∂ y g [ y + f ( 1 ) ( x ) R u ] } u = 0 = ∂ u { g ( 1 ) [ y + f ( 1 ) ( x ) R u ] } u = 0 = g ( 2 ) ( y ) f ( 1 ) ( x ) R
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 are not specified (must not matter). Upon return, for j = 0 , … , n -1 , all the elements of `v[j]` are between zero and `q-1` inclusive. This represents a sparsity pattern for the matrix V ( x ) ∈ B n × q defined by V ( x ) = ∂ u [ ∂ x ( g ∘ f ) ( x + R u ) ] u = 0 = ∂ u [ ( g ∘ f ) ( 1 ) ( x + R u ) ] u = 0 = ( g ∘ f ) ( 2 ) ( x ) R = f ( 1 ) ( x ) T g ( 2 ) ( y ) f ( 1 ) ( x ) R + ∑ i = 1 m [ g ( 1 ) ( y ) ] i f i ( 2 ) ( x ) R = f ( 1 ) ( x ) T U ( x ) + ∑ i = 1 m S ( x ) i f i ( 2 ) ( x ) R
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
Simple
The file old_reciprocal.cpp contains the simplest example and test of a user atomic operation.
Use AD
The examples old_usead_1.cpp and old_usead_2.cpp use AD to compute the derivatives inside a user defined atomic function. This may have the advantage of reducing the size of the tape, because a repeated section of code would only be taped once.
Tangent Function
The file old_tan.cpp contains an example and test implementation of the tangent function as a user atomic operation.
Matrix Multiplication
The file old_mat_mul.cpp contains an example and test implementation of matrix multiplication a a user atomic operation.

Input File: cppad/local/old_atomic.hpp