Prev | Next |

@(@\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}} }@)@

*s* = *f*.ForSparseJac(*q*, *r*)

*s* = *f*.ForSparseJac(*q*, *r*, *transpose*, *dependency*)

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
@[@
S(x) = F^{(1)} ( x ) * R
@]@
Given a
sparsity pattern
for @(@
R
@)@,
`ForSparseJac`

returns a sparsity pattern for the @(@
S(x)
@)@.
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).
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.
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.
If the operation sequence in

*f*

is
independent
of
the independent variables in @(@
x \in B^n
@)@,
the sparsity pattern is valid for all values of
(even if it has CondExp
or VecAD
operations).
The argument

*q*

has prototype

size_t *q*

It specifies the number of columns in
@(@
R \in B^{n \times q}
@)@ and the Jacobian
@(@
S(x) \in B^{m \times q}
@)@.
The argument

*transpose*

has prototype

bool *transpose*

The default value `false`

is used when
*transpose*

is not present.
The argument

*dependency*

has prototype

bool *dependency*

If
*dependency*

is true,
the dependency pattern
(instead of sparsity pattern) is computed.
The argument

*r*

has prototype

const *VectorSet*& *r*

see VectorSet
below.
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^{n \times q}
@)@.
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^{q \times n}
@)@.
The return value

*s*

has prototype

*VectorSet* *s*

see VectorSet
below.
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^{m \times q}
@)@.
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^{q \times m}
@)@.
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.
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 )
@)@.
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/core/for_sparse_jac.hpp