Jacobian Sparsity Pattern: Forward Mode
Keywords: jacobian sparsity pattern: forward mode syntax purpose f size_forward_bool size_forward_set x q transpose dependency r false true s vectorset entire pattern example

| Prev | Next |  |  |  |  |  |  |

Jacobian Sparsity Pattern: Forward Mode
Syntax
`s = f.ForSparseJac(q, r)
` `s = f.ForSparseJac(q, r, transpose, dependency)`
Purpose
We use F : B n → B m to denote the AD function corresponding to `f` . For a fixed n × q matrix R , the Jacobian of F [ x + R * u ] with respect to u at u = 0 is S ( x ) = F ( 1 ) ( x ) * R Given a sparsity pattern for R , `ForSparseJac` returns a sparsity pattern for the S ( x ) .
f
The object `f` has prototype `
ADFun<Base> f
` Note that the ADFun object `f` is not `const`. After a call to `ForSparseJac`, the sparsity pattern for each of the variables in the operation sequence is held in `f` (for possible later use by RevSparseHes ). These sparsity patterns are stored with elements of type `bool` or elements of type `std::set<size_t>` (see VectorSet below).
size_forward_bool
After `ForSparseJac`, if `k` is a `size_t` object, `
k = f.size_forward_bool()
` sets `k` to the amount of memory (in unsigned character units) used to store the sparsity pattern with elements of type `bool` in the function object `f` . If the sparsity patterns for the previous `ForSparseJac` used elements of type `bool`, the return value for `size_forward_bool` will be non-zero. Otherwise, its return value will be zero. This sparsity pattern is stored for use by RevSparseHes and when it is not longer needed, it can be deleted (and the corresponding memory freed) using `
f.size_forward_bool(0)
` After this call, `f.size_forward_bool()` will return zero.
size_forward_set
After `ForSparseJac`, if `k` is a `size_t` object, `
k = f.size_forward_set()
` sets `s` to the total number of elements in all the sets corresponding to the sparsity pattern stored in the function object `f` . If the sparsity patterns for this operation use elements of type `bool`, the return value for `size_forward_set` will be zero. Otherwise, its return value will be non-zero (unless the entire sparsity pattern is false). This sparsity pattern is stored for use by RevSparseHes and when it is not longer needed, it can be deleted (and the corresponding memory freed) using `
f.size_forward_set(0)
` After this call, `f.size_forward_set()` will return zero.
x
the sparsity pattern is valid for all values of the independent variables in x ∈ B n (even if it has CondExp or VecAD operations).
q
The 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 .
transpose
The argument `transpose` has prototype `
bool transpose
` The default value `false` is used when `transpose` is not present.
dependency
The argument `dependency` has prototype `
bool dependency
` If `dependency` is true, the dependency pattern (instead of sparsity pattern) is computed.
r
The argument `r` has prototype `
const VectorSet& r
` see VectorSet below.
transpose false
If `r` has elements of type `bool`, its size is n * q . If it has elements of type `std::set<size_t>`, its size is n and all the set elements must be between zero and `q-1` inclusive. It specifies a sparsity pattern for the matrix R ∈ B n × q .
transpose true
If `r` has elements of type `bool`, its size is q * n . If it has elements of type `std::set<size_t>`, its size is q and all the set elements must be between zero and `n-1` inclusive. It specifies a sparsity pattern for the matrix R T ∈ B q × n .
s
The return value `s` has prototype `
VectorSet s
` see VectorSet below.
transpose false
If `s` has elements of type `bool`, its size is m * q . If it has elements of type `std::set<size_t>`, its size is m and all its set elements are between zero and `q-1` inclusive. It specifies a sparsity pattern for the matrix S ( x ) ∈ B m × q .
transpose true
If `s` has elements of type `bool`, its size is q * m . If it has elements of type `std::set<size_t>`, its size is q and all its set elements are between zero and `m-1` inclusive. It specifies a sparsity pattern for the matrix S ( x ) T ∈ B q × m .
VectorSet
The type `VectorSet` must be a SimpleVector class with elements of type `bool` or `std::set<size_t>`; see sparsity pattern for a discussion of the difference.
Entire Sparsity Pattern
Suppose that q = n and R is the n × n identity matrix. In this case, the corresponding value for `s` is a sparsity pattern for the Jacobian S ( x ) = F ( 1 ) ( x ) .
Example
The file for_sparse_jac.cpp contains an example and test of this operation. It returns true if it succeeds and false otherwise. The file sparsity_sub.cpp contains an example and test of using `ForSparseJac` to compute the sparsity pattern for a subset of the Jacobian.

Input File: cppad/local/for_sparse_jac.hpp