Prev

Next

Index-> contents reference index search external

Up-> CppAD ADFun sparsity_pattern ForSparseJac

Headings-> Syntax Purpose f ---..size_forward_bool ---..size_forward_set x q transpose dependency r ---..transpose false ---..transpose true s ---..transpose false ---..transpose true SetVector Entire Sparsity Pattern Example

@(@\newcommand{\W}[1]{ \; #1 \; } \newcommand{\R}[1]{ {\rm #1} } \newcommand{\B}[1]{ {\bf #1} } \newcommand{\D}[2]{ \frac{\partial #1}{\partial #2} } \newcommand{\DD}[3]{ \frac{\partial^2 #1}{\partial #2 \partial #3} } \newcommand{\Dpow}[2]{ \frac{\partial^{#1}}{\partial {#2}^{#1}} } \newcommand{\dpow}[2]{ \frac{ {\rm d}^{#1}}{{\rm d}\, {#2}^{#1}} }@)@This is cppad-20221105 documentation. Here is a link to its current documentation . Jacobian Sparsity Pattern: Forward Mode
Syntax
s = f.ForSparseJac(q, r)
s = f.ForSparseJac(q, r, transpose, dependency)

Purpose
We use @(@ F : \B{R}^n \rightarrow \B{R}^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 @[@ 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 SetVector 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 k to the amount of memory (in unsigned character units) used to store the vector of sets sparsity patterns. 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. 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
If the operation sequence in f is independent of the independent variables in @(@ x \in \B{R}^n @)@, the sparsity pattern is valid for all values of (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 \in \B{R}^{n \times q} @)@ and the Jacobian @(@ S(x) \in \B{R}^{m \times 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 SetVector& r
see SetVector 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 \in \B{R}^{n \times 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^\R{T} \in \B{R}^{q \times n} @)@.

s
The return value s has prototype
    SetVector s
see SetVector 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) \in \B{R}^{m \times 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)^\R{T} \in \B{R}^{q \times m} @)@.

SetVector
The type SetVector 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 \times 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. 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: include/cppad/core/for_sparse_jac.hpp