for_jac_sparsity

View page source

Forward Mode Jacobian Sparsity Patterns

Syntax

f . for_jac_sparsity (
      pattern_in , transpose , dependency , internal_bool , pattern_out
)

Purpose

We use \(F : \B{R}^n \rightarrow \B{R}^m\) to denote the AD Function corresponding to the operation sequence stored in f . Fix \(R \in \B{R}^{n \times \ell}\) and define the function

\[J(x) = F^{(1)} ( x ) * R\]

Given the Sparsity Pattern for \(R\), for_jac_sparsity computes a sparsity pattern for \(J(x)\).

x

Note that the sparsity pattern \(J(x)\) corresponds to the operation sequence stored in f and does not depend on the argument x . (The operation sequence may contain CondExp and VecAD operations.)

SizeVector

The type SizeVector is a SimpleVector class with elements of type size_t .

f

The object f has prototype

ADFun < Base > f

The ADFun object f is not const . After a call to for_jac_sparsity , a sparsity pattern for each of the variables in the operation sequence is held in f for possible later use during reverse Hessian sparsity calculations.

size_forward_bool

After for_jac_sparsity , 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 Boolean Vector sparsity patterns. If internal_bool if false, k will be zero. Otherwise it will be non-zero. If you do not need this information for RevSparseHes calculations, it can be deleted (and the corresponding memory freed) using

f . size_forward_bool (0)

after which f . size_forward_bool () will return zero.

size_forward_set

After for_jac_sparsity , 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 internal_bool if true, k will be zero. Otherwise it will be non-zero. If you do not need this information for future rev_hes_sparsity calculations, it can be deleted (and the corresponding memory freed) using

f . size_forward_set (0)

after which f . size_forward_set () will return zero.

pattern_in

The argument pattern_in has prototype

const sparse_rc < SizeVector >& pattern_in

see sparse_rc . If transpose it is false (true), pattern_in is a sparsity pattern for \(R\) (\(R^\R{T}\)).

transpose

This argument has prototype

bool transpose

See pattern_in above and pattern_out below.

dependency

This argument has prototype

bool dependency

see pattern_out below.

internal_bool

This argument has prototype

bool internal_bool

If this is true, calculations are done with sets represented by a vector of boolean values. Otherwise, a vector of sets of integers is used.

pattern_out

This argument has prototype

sparse_rc < SizeVector >& pattern_out

This input value of pattern_out does not matter. If transpose it is false (true), upon return pattern_out is a sparsity pattern for \(J(x)\) (\(J(x)^\R{T}\)). If dependency is true, pattern_out is a Dependency Pattern instead of sparsity pattern.

Sparsity for Entire Jacobian

Suppose that \(R\) is the \(n \times n\) identity matrix. In this case, pattern_out is a sparsity pattern for \(F^{(1)} ( x )\) ( \(F^{(1)} (x)^\R{T}\) ) if transpose is false (true).

Example

The file for_jac_sparsity.cpp contains an example and test of this operation.