$\newcommand{\W}[1]{ \; #1 \; } \newcommand{\R}[1]{ {\rm #1} } \newcommand{\B}[1]{ {\bf #1} } \newcommand{\D}[2]{ \frac{\partial #1}{\partial #2} } \newcommand{\DD}[3]{ \frac{\partial^2 #1}{\partial #2 \partial #3} } \newcommand{\Dpow}[2]{ \frac{\partial^{#1}}{\partial {#2}^{#1}} } \newcommand{\dpow}[2]{ \frac{ {\rm d}^{#1}}{{\rm d}\, {#2}^{#1}} }$
Evaluate a Function That Has a Sparse Jacobian

Syntax
# include <cppad/speed/sparse_jac_fun.hpp>  sparse_jac_fun(m, n, x, row, col, p, fp)

Purpose
This routine evaluates $f(x)$ and $f^{(1)} (x)$ where the Jacobian $f^{(1)} (x)$ is sparse. The function $f : \B{R}^n \rightarrow \B{R}^m$ only depends on the size and contents of the index vectors row and col . The non-zero entries in the Jacobian of this function have one of the following forms: $$\D{ f[row[k]]}{x[col[k]]}$$ for some $k$ between zero and $K-1$. All the other terms of the Jacobian are zero.

Inclusion
The template function sparse_jac_fun is defined in the CppAD namespace by including the file cppad/speed/sparse_jac_fun.hpp (relative to the CppAD distribution directory).

Float
The type Float must be a NumericType . In addition, if y and z are Float objects,       y = exp(z)  must set the y equal the exponential of z , i.e., the derivative of y with respect to z is equal to y .

FloatVector
The type FloatVector is any SimpleVector , or it can be a raw pointer, with elements of type Float .

n
The argument n has prototype       size_t n  It specifies the dimension for the domain space for $f(x)$.

m
The argument m has prototype       size_t m  It specifies the dimension for the range space for $f(x)$.

x
The argument x has prototype       const FloatVector& x  It contains the argument value for which the function, or its derivative, is being evaluated. We use $n$ to denote the size of the vector x .

row
The argument row has prototype        const CppAD::vector<size_t>& row  It specifies indices in the range of $f(x)$ for non-zero components of the Jacobian (see purpose above). The value $K$ is defined by K = row.size() . All the elements of row must be between zero and m-1 .

col
The argument col has prototype        const CppAD::vector<size_t>& col  and its size must be $K$; i.e., the same as row . It specifies the component of $x$ for the non-zero Jacobian terms. All the elements of col must be between zero and n-1 .

p
The argument p has prototype       size_t p  It is either zero or one and specifies the order of the derivative of $f$ that is being evaluated, i.e., $f^{(p)} (x)$ is evaluated.

fp
The argument fp has prototype       FloatVector& fp  If p = 0 , it size is m otherwise its size is K . The input value of the elements of fp does not matter.

Function
If p is zero, fp has size $m$ and (fp[0], ... , fp[m-1]) is the value of $f(x)$.

Jacobian
If p is one, fp has size K and for $k = 0 , \ldots , K-1$, $$\D{f[ \R{row}[i] ]}{x[ \R{col}[j] ]} = fp [k]$$

Example
The file sparse_jac_fun.cpp contains an example and test of sparse_jac_fun.hpp. It returns true if it succeeds and false otherwise.

Source Code
The file sparse_jac_fun.hpp contains the source code for this template function.