\(\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}} }\)
sparse_jac¶
View page sourceComputing Sparse Jacobians¶
Syntax¶
sparse_jac_for
(sparse_jac_rev
(Purpose¶
We use \(F : \B{R}^n \rightarrow \B{R}^m\) to denote the function corresponding to f . Here n is the Domain size, and m is the Range size, or f . The syntax above takes advantage of sparsity when computing the Jacobian
In the sparse case, this should be faster and take less memory than Jacobian . We use the notation \(J_{i,j} (x)\) to denote the partial of \(F_i (x)\) with respect to \(x_j\).
SizeVector¶
The type SizeVector is a SimpleVector class with
elements of type
size_t
.
BaseVector¶
The type BaseVector is a SimpleVector class with
elements of type
size_t
.
sparse_jac_for¶
This function uses first order forward mode sweeps forward_one to compute multiple columns of the Jacobian at the same time.
sparse_jac_rev¶
This uses function first order reverse mode sweeps reverse_one to compute multiple rows of the Jacobian at the same time.
f¶
This object has prototype
ADFun
< Base > f
Note that the Taylor coefficients stored in f are affected by this operation; see Uses Forward below.
group_max¶
This argument has prototype
size_t
group_max
and must be greater than zero. It specifies the maximum number of colors to group during a single forward sweep. If a single color is in a group, a single direction for of first order forward mode forward_one is used for each color. If multiple colors are in a group, the multiple direction for of first order forward mode forward_dir is used with one direction for each color. This uses separate memory for each direction (more memory), but my be significantly faster.
x¶
This argument has prototype
const
BaseVector & x
and its size is n . It specifies the point at which to evaluate the Jacobian \(J(x)\).
subset¶
This argument has prototype
sparse_rcv
< SizeVector , BaseVector >& subset
Its row size is subset . nr
() == m ,
and its column size is subset . nc
() == n .
It specifies which elements of the Jacobian are computed.
The input value of its value vector
subset . val
() does not matter.
Upon return it contains the value of the corresponding elements
of the Jacobian.
All of the row, column pairs in subset must also appear in
pattern ; i.e., they must be possibly non-zero.
pattern¶
This argument has prototype
const sparse_rc
< SizeVector >& pattern
Its row size is pattern . nr
() == m ,
and its column size is pattern . nc
() == n .
It is a sparsity pattern for the Jacobian \(J(x)\).
This argument is not used (and need not satisfy any conditions),
when work is non-empty.
coloring¶
The coloring algorithm determines which rows (reverse) or columns (forward) can be computed during the same sweep. This field has prototype
const std::string&
coloring
This value only matters when work is empty; i.e.,
after the work constructor or work . clear
() .
cppad¶
This uses a general purpose coloring algorithm written for Cppad.
colpack¶
If colpack_prefix is specified on the
CMake Command line,
you can set coloring to colpack
.
This uses a general purpose coloring algorithm that is part of Colpack.
work¶
This argument has prototype
sparse_jac_work&
work
We refer to its initial value,
and its value after work . clear
() , as empty.
If it is empty, information is stored in work .
This can be used to reduce computation when
a future call is for the same object f ,
the same member function sparse_jac_for
or sparse_jac_rev
,
and the same subset of the Jacobian.
In fact, it can be used with a different f
and a different subset provided that Jacobian sparsity pattern
for f and the sparsity pattern in subset are the same.
If any of these values change, use work . clear
() to
empty this structure.
n_color¶
The return value n_color has prototype
size_t
n_color
If sparse_jac_for
(sparse_jac_rev
) is used,
n_color is the number of first order forward directions
used to compute the requested Jacobian values.
It is also the number of colors determined by the coloring method
mentioned above.
This is proportional to the total computational work,
not counting the zero order forward sweep,
or combining multiple columns (rows) into a single sweep.
Note that if group_max == 1 ,
or if we are using sparse_jac_rev
,
n_color is equal to the number of sweeps.
Uses Forward¶
After each call to Forward ,
the object f contains the corresponding
Taylor coefficients .
After a call to sparse_jac_forward
or sparse_jac_rev
,
the zero order coefficients correspond to
f .
Forward
(0, x )
All the other forward mode coefficients are unspecified.
Example¶
The files sparse_jac_for.cpp and sparse_jac_rev.cpp
are examples and tests of sparse_jac_for
and sparse_jac_rev
.
They return true
, if they succeed, and false
otherwise.