------------------------------------------------------ lines 9-214 of file: include/cppad/core/sparse_jac.hpp ------------------------------------------------------ {xrst_begin sparse_jac} {xrst_spell nr rc rcv } Computing Sparse Jacobians ########################## Syntax ****** | *n_color* = *f* . ``sparse_jac_for`` ( | |tab| *group_max* , *x* , *subset* , *pattern* , *coloring* , *work* | ) | *n_color* = *f* . ``sparse_jac_rev`` ( | |tab| *x* , *subset* , *pattern* , *coloring* , *work* | ) Purpose ******* We use :math:`F : \B{R}^n \rightarrow \B{R}^m` to denote the function corresponding to *f* . Here *n* is the :ref:`fun_property@Domain` size, and *m* is the :ref:`fun_property@Range` size, or *f* . The syntax above takes advantage of sparsity when computing the Jacobian .. math:: J(x) = F^{(1)} (x) In the sparse case, this should be faster and take less memory than :ref:`Jacobian-name` . We use the notation :math:`J_{i,j} (x)` to denote the partial of :math:`F_i (x)` with respect to :math:`x_j`. SizeVector ********** The type *SizeVector* is a :ref:`SimpleVector-name` class with :ref:`elements of type` ``size_t`` . BaseVector ********** The type *BaseVector* is a :ref:`SimpleVector-name` class with :ref:`elements of type` ``size_t`` . sparse_jac_for ************** This function uses first order forward mode sweeps :ref:`forward_one-name` to compute multiple columns of the Jacobian at the same time. sparse_jac_rev ************** This uses function first order reverse mode sweeps :ref:`reverse_one-name` to compute multiple rows of the Jacobian at the same time. f * This object has prototype ``ADFun`` < *Base* > *f* Note that the Taylor coefficients stored in *f* are affected by this operation; see :ref:`sparse_jac@Uses Forward` below. group_max ********* This argument has prototype ``size_t`` *group_max* and must be greater than zero. It specifies the maximum number of colors to group during a single forward sweep. If a single color is in a group, a single direction for of first order forward mode :ref:`forward_one-name` is used for each color. If multiple colors are in a group, the multiple direction for of first order forward mode :ref:`forward_dir-name` is used with one direction for each color. This uses separate memory for each direction (more memory), but my be significantly faster. x * This argument has prototype ``const`` *BaseVector* & *x* and its size is *n* . It specifies the point at which to evaluate the Jacobian :math:`J(x)`. subset ****** This argument has prototype ``sparse_rcv`` < *SizeVector* , *BaseVector* >& *subset* Its row size is *subset* . ``nr`` () == *m* , and its column size is *subset* . ``nc`` () == *n* . It specifies which elements of the Jacobian are computed. The input value of its value vector *subset* . ``val`` () does not matter. Upon return it contains the value of the corresponding elements of the Jacobian. All of the row, column pairs in *subset* must also appear in *pattern* ; i.e., they must be possibly non-zero. pattern ******* This argument has prototype ``const sparse_rc`` < *SizeVector* >& *pattern* Its row size is *pattern* . ``nr`` () == *m* , and its column size is *pattern* . ``nc`` () == *n* . It is a sparsity pattern for the Jacobian :math:`J(x)`. This argument is not used (and need not satisfy any conditions), when :ref:`sparse_jac@work` is non-empty. coloring ******** The coloring algorithm determines which rows (reverse) or columns (forward) can be computed during the same sweep. This field has prototype ``const std::string&`` *coloring* This value only matters when work is empty; i.e., after the *work* constructor or *work* . ``clear`` () . cppad ===== This uses a general purpose coloring algorithm written for Cppad. colpack ======= If :ref:`colpack_prefix-name` is specified on the :ref:`cmake@CMake Command` line, you can set *coloring* to ``colpack`` . This uses a general purpose coloring algorithm that is part of Colpack. work **** This argument has prototype ``sparse_jac_work&`` *work* We refer to its initial value, and its value after *work* . ``clear`` () , as empty. If it is empty, information is stored in *work* . This can be used to reduce computation when a future call is for the same object *f* , the same member function ``sparse_jac_for`` or ``sparse_jac_rev`` , and the same subset of the Jacobian. In fact, it can be used with a different *f* and a different *subset* provided that Jacobian sparsity pattern for *f* and the sparsity pattern in *subset* are the same. If any of these values change, use *work* . ``clear`` () to empty this structure. n_color ******* The return value *n_color* has prototype ``size_t`` *n_color* If ``sparse_jac_for`` (``sparse_jac_rev`` ) is used, *n_color* is the number of first order forward directions used to compute the requested Jacobian values. It is also the number of colors determined by the coloring method mentioned above. This is proportional to the total computational work, not counting the zero order forward sweep, or combining multiple columns (rows) into a single sweep. Note that if *group_max* == 1 , or if we are using ``sparse_jac_rev`` , *n_color* is equal to the number of sweeps. Uses Forward ************ After each call to :ref:`Forward-name` , the object *f* contains the corresponding :ref:`Taylor coefficients` . After a call to ``sparse_jac_forward`` or ``sparse_jac_rev`` , the zero order coefficients correspond to *f* . ``Forward`` (0, *x* ) All the other forward mode coefficients are unspecified. Example ******* {xrst_toc_hidden example/sparse/sparse_jac_for.cpp example/sparse/sparse_jac_rev.cpp } The files :ref:`sparse_jac_for.cpp-name` and :ref:`sparse_jac_rev.cpp-name` are examples and tests of ``sparse_jac_for`` and ``sparse_jac_rev`` . They return ``true`` , if they succeed, and ``false`` otherwise. {xrst_end sparse_jac}