CppAD: A C++ Algorithmic Differentiation Package  20171217
sparse_jac_fun.hpp
Go to the documentation of this file.
3
4 /* --------------------------------------------------------------------------
6
8 the terms of the
9  Eclipse Public License Version 1.0.
10
11 A copy of this license is included in the COPYING file of this distribution.
13 -------------------------------------------------------------------------- */
14 /*
15 $begin sparse_jac_fun$$16 spell 17 Jacobian 18 jac 19 cppad 20 hpp 21 fp 22 CppAD 23 namespace 24 const 25 bool 26 exp 27 arg 28$$ 29 30$section Evaluate a Function That Has a Sparse Jacobian$$31 mindex sparse_jac_fun$$
32
33
34 $head Syntax$$35 codei%# include <cppad/speed/sparse_jac_fun.hpp> 36 %$$ 37$codei%sparse_jac_fun(%m%, %n%, %x%, %row%, %col%, %p%, %fp%)%$$38 39 head Purpose$$
40 This routine evaluates
41 $latex f(x)$$and latex f^{(1)} (x)$$ 42 where the Jacobian$latex f^{(1)} (x)$$is sparse. 43 The function latex f : \B{R}^n \rightarrow \B{R}^m$$ only depends on the
44 size and contents of the index vectors $icode row$$and icode col$$. 45 The non-zero entries in the Jacobian of this function have 46 one of the following forms: 47$latex $48 \D{ f[row[k]]}{x[col[k]]} 49$ $$50 for some latex k$$ between zero and $latex K-1$$. 51 All the other terms of the Jacobian are zero. 52 53 head Inclusion$$ 54 The template function$code sparse_jac_fun$$55 is defined in the code CppAD$$ namespace by including
56 the file $code cppad/speed/sparse_jac_fun.hpp$$57 (relative to the CppAD distribution directory). 58 59 head Float$$ 60 The type$icode Float$$must be a cref NumericType$$.
61 In addition, if $icode y$$and icode z$$ are$icode Float$$objects, 62 codei% 63 %y% = exp(%z%) 64 %$$
65 must set the $icode y$$equal the exponential of icode z$$, i.e., 66 the derivative of$icode y$$with respect to icode z$$ is equal to $icode y$$. 67 68 head FloatVector$$ 69 The type$icode FloatVector$$is any 70 cref SimpleVector$$, or it can be a raw pointer,
71 with elements of type $icode Float$$. 72 73 head n$$ 74 The argument$icode n$$has prototype 75 codei% 76 size_t %n% 77 %$$
78 It specifies the dimension for the domain space for $latex f(x)$$. 79 80 head m$$ 81 The argument$icode m$$has prototype 82 codei% 83 size_t %m% 84 %$$
85 It specifies the dimension for the range space for $latex f(x)$$. 86 87 head x$$ 88 The argument$icode x$$has prototype 89 codei% 90 const %FloatVector%& %x% 91 %$$
92 It contains the argument value for which the function,
93 or its derivative, is being evaluated.
94 We use $latex n$$to denote the size of the vector icode x$$. 95 96$head row$$97 The argument icode row$$ has prototype
98 $codei% 99 const CppAD::vector<size_t>& %row% 100 %$$101 It specifies indices in the range of latex f(x)$$ for non-zero components 102 of the Jacobian 103 (see$cref/purpose/sparse_hes_fun/Purpose/$$above). 104 The value latex K$$ is defined by $icode%K% = %row%.size()%$$. 105 All the elements of icode row$$ must be between zero and$icode%m%-1%$$. 106 107 head col$$
108 The argument $icode col$$has prototype 109 codei% 110 const CppAD::vector<size_t>& %col% 111 %$$ 112 and its size must be$latex K$$; i.e., the same as icode row$$.
113 It specifies the component of $latex x$$for 114 the non-zero Jacobian terms. 115 All the elements of icode col$$ must be between zero and$icode%n%-1%$$. 116 117 head p$$
118 The argument $icode p$$has prototype 119 codei% 120 size_t %p% 121 %$$ 122 It is either zero or one and 123 specifies the order of the derivative of$latex f$$124 that is being evaluated, i.e., latex f^{(p)} (x)$$ is evaluated.
125
126 $head fp$$127 The argument icode fp$$ has prototype 128$codei%
129  %FloatVector%& %fp%
130 %$$131 If icode%p% = 0%$$, it size is $icode m$$132 otherwise its size is icode K$$. 133 The input value of the elements of$icode fp$$does not matter. 134 135 subhead Function$$
136 If $icode p$$is zero, icode fp$$ has size$latex m$$and 137 codei%(%fp%[0]%, ... , %fp%[%m%-1])%$$ is the value of $latex f(x)$$. 138 139 subhead Jacobian$$ 140 If$icode p$$is one, icode fp$$ has size $icode K$$and 141 for latex k = 0 , \ldots , K-1$$, 142$latex $143 \D{f[ \R{row}[i] ]}{x[ \R{col}[j] ]} = fp [k] 144$ $$145 146 children% 147 speed/example/sparse_jac_fun.cpp% 148 omh/sparse_jac_fun.omh 149 %$$
150
151 $head Example$$152 The file 153 cref sparse_jac_fun.cpp$$ 154 contains an example and test of$code sparse_jac_fun.hpp$$. 155 It returns true if it succeeds and false otherwise. 156 157 head Source Code$$
158 The file
159 $cref sparse_jac_fun.hpp$$160 contains the source code for this template function. 161 162$end
163 ------------------------------------------------------------------------------
164 */
165 // BEGIN C++
169
170 // following needed by gcc under fedora 17 so that exp(double) is defined
172
174  template <class Float, class FloatVector>
176  size_t m ,
177  size_t n ,
178  const FloatVector& x ,
181  size_t p ,
182  FloatVector& fp )
183  {
184  // check numeric type specifications
185  CheckNumericType<Float>();
186  // check value of p
188  p == 0 || p == 1,
189  "sparse_jac_fun: p != 0 and p != 1"
190  );
191  size_t K = row.size();
193  K >= m,
194  "sparse_jac_fun: row.size() < m"
195  );
196  size_t i, j, k;
197
198  if( p == 0 )
199  for(i = 0; i < m; i++)
200  fp[i] = Float(0);
201
202  Float t;
203  for(k = 0; k < K; k++)
204  { i = row[k];
205  j = col[k];
206  t = exp( x[j] * x[j] / 2.0 );
207  switch(p)
208  {
209  case 0:
210  fp[i] += t;
211  break;
212
213  case 1:
214  fp[k] = t * x[j];
215  break;
216  }
217  }
218  }
219 }
220 // END C++
221 # endif
void sparse_jac_fun(size_t m, size_t n, const FloatVector &x, const CppAD::vector< size_t > &row, const CppAD::vector< size_t > &col, size_t p, FloatVector &fp)