Prev

Next

Index-> contents reference index search external

Up-> CppAD ADFun Drivers sparse_hessian

CppAD-> Install Introduction AD ADFun multi_thread library cppad_ipopt_nlp Example preprocessor Appendix

ADFun-> Independent FunConstruct Dependent abort_recording seq_property FunEval Drivers FunCheck optimize

Drivers-> Jacobian ForOne RevOne Hessian ForTwo RevTwo sparse_jacobian sparse_hessian

sparse_hessian-> sparse_hessian.cpp

Headings-> Syntax Purpose f x w p row, col hes work n_sweep VectorBase VectorSet ---..Restrictions VectorSize Uses Forward Example

Sparse Hessian: Easy Driver
Syntax
hes = f.SparseHessian(x, w)
hes = f.SparseHessian(x, w, p)
n_sweep = f.SparseHessian(x, w, p, row, col, hes, work)

Purpose
We use $\mathit{n}$ for the domain size, and $\mathit{m}$ for the range size of f . We use $\mathit{F}:{\mathbf{R}}^{\mathit{n}}\to {\mathbf{R}}^{\mathit{m}}$ do denote the AD function corresponding to f . The syntax above sets hes to the Hessian $$\mathit{H}(\mathit{x})=\frac{{\mathrm{d}}^2}{\mathrm{d}{\mathit{x}}^2}\sum _{\mathit{i}=1}^{\mathit{m}}{\mathit{w}}_{\mathit{i}}{\mathit{F}}_{\mathit{i}}(\mathit{x})$$ This routine takes advantage of the sparsity of the Hessian 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 Hessian 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 Hessian .

f
The object f has prototype
     ADFun<Base> f
Note that the ADFun object f is not const (see Uses Forward below).

x
The argument x has prototype
     const VectorBase& x
(see VectorBase below) and its size must be equal to n , the dimension of the domain space for f . It specifies that point at which to evaluate the Hessian.

w
The argument w has prototype
     const VectorBase& w
and size $\mathit{m}$ . It specifies the value of ${\mathit{w}}_{\mathit{i}}$ in the expression for hes . The more components of $\mathit{w}$ that are identically zero, the more sparse the resulting Hessian may be (and hence the more efficient the calculation of hes may be).

p
The argument p is optional and has prototype
     const VectorSet& p
(see VectorSet below) If it has elements of type bool, its size is $\mathit{n}*\mathit{n}$ . If it has elements of type std::set<size_t>, its size is $\mathit{n}$ and all its set elements are between zero and $\mathit{n}-1$ . It specifies a sparsity pattern for the Hessian $\mathit{H}(\mathit{x})$ .

If this sparsity pattern does not change between calls to SparseHessian , it should be faster to calculate p once and pass this argument to SparseHessian . In addition, if you specify 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, col
The arguments row and col are optional and have prototype
     const VectorSize& row
     const VectorSize& col
(see VectorSize below). They specify which rows and columns of $\mathit{H}(\mathit{x})$ are returned and in what order. We use $\mathit{K}$ to denote the value hes.size() which must also equal the size of row and col . Furthermore, for $\mathit{k}=0,\dots ,\mathit{K}-1$ , it must hold that $\mathit{row}[\mathit{k}]<\mathit{n}$ and $\mathit{col}[\mathit{k}]<\mathit{n}$ . In addition, all of the $(\mathit{row}[\mathit{k}],\mathit{col}[\mathit{k}])$ pairs must correspond to a true value in the sparsity pattern p .

hes
The result hes has prototype
     VectorBase hes
In the case where row and col are not present, the size of hes is $\mathit{n}*\mathit{n}$ and its size is $\mathit{n}*\mathit{n}$ . In this case, for $\mathit{i}=0,\dots ,\mathit{n}-1$ and $\mathit{ell}=0,\dots ,\mathit{n}-1$ $$\mathit{hes}[\mathit{j}*\mathit{n}+\ell ]=\frac{{\partial }^2{\mathit{w}}^{\mathrm{T}}\mathit{F}}{\partial {\mathit{x}}_{\mathit{j}}\partial {\mathit{x}}_{\ell }}(\mathit{x})$$

In the case where the arguments row and col are present, we use $\mathit{K}$ to denote the size of hes . The input value of its elements does not matter. Upon return, for $\mathit{k}=0,\dots ,\mathit{K}-1$ , $$\mathit{hes}[\mathit{k}]=\frac{{\partial }^2{\mathit{w}}^{\mathrm{T}}\mathit{F}}{\partial {\mathit{x}}_{\mathit{j}}\partial {\mathit{x}}_{\ell }}(\mathit{x}),\mathrm{where}\mathit{j}=\mathit{row}[\mathit{k}]\mathrm{and}\ell =\mathit{col}[\mathit{k}]$$
work
If this argument is present, it has prototype
     sparse_hessian_work& work
This object can only be used with the routines SparseHessian. During its the first use, information is stored in work . This is used to reduce the work done by future calls to SparseHessian with the same f , p , row , and col . If a future call is make where any of these values have changed, you must first call work.clear() to inform CppAD that this information needs to be recomputed.

n_sweep
The return value n_sweep has prototype
     size_t n_sweep
It is the number of first order forward sweeps used to compute the requested Hessian values. Each first forward sweep is followed by a second order reverse sweep so it is also the number of reverse sweeps. This is proportional to the total work that SparseHessian does, not counting the zero order forward sweep, or the work to combine multiple columns into a single forward-reverse sweep pair.

VectorBase
The type VectorBase must be a SimpleVector class with elements of type Base . The routine CheckSimpleVector will generate an error message if this is not the case.

VectorSet
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. The routine CheckSimpleVector will generate an error message if this is not the case.

Restrictions
If VectorSet 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.

VectorSize
The type VectorSize 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.

Uses Forward
After each call to Forward , the object f contains the corresponding Taylor coefficients . After SparseHessian, the previous calls to Forward are undefined.

Example
The routine sparse_hessian.cpp is examples and tests of sparse_hessian. It return true, if it succeeds and false otherwise.

---

Input File: cppad/local/sparse_hessian.hpp