------------------------------------------------------------
lines 8-157 of file: include/cppad/core/subgraph_reverse.hpp
------------------------------------------------------------

{xrst_begin subgraph_reverse}
{xrst_spell
   dw
   subgraphs
}

Reverse Mode Using Subgraphs
############################

Syntax
******
| *f* . ``subgraph_reverse`` ( *select_domain* )
| *f* . ``subgraph_reverse`` ( *q* , *ell* , *col* , *dw* )
| *f* . ``clear_subgraph`` ()

Purpose
*******
We use :math:`F : \B{R}^n \rightarrow \B{R}^m` to denote the
:ref:`glossary@AD Function` corresponding to *f* .
Reverse mode computes the derivative of the :ref:`Forward-name` mode
:ref:`Taylor coefficients<glossary@Taylor Coefficient>`
with respect to the domain variable :math:`x`.

Notation
********
We use the reverse mode
:ref:`reverse_any@Notation` with the following change:
the vector
:ref:`reverse_any@Notation@w^(k)` is defined

.. math::

   w_i^{(k)} = \left\{ \begin{array}{ll}
      1 & {\rm if} \; k = q-1 \; \R{and} \; i = \ell
      \\
      0       & {\rm otherwise}
   \end{array} \right.

BaseVector
**********
The type *BaseVector* must be a :ref:`SimpleVector-name` class with
:ref:`elements of type<SimpleVector@Elements of Specified Type>`
*Base* .
The routine :ref:`CheckSimpleVector-name` will generate an error message
if this is not the case.

BoolVector
**********
The type *BoolVector* is a :ref:`SimpleVector-name` class with
:ref:`elements of type<SimpleVector@Elements of Specified Type>`
``bool`` .

SizeVector
**********
The type *SizeVector* is a :ref:`SimpleVector-name` class with
:ref:`elements of type<SimpleVector@Elements of Specified Type>`
``size_t`` .

select_domain
*************
The argument *select_domain* has prototype

   ``const`` *BoolVector* & *select_domain*

It has size :math:`n` and specifies which independent variables
to include in future ``subgraph_reverse`` calculations.
If *select_domain* [ *j* ] is false,
it is assumed that :math:`u^{(k)}_j = 0` for :math:`k > 0`; i.e.,
the *j*-th component of the Taylor coefficient for :math:`x`,
with order greater that zero, are zero; see
:ref:`reverse_any@Notation@u^(k)` .

q
*
The argument *q* has prototype

   ``size_t`` *q*

and specifies the number of Taylor coefficient orders to be differentiated.

ell
***
The argument *ell* has prototype

   ``size_t`` *ell*

and specifies the dependent variable index that we are computing
the derivatives for; i.e. :math:`\ell`.
This index can only be used once per, and after, a call that selects
the independent variables using *select_domain* .

col
***
This argument *col* has prototype

   *SizeVector* *col*

The input size and value of its elements do not matter.
The *col* . ``resize`` member function is used to change its size
to the number the number of possible non-zero derivative components.
For each *c* ,

| |tab| *select_domain* [ *col* [ *c* ] ] == ``true``
| |tab| *col* [ *c* +1] >= *col* [ *c* ]

and the derivative with respect to the *j*-th independent
variable is possibly non-zero where
*j* = *col* [ *c* ] .

dw
**
The argument *dw* has prototype

   *Vector* *dw*

Its input size and value does not matter.
Upon return,
it is a vector with size :math:`n \times q`.
For :math:`c = 0 , \ldots , %col%.size()-1`,
and :math:`k = 0, \ldots , q-1`,

.. math::

   dw[ j * q + k ] = W^{(1)} ( x )_{j,k}

is the derivative of the specified Taylor coefficients w.r.t the *j*-th
independent variable where *j* = *col* [ *c* ] .
Note that this corresponds to the :ref:`reverse_any-name` convention when
:ref:`reverse_any@w` has size *m* * *q* .

clear_subgraph
**************
Calling this routine will free memory that holds
information between calls to subgraph calculations so that
it does not need to be recalculated.
(This memory is automatically freed when *f* is deleted.)
You cannot free this memory between calls that select the domain
and corresponding calls that compute reverse mode derivatives.
Some of this information is also used by :ref:`subgraph_sparsity-name` .

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

{xrst_end subgraph_reverse}