lines 9-165 of file: include/cppad/core/rev_sparse_jac.hpp

{xrst_begin RevSparseJac}

Jacobian Sparsity Pattern: Reverse Mode
#######################################

Syntax
******

   *s* = *f* . ``RevSparseJac`` ( *q* , *r* )

*s* = *f* . ``RevSparseJac`` ( *q* , *r* , *transpose* , *dependency* )

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}^{q \times m}`,
the Jacobian of :math:`R * F( x )`
with respect to :math:`x` is

.. math::

   S(x) = R * F^{(1)} ( x )

Given a
:ref:`glossary@Sparsity Pattern`
for :math:`R`,
``RevSparseJac`` returns a sparsity pattern for the :math:`S(x)`.

f
*
The object *f* has prototype

   ``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 rows in
:math:`R \in \B{R}^{q \times m}` and the
Jacobian :math:`S(x) \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.

dependency
**********
The argument *dependency* has prototype

   ``bool`` *dependency*

If *dependency* is true,
the :ref:`dependency.cpp@Dependency Pattern`
(instead of sparsity pattern) is computed.

r
*
The argument *s* has prototype

   ``const`` *SetVector* & *r*

see :ref:`RevSparseJac@SetVector` below.

transpose false
===============
If *r* has elements of type ``bool`` ,
its size is :math:`q * m`.
If it has elements of type ``std::set<size_t>`` ,
its size is *q* and all its set elements are between
zero and :math:`m - 1`.
It specifies a
:ref:`glossary@Sparsity Pattern`
for the matrix :math:`R \in \B{R}^{q \times m}`.

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

s
*
The return value *s* has prototype

   *SetVector* *s*

see :ref:`RevSparseJac@SetVector` below.

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

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

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.

Entire Sparsity Pattern
***********************
Suppose that :math:`q = m` and
:math:`R` is the :math:`m \times m` identity matrix.
In this case,
the corresponding value for *s* is a
sparsity pattern for the Jacobian :math:`S(x) = F^{(1)} ( x )`.

Example
*******
{xrst_toc_hidden
   example/sparse/rev_sparse_jac.cpp
}
The file
:ref:`rev_sparse_jac.cpp-name`
contains an example and test of this operation.

{xrst_end RevSparseJac}