----------------------------------------------------------
lines 9-184 of file: include/cppad/core/rev_sparse_hes.hpp
----------------------------------------------------------

{xrst_begin RevSparseHes}

Hessian Sparsity Pattern: Reverse Mode
######################################

Syntax
******
| *h* = *f* . ``RevSparseHes`` ( *q* , *s* )
| *h* = *f* . ``RevSparseHes`` ( *q* , *s* , *transpose* )

Purpose
*******
We use :math:`F : \B{R}^n \rightarrow \B{R}^m` to denote the
:ref:`glossary@AD Function` corresponding to *f* .
For a fixed matrix :math:`R \in \B{R}^{n \times q}`
and a fixed vector :math:`S \in \B{R}^{1 \times m}`,
we define

.. math::
   :nowrap:

   \begin{eqnarray}
   H(x)
   & = & \partial_x \left[ \partial_u S * F[ x + R * u ] \right]_{u=0}
   \\
   & = & R^\R{T} * (S * F)^{(2)} ( x )
   \\
   H(x)^\R{T}
   & = & (S * F)^{(2)} ( x ) * R
   \end{eqnarray}

Given a
:ref:`glossary@Sparsity Pattern`
for the matrix :math:`R` and the vector :math:`S`,
``RevSparseHes`` returns a sparsity pattern for the :math:`H(x)`.

f
*
The object *f* has prototype

   ``const ADFun`` < *Base* > *f*

x
*
If the operation sequence in *f* is
:ref:`glossary@Operation@Independent` of
the independent variables in :math:`x \in \B{R}^n`,
the sparsity pattern is valid for all values of
(even if it has :ref:`CondExp-name` or :ref:`VecAD-name` operations).

q
*
The argument *q* has prototype

   ``size_t`` *q*

It specifies the number of columns in :math:`R \in \B{R}^{n \times q}`
and the number of rows in :math:`H(x) \in \B{R}^{q \times n}`.
It must be the same value as in the previous :ref:`ForSparseJac-name` call

   *f* . ``ForSparseJac`` ( *q* , *r* , *r_transpose* )

Note that if *r_transpose* is true, *r* in the call above
corresponding to :math:`R^\R{T} \in \B{R}^{q \times n}`

transpose
*********
The argument *transpose* has prototype

   ``bool`` *transpose*

The default value ``false`` is used when *transpose* is not present.

r
*
The matrix :math:`R` is specified by the previous call

   *f* . ``ForSparseJac`` ( *q* , *r* , *transpose* )

see :ref:`ForSparseJac@r` .
The type of the elements of
:ref:`RevSparseHes@SetVector` must be the
same as the type of the elements of *r* .

s
*
The argument *s* has prototype

   ``const`` *SetVector* & *s*

(see :ref:`RevSparseHes@SetVector` below)
If it has elements of type ``bool`` ,
its size is :math:`m`.
If it has elements of type ``std::set<size_t>`` ,
its size is one and all the elements of *s* [0]
are between zero and :math:`m - 1`.
It specifies a
:ref:`glossary@Sparsity Pattern`
for the vector *S* .

h
*
The result *h* has prototype

   *SetVector* & *h*

(see :ref:`RevSparseHes@SetVector` below).

transpose false
===============
If *h* has elements of type ``bool`` ,
its size is :math:`q * n`.
If it has elements of type ``std::set<size_t>`` ,
its size is :math:`q` and all the set elements are between
zero and *n* ``-1`` inclusive.
It specifies a
:ref:`glossary@Sparsity Pattern`
for the matrix :math:`H(x)`.

transpose true
==============
If *h* has elements of type ``bool`` ,
its size is :math:`n * q`.
If it has elements of type ``std::set<size_t>`` ,
its size is :math:`n` and all the set elements are between
zero and *q* ``-1`` inclusive.
It specifies a
:ref:`glossary@Sparsity Pattern`
for the matrix :math:`H(x)^\R{T}`.

SetVector
*********
The type *SetVector* must be a :ref:`SimpleVector-name` class with
:ref:`elements of type<SimpleVector@Elements of Specified Type>`
``bool`` or ``std::set<size_t>`` ;
see :ref:`glossary@Sparsity Pattern` for a discussion
of the difference.
The type of the elements of
:ref:`RevSparseHes@SetVector` must be the
same as the type of the elements of *r* .

Entire Sparsity Pattern
***********************
Suppose that :math:`q = n` and
:math:`R \in \B{R}^{n \times n}` is the :math:`n \times n` identity matrix.
Further suppose that the :math:`S` is the *k*-th
:ref:`glossary@Elementary Vector` ; i.e.

.. math::

   S_j = \left\{ \begin{array}{ll}
      1  & {\rm if} \; j = k
      \\
      0  & {\rm otherwise}
   \end{array} \right.

In this case,
the corresponding value *h* is a
sparsity pattern for the Hessian matrix
:math:`F_k^{(2)} (x) \in \B{R}^{n \times n}`.

Example
*******
{xrst_toc_hidden
   example/sparse/rev_sparse_hes.cpp
   example/sparse/sparsity_sub.cpp
}
The file
:ref:`rev_sparse_hes.cpp-name`
contains an example and test of this operation.
The file
:ref:`sparsity_sub.cpp<sparsity_sub.cpp@RevSparseHes>`
contains an example and test of using ``RevSparseHes``
to compute the sparsity pattern for a subset of the Hessian.

{xrst_end RevSparseHes}