Prev Next

Jacobian Sparsity Pattern: Forward Mode

Syntax
s = f.ForSparseJac(qr)

Purpose
We use  F : B^n \rightarrow B^m to denote the AD function corresponding to f. For a fixed  n \times q matrix  R , the Jacobian of  F[ x + R * u ] with respect to  u at  u = 0 is  \[
     J(x) = F^{(1)} ( x ) * R
\] 
Given a sparsity pattern for  R , ForSparseJac returns a sparsity pattern for the  J(x) .

f
The object f has prototype
     ADFun<
Basef
Note that the ADFun object f is not const. After this the sparsity pattern for each of the variables in the operation sequence is stored in the object f.

x
If no VecAD objects are used by the AD of Base operation sequence stored in f, the sparsity pattern is valid for all values  x \in B^n .

If f.useVecAD is true, the sparsity patter is only valid for the value of x in the previous zero order forward mode call
     
f.Forward(0, x)
If there is no previous zero order forward mode call using f, the value of the independent variables during the recording of the AD sequence of operations is used for x.

q
The argument q has prototype
     size_t 
q
It specifies the number of columns in the Jacobian  J(x) . Note that the memory required for the calculation is proportional to  q times the total number of variables in the AD operation sequence corresponding to f (f.size_var ). Smaller values for q can be used to break the sparsity calculation into groups that do not require to much memory.

r
The argument r has prototype
     const 
Vector &r
(see Vector below) and its size is  n * q . It specifies a sparsity pattern for the matrix R as follows: for  i = 0 , \ldots , n-1 and  j = 0 , \ldots , q-1 .  \[
     R_{i,j} \neq 0 ; \Rightarrow \; r [ i * q + j ] = {\rm true}
\] 


s
The return value s has prototype
     
Vector s
(see Vector below) and its size is  m * q . It specifies a sparsity pattern for the matrix  J(x) as follows: for  x \in B^n , for  i = 0 , \ldots , m-1 , and  j = 0 , \ldots , q-1  \[
     J(x)_{i,j} \neq 0 ; \Rightarrow \; s [ i * q + j ] = {\rm true}
\] 


Vector
The type Vector must be a SimpleVector class with elements of type bool . The routine CheckSimpleVector will generate an error message if this is not the case. In order to save memory, you may want to use a class that packs multiple elements into one storage location; for example, vectorBool .

Entire Sparsity Pattern
Suppose that  q = n and  R is the  n \times n identity matrix, If follows that  \[
r [ i * q + j ] = \left\{ \begin{array}{ll}
     {\rm true}  & {\rm if} \; i = j \\
     {\rm flase} & {\rm otherwise}
\end{array} \right. 
\] 
is an efficient sparsity pattern for  R ; i.e., the choice for r has as few true values as possible. In this case, the corresponding value for s is a sparsity pattern for the Jacobian  J(x) = F^{(1)} ( x ) .

Example
The file ForSparseJac.cpp contains an example and test of this operation. It returns true if it succeeds and false otherwise.
Input File: cppad/local/for_sparse_jac.hpp