---------------------------------------------------------------------
lines 8-116 of file: include/cppad/core/atomic/three/jac_sparsity.hpp
---------------------------------------------------------------------

{xrst_begin atomic_three_jac_sparsity}

Atomic Function Jacobian Sparsity Patterns
##########################################

Syntax
******
| *ok* = *afun* . ``jac_sparsity`` (
| |tab| *parameter_x* , *type_x* , *dependency* , *select_x* , *select_y* , *pattern_out*
| )

Prototype
*********
{xrst_literal
   // BEGIN_PROTOTYPE
   // END_PROTOTYPE
}

Implementation
**************
This function must be defined if
:ref:`atomic_three_ctor@atomic_user@afun` is
used to define an :ref:`ADFun-name` object *f* ,
and Jacobian sparsity patterns are computed for *f* .
(Computing Hessian sparsity patterns and optimizing
requires Jacobian sparsity patterns.)

Base
****
See :ref:`atomic_three_afun@Base` .

parameter_x
***********
See :ref:`atomic_three_define@parameter_x` .

type_x
******
See :ref:`atomic_three_define@type_x` .

dependency
**********
If *dependency* is true,
then *pattern_out* is a
:ref:`dependency.cpp@Dependency Pattern`
for this atomic function.
Otherwise it is a
:ref:`glossary@Sparsity Pattern` for the
derivative of the atomic function.

select_x
********
This argument has size equal to the number of arguments to this
atomic function; i.e. the size of *ax* .
It specifies which domain components are included in
the calculation of *pattern_out* .
If *select_x* [ *j* ] is false, then there will be no indices
*k* such that

   *pattern_out* . ``col`` ()[ *k* ] == *j*

.

select_y
********
This argument has size equal to the number of results to this
atomic function; i.e. the size of *ay* .
It specifies which range components are included in
the calculation of *pattern_out* .
If *select_y* [ *i* ] is false, then there will be no indices
*k* such that

   *pattern_out* . ``row`` ()[ *k* ] == *i*

.

pattern_out
***********
This input value of *pattern_out* does not matter.
Upon return it is a
dependency or sparsity pattern for the Jacobian of :math:`g(x)`,
the function corresponding to
:ref:`atomic_three_ctor@atomic_user@afun` ;
*dependency* above.
To be specific, there are non-negative indices
*i* , *j* , *k* such that

| |tab| *pattern_out* . ``row`` ()[ *k* ] == *i*
| |tab| *pattern_out* . ``col`` ()[ *k* ] == *j*

if and only if
*select_x* [ *j* ] is true,
*select_y* [ *j* ] is true,
and :math:`g_i(x)` depends on the value of :math:`x_j`
(and the partial of :math:`g_i(x)` with respect to
:math:`x_j` is possibly non-zero).

ok
**
If this calculation succeeded, *ok* is true.
Otherwise it is false.
{xrst_toc_hidden
   example/atomic_three/jac_sparsity.cpp
}
Examples
********
The file :ref:`atomic_three_jac_sparsity.cpp-name` contains an example and test
that uses this routine.

{xrst_end atomic_three_jac_sparsity}