|
|
Prev | Next |
jac = f.SparseJacobian(x)
jac = f.SparseJacobian(x, p)
n_sweep = f.SparseJacobianForward(x, p, row, col, jac, work)
n_sweep = f.SparseJacobianReverse(x, p, row, col, jac, work)
f
.
We use @(@
F : \B{R}^n \rightarrow \B{R}^m
@)@ do denote the
AD function
corresponding to
f
.
The syntax above sets
jac
to the Jacobian
@[@
jac = F^{(1)} (x)
@]@
This routine takes advantage of the sparsity of the Jacobian
in order to reduce the amount of computation necessary.
If
row
and
col
are present, it also takes
advantage of the reduced set of elements of the Jacobian that
need to be computed.
One can use speed tests (e.g. speed_test
)
to verify that results are computed faster
than when using the routine Jacobian
.
f
has prototype
ADFun<Base> f
f
is not const
(see Uses Forward
below).
x
has prototype
const BaseVector& x
n
, the dimension of the
domain
space for
f
.
It specifies
that point at which to evaluate the Jacobian.
p
is optional and has prototype
const SetVector& p
bool,
its size is @(@
m * n
@)@.
If it has elements of type std::set<size_t>,
its size is @(@
m
@)@ and all its set elements are between
zero and @(@
n - 1
@)@.
It specifies a
sparsity pattern
for the Jacobian @(@
F^{(1)} (x)
@)@.
SparseJacobian
, it should be faster to calculate
p
once
(using ForSparseJac
or RevSparseJac
)
and then pass
p
to
SparseJacobian
.
Furthermore, if you specify
work
in the calling sequence,
it is not necessary to keep the sparsity pattern; see the heading
p
under the
work
description.
p
, CppAD will use the same
type of sparsity representation
(vectors of bool or vectors of std::set<size_t>)
for its internal calculations.
Otherwise, the representation
for the internal calculations is unspecified.
row
and
col
are optional and have prototype
const SizeVector& row
const SizeVector& col
row
and
col
must be possibly non-zero in the sparsity pattern.
We use @(@
K
@)@ to denote the value
jac.size()
which must also equal the size of
row
and
col
.
Furthermore,
for @(@
k = 0 , \ldots , K-1
@)@, it must hold that
@(@
row[k] < m
@)@ and @(@
col[k] < n
@)@.
jac
has prototype
BaseVector& jac
row
and
col
are not present,
the size of
jac
is @(@
m * n
@)@ and
for @(@
i = 0 , \ldots , m-1
@)@,
@(@
j = 0 , \ldots , n-1
@)@,
@[@
jac [ i * n + j ] = \D{ F_i }{ x_j } (x)
@]@
row
and
col
are present,
we use @(@
K
@)@ to denote the size of
jac
.
The input value of its elements does not matter.
Upon return, for @(@
k = 0 , \ldots , K - 1
@)@,
@[@
jac [ k ] = \D{ F_i }{ x_j } (x)
\; , \;
\; {\rm where} \;
i = row[k]
\; {\rm and } \;
j = col[k]
@]@
sparse_jacobian_work& work
SparseJacobianForward and SparseJacobianReverse.
During its the first use, information is stored in
work
.
This is used to reduce the work done by future calls to the same mode
(forward or reverse),
the same
f
,
p
,
row
, and
col
.
If a future call is for a different mode,
or any of these values have changed,
you must first call
work.clear()
to inform CppAD that this information needs to be recomputed.
std::string work.color_method
clear())
is "cppad".
If colpack_prefix
is specified on the
cmake command
line,
you can set this method to "colpack".
This value only matters on the first call to sparse_jacobian
that follows the
work
constructor or a call to
work.clear()
.
work
is present, and it is not the first call after
its construction or a clear,
the sparsity pattern
p
is not used.
This enables one to free the sparsity pattern
and still compute corresponding sparse Jacobians.
n_sweep
has prototype
size_t n_sweep
SparseJacobianForward (SparseJacobianReverse) is used,
n_sweep
is the number of first order forward (reverse) sweeps
used to compute the requested Jacobian values.
(This is also the number of colors determined by the coloring method
mentioned above).
This is proportional to the total work that SparseJacobian does,
not counting the zero order forward sweep,
or the work to combine multiple columns (rows) into a single sweep.
BaseVector
must be a SimpleVector
class with
elements of type
Base
.
The routine CheckSimpleVector
will generate an error message
if this is not the case.
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.
The routine CheckSimpleVector
will generate an error message
if this is not the case.
SetVector
has elements of std::set<size_t>,
then
p[i]
must return a reference (not a copy) to the
corresponding set.
According to section 26.3.2.3 of the 1998 C++ standard,
std::valarray< std::set<size_t> > does not satisfy
this condition.
SizeVector
must be a SimpleVector
class with
elements of type
size_t.
The routine CheckSimpleVector
will generate an error message
if this is not the case.
f
contains the corresponding
Taylor coefficients
.
After a call to any of the sparse Jacobian routines,
the zero order Taylor coefficients correspond to
f.Forward(0, x)
and the other coefficients are unspecified.
After SparseJacobian,
the previous calls to Forward
are undefined.
sparse_jacobian.
It return true, if it succeeds and false otherwise.